SugarCRM SupportDocumentationSugar DeveloperSugar Developer Guide 7.7ArchitectureCLI
This page refers to beta functionality. Please be advised that the content of this page is subject to change.

CLI

Overview

As of Sugar 7.7.1, Sugar includes a beta command line interface tool built using the Symfony Console Framework. Sugar's CLI is intended to be an administrator or developer level power tool to execute PHP code in the context of Sugar's code base. These commands are version specific and can be executed on a preinstalled Sugar instance or on an installed Sugar instance. Sugar's CLI is not intended to be used as a tool to interact remotely with an instance nor is it designed to interact with multiple instances. 

Commands

Sugar Commands are an implementation of Console Commands. They extend the base console classes to execute Sugar specific actions. Each instance of Sugar is shipped with a list of predefined commands. The current list of commands is shown below.

Command Description
help Displays help for a command
list Lists commands
elastic:indices Show Elasticsearch index statistics
elastic:queue Show Elasticsearch queue statistics
elastic:routing Show Elasticsearch index routing
search:fields Show search engine enabled fields
search:reindex Schedule SearchEngine reindex
search:status Show search engine availability and enabled modules

Note : For advanced users, a bash autocompletion script for CLI is located at ./src/Console/Resources/sugarcrm-bash-completion for inclusion in  ~/.bashrc. More details on using the script can be found in the file's header comments.

Usage

The command executable, located at ./bin/sugarcrm, is executed from the root of the Sugar instance. The command signature is shown below:

php bin/sugarcrm <command> [options] [arguments]

Help

The command console has built-in help documentation. If you pass in a command that isn't found, you will be shown the default help documentation. 

SugarCRM Console version <version>

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
      --profile         Display timing and memory usage information
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  help             Displays help for a command
  list             Lists commands
 elastic
  elastic:indices  Show Elasticsearch index statistics
  elastic:queue    Show Elasticsearch queue statistics
  elastic:routing  Show Elasticsearch index routing
 search
  search:fields    Show search engine enabled fields
  search:reindex   Schedule SearchEngine reindex
  search:status    Show search engine availability and enabled modules

 Additional help documentation is also available for individual commands. Some examples of accessing the help are shown below. 

Passing the word "help" before a command name:

php bin/sugarcrm help <command>

Passing the "-h" option:

php bin/sugarcrm <command> -h

An example of the list help documentation is shown below.

Usage:
  list [options] [--] []

Arguments:
  namespace            The namespace name

Options:
      --xml            To output list as XML
      --raw            To output raw command list
      --format=FORMAT  The output format (txt, xml, json, or md) [default: "txt"]

Help:
 The list command lists all commands:

   php bin/sugarcrm list

 You can also display the commands for a specific namespace:

   php bin/sugarcrm list test

 You can also output the information in other formats by using the --format option:

   php bin/sugarcrm list --format=xml

 It's also possible to get raw list of commands (useful for embedding command runner):

   php bin/sugarcrm list --raw

Custom Commands

Sugar allows developers the ability to create custom commands. These commands are registered using the Extension Framework. Each custom command will extend the stock Command class and implement a specific mode interface. The file system location of the command code can exist anywhere in the instance's file system including a separate composer loaded repository. 

Best Practices

The following are some common best practices developers should keep in mind when adding new commands :

  • Do not extend from existing commands
  • Do not duplicate an already existing command
  • Pick the correct mode for the command
  • Limit the logic in the command
  • Do not put reusable components in the command itself

Each command requires specific sections of code in order to properly create the command. These requirements are listed in the sections below.

Command Namespace

It is recommended to name any custom commands using a proper "command namespace". These namespaces are different than PHP namespaces and reduce the chances of collisions occurring between vendors. An example of this would be to prefix any commands with a namespace format of vendor:category:command E.g. MyDevShop:repairs:fixMyModule

Note : The CLI framework does not allow overriding of existing commands.

PHP Namespace

The header of the PHP command file will need to define the following namespace:

namespace Sugarcrm\Sugarcrm\custom\Console\Command;

In addition to the namespace, the following use commands are required for different operations :

Name Description Example
Command Every command will extend the Command class use Symfony\Component\Console\Command\Command;
Mode Whether the command is an Instance or Standalone Mode command

use Sugarcrm\Sugarcrm\Console\CommandRegistry\Mode\InstanceModeInterface;

use Sugarcrm\Sugarcrm\Console\CommandRegistry\Mode\StandaloneModeInterface;

Input Accepts Input from the command use Symfony\Component\Console\Input\InputInterface;
Output Sends Output from the command use Symfony\Component\Console\Output\OutputInterface;

Mode

When creating Sugar commands, developers will need to specify the mode or set of modes for the command. These modes help prepare the appropriate resources for execution of the command. 

Mode Description
Instance Mode  Commands that require an installed Sugar instance.
Standalone Mode  Commands that do not require an installed Sugar instance.

Note : Multiple modes can be selected.

Class Definition

The custom command class definition should extend the stock command class as well as implement a mode's interface

// Instance Mode Class Definition
class <classname> extends Command implements InstanceModeInterface
{
    //protected methods
}

// Standalone Mode Class Definition
class <classname> extends Command implements StandaloneModeInterface
{
    //protected methods
}

// Implementing both Modes
class <classname> extends Command implements InstanceModeInterface, StandaloneModeInterface
{
    //protected methods
}

Methods

Each command class implements two protected methods :

Method Description
configure()  Runs on the creation of the command. Useful to set the name, description, and help on the command.
execute(InputInterface $input, OutputInterface $output)  The code to run for executing the command. Accepts an input and output parameter. 

An example of implementing the protected methods is shown below:

protected function configure()
{
    $this->setName('sugardev:helloworld')
         ->setDescription('Hello World')
         ->setHelp('This command accepts no paramters and returns "Hello World".')
    ;
}

protected function execute(InputInterface $input, OutputInterface $output)
{
    $output->writeln("Hello world -> " . $this->getApplication()->getMode());
}

Registering Command

After creating the custom command file, register it with the Extension Framework. This file will be located in ./custom/Extension/application/Ext/Console/. An example of registering a command is below:

<?php

Sugarcrm\Sugarcrm\Console\CommandRegistry\CommandRegistry::getInstance()
   ->addCommand(new Sugarcrm\Sugarcrm\custom\Console\Command\<Command Class Name>());

Next, navigate to Admin > Repair > Quick Repair and Rebuild. The custom command will now be available.

Example

The following sections demonstrate how to create a "Hello World" example. This command does not alter the Sugar system and will only output display text. First, create the command class under the appropriate namespace.

./custom/src/Console/Command/HelloWorldCommand.php

<?php

namespace Sugarcrm\Sugarcrm\custom\Console\Command;

use Sugarcrm\Sugarcrm\Console\CommandRegistry\Mode\InstanceModeInterface;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

/**
 *
 * Hello World Example
 *
 */
class HelloWorldCommand extends Command implements InstanceModeInterface
{

    protected function configure()
    {
        $this
            ->setName('sugardev:helloworld')
            ->setDescription('Hello World')
            ->setHelp('This command accepts no paramters and returns "Hello World".')
        ;
    }

    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $output->writeln("Hello world -> " . $this->getApplication()->getMode());
    }
}

Next, register the new command:

./custom/Extension/application/Ext/Console/RegisterHelloWorldCommand.php

<?php

// Register HelloWorldCommand
Sugarcrm\Sugarcrm\Console\CommandRegistry\CommandRegistry::getInstance()
    ->addCommand(new Sugarcrm\Sugarcrm\custom\Console\Command\HelloWorldCommand());

Navigate to Admin > Repair > Quick Repair and Rebuild. The new command will be executable from the root of the Sugar instance. It can be executed by running the following command:

php bin/sugarcrm sugardev:helloworld

 Result:

Hello world -> InstanceMode

Help text can be displayed by executing the following command: 

php bin/sugarcrm help sugardev:helloworld

 Result:

Usage:
  sugardev:helloworld

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
      --profile         Display timing and memory usage information
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
 This command accepts no paramters and returns "Hello World".

Download the module loadable example package here.

Last modified: 07/13/2017 03:00pm