CLI

Overview

Sugar on-premise deployments include a 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.

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
 aclcache
  aclcache:dump                Dumps ACL cache contents into cache/acldumps folder.
 elastic
  elastic:explain              Execute global search explain queries for debugging purposes. As this will generate a lot of output in JSON format, it is recommended to redirect the output to a file for later processing.
  elastic:indices              Show Elasticsearch index statistics
  elastic:queue                Show Elasticsearch queue statistics
  elastic:queue_cleanup        Cleanup records from Elasticsearch queue.
  elastic:refresh_enable       Enable refresh on all indices
  elastic:refresh_status       Show Elasticsearch index refresh status
  elastic:refresh_trigger      Perform a manual refresh on all indices
  elastic:replicas_enable      Enable replicas on all indices
  elastic:replicas_status      Show Elasticsearch index refresh status
  elastic:routing              Show Elasticsearch index routing
 email
  email:process                Process emails in parallel
  email:process-batch          Process a single email batch
 idm-mode
  idm-mode:manage              enable, disable IDM mode, or move config data to DB
 password
  password:config              Show password hash configuration
  password:reset               Reset user password for local user authentication.
  password:weak                Show users having weak or non-compliant password hashes
 search
  search:fields                Show search engine enabled fields
  search:module                Enable/disable given module for search
  search:reindex               Create mappings and schedule a reindex
  search:silent_reindex        Create mappings and index the data
  search:silent_reindex_mp     Create mappings and index the data using multi-processing
  search:status                Show search engine availability and enabled modules
 team-security
  team-security:rebuild        Rebuild denormalized team security data
  team-security:status         Display the status of the denormalized data
 teamset
  teamset:backup               Backs up the team_sets related tables.
  teamset:prune                Prune all team set tables of unused team sets. Original tables will be backed up automatically. DO NOT USE while users are logged into the system!
  teamset:restore_from_backup  Restores all team set tables from backups. DO NOT USE while users are logged into the system!
  teamset:scan                 Scan all module tables for unused team sets and report the number found.
  teamset:sql                  Print the sql query used to search for unused teamsets

 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 :

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. 

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 :

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.