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.
Command | Description |
help | Displays help for a command |
list | Lists commands |
aclcache:dump | Dumps ACL cache contents into cache/acldumps folder |
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 |
idm-mode:manage | enable, disable IDM mode, or move config data to DB |
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:fields | Show search engine enabled fields |
search:module | Enable/disable given module for search |
search:reindex | Schedule SearchEngine 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:rebuild | Rebuild denormalized team security data |
team-security:status | Display the status of the denormalized data |
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 |
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
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 :
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.