CLI reference
The system includes an administrative CLI for system management. This interface allows you to perform all tasks relating to system setup and configuration. Any administrative activity that you can perform in the Admin App or REST API can be performed through the CLI.
Your system may also include additional, product-specific CLI tools.
Accessing the CLI tools on a system instance
You can access the CLI tools from any instance. To do this:
Procedure
Log in or SSH into a system instance.
Navigate to the CLI tool directory:
cd <installation-directory>/cli/
Navigate to the directory for the CLI tool you want. For example:
cd admin
Accessing the CLI tools from your computer
You can install your system's CLI tools on your Linux computer. To do this, you must have version 1.8 of the Java Runtime Environment (JRE) installed.
Your system's CLI tools are distributed in .tgz files along with the software installation package.
To install a CLI tool:
Procedure
Store the .tgz file in a directory on your computer.
Unpack the file:
tar zxvf filename
Syntax
The CLI tools have this syntax:
<tool-name> [options] [command] [command-specific-options]
-c, --command <command|category>
Specifies the command you want to run. When used with the --help
option, displays information about the specified command.
You can also use this option to specify a category of commands when using the --help
option. Doing this displays information about all commands within the specified category.
-d, --model-definition <name>
Returns information about the specified request model.
--debug
Includes verbose debug output for troubleshooting purposes.
-h, --help <all>
Displays help information. If you specify the all
argument, displays information an all commands. If you specify the --help
option, displays information about commands in the specified category.
-k, --check-ssl-cert <true|false>
Whether to enable SSL security checking. When false, insecure connections are allowed.
-m, --model-schema <ModelName>
Returns the JSON-formatted schema for the specified request model.
-p, --password <password>
Password for the specified user account.
--port
The port for the system application that supports the CLI tool.
-r, --realm <realm>
Security realm where your user account is defined.
-s, --server <server>
The hostname or IP address of a system instance.
-u, --username <username>
Username for an account that has permission to access system.
-V, --version
Displays the CLI version.
Viewing available commands
- To view all available commands, run:
<cli-tool-name> --help all
- To view all command categories, run:
<cli-tool-name> --help
- To view all commands within a category, run:
<cli-tool-name> --help -c <category>
For example:
admincli --help -c instances
- To view all information about a single command, run:
<cli-tool-name> --help -c <command>
For example:
admincli --help -c listInstances
Viewing request models
Some commands require that you include a JSON-formatted request body along with the command. The command's request model determines how you need to format the request body.
The help command for an individual command indicates what request model it requires.
For example, this help command output indicates that a command to update a service requires a ServiceUpdateModel request:
# ./admincli -c updateServiceConfig -h usage: updateServiceConfig Name: updateServiceConfig Description: Configure service instances Added: 1.0 Usage: admincli -c updateServiceConfig <options> Options: --service-update-model <ServiceUpdateModel> File containing JSON text representing a ServiceUpdateModel for the command updateServiceConfig. Use the -m and -d options to retrieve information on request and response models.
To view detailed information about the contents of a request model, run:
<cli-tool-name> -d
<ModelName>
For example:
admincli -d
ServiceUpdateModel
To view the JSON format for the request model, run:
<cli-tool-name> -m <ModelName>
Editing configuration preferences
You can use the CLI tool's .conf
file to specify settings to use every
time you run a CLI command.
The CLI configuration file has this format:
{ "defaultSettings": { "checkSSLCert": "[false|true]",(optional) "server": "<hostname>",(optional) "realm": "[local|<security-realm-name>]",(optional) "username": "<your-username>",(optional) "password": "<your-password>" (optional) } }
For example, with the following configuration, all commands:
- Are run against the
system.example.com
system - Check the SSL certificate for the system before connecting
- Uses the
exampleUsersEast
security realm to authenticate the specified username and password
{ "defaultSettings": { "checkSSLCert": "true", "server": "system.example.com", "realm": "exampleUsersEast" } }
You can configure CLI preference by editing the existing .conf
files in
the CLI installation directory.
The options you specify explicitly in a CLI command override the options specified in the
.conf
file.
System error responses
If a CLI request reaches the system and the system returns an error, the CLI response contains:
- An HTTP status code
- Conditionally, a product-specific error code
- A JSON-formatted error response body
This table describes the typical reasons why these HTTP status codes are returned.
Status code | Description |
400 (Bad Request) |
The request body contains one or more of these:
If the request includes a UUID, the UUID may be invalidly formatted. |
401 (Unauthorized) | The provided credentials are invalid. |
403 (Forbidden) | You do not have permission to perform the request. |
404 (File not found) | The resource you are trying to retrieve or edit cannot be found. |
409 (Conflict) | The resource you are trying to create already exists. |
500 (Server Error) | The system experienced an error. |
599 (Network Connection Timeout Error) | The CLI request timed out while attempting to connect to the system or one of its instances. |
Some CLI requests return product-specific error codes in addition to an HTTP status code.
These error codes are listed in the errorCodes
field in the JSON response
body. This table describes these error codes.
Error code | Description |
4000 | SSL certificate not trusted. |
Error response bodies have this format:
{ "statusCode": <HTTP-status-code>, "errorCode": <product-specific-error-code>, "errorMessage": <message>, "errorProperties": [ { "name": <error-property>, "message": <error-property-message> } ] }