Note

The documentation you're currently reading is for version 2.3.2. Click here to view documentation for the latest stable version.

CLI Reference

The BWC command line client (CLI) allows you talk to and operate your BWC deployment using the command line. It talks to the BWC installation using the public API.

Installation

If you installed BWC using packages or a deployment script, the CLI should already be available. It can also be installed with pip:

pip install st2client

Configuration

The command line client can be configured using one or more of the approaches listed below:

  • Configuration file (~/.st2/config)
  • Environment variables (ST2_API_URL, etc.)
  • Command line arguments (st2 --cacert=... action list, etc.)

The options have the following precedence from the highest to the lowest: command line arguments, environment variables, configuration file. This means that the values specified as command line arguments have the highest precedence and the values specified in the configuration file have the lowest precedence.

If the same value is specified in multiple places, the value with the highest precedence will be used. For example, if API url is specified in the configuration file and in an environment variable, the environment variable will be used.

Configuration file

The CLI can be configured through an ini-style configuration file which is by default located at ~/.st2/config.

If you want to use configuration from a different file (e.g. you have one config per deployment or environment) you can select which file to use using the ST2_CONFIG_FILE environment variable or --config-file command line argument.

For example (environment variable):

ST2_CONFIG_FILE=~/.st2/prod-config st2 action list

For example (command line argument):

st2 --config-file=~/.st2/prod-config action list

An example configuration file with all the options and the corresponding explanation is included below.

# Configuration file for the StackStorm CLI
[general]
base_url = http://127.0.0.1
api_version = v1
# Path to the CA cert bundle used to validate the SSL certificates
cacert =

[cli]
debug = True
# True to cache the retrieved auth token during authentication in ~/.st2/token
# and use the cached token in the subsequent API requests
cache_token = True
# Timezone used for timestamps displayed in the CLI. If not provided it defaults
# to UTC
timezone = Europe/Ljubljana

[credentials]
# Credentials used to authenticate against the auth API and retrieve the auth
# token
username = test1
password = testpassword

[api]
url = http://127.0.0.1:9101/v1

[auth]
url = http://127.0.0.1:9100/

If you want the CLI to skip parsing of the configuration file, you can do that by passing --skip-config flag to the CLI as shown below:

st2 --skip-config action list

Authentication and auth token caching

If you don’t wish to store your password in plain-text as shown in the previous section, the st2 login command offers an alternative. Similar to st2 auth, you must provide your username and password:

st2 login st2admin --password 'Password1!'

However, in addition to caching the token, this command will also modify the CLI configuration to include the referenced username. This way, future commands will know which cached token to use for authentication (since tokens are cached using the token-<username> format), meaning the password can be omitted from the config file altogether.

Warning

st2 login will overwrite the “credentials” section of the configuration. By default, it will overwrite the configured username, and will remove any configured password.

These auth tokens are by default cached on the local filesystem (in the ~/.st2/token-<username> file) and re-used for subsequent requests to the API service. Note that because the default behavior is to remove the password from the configuration, you will need to re-login once the generated token has expired - or make use of the --write-password flag, which writes the password to the config.

You can also use the st2 whoami command for a quick look at who is the currently configured user.

Switching between users is also as easy as re-running the st2 login command. Other users’ token cache files will remain, but the CLI configuration will be changed to point to the new username.

Note

As with many other st2 commands, st2 login will not create the configuration file for you. Keep this in mind especially if you’re leveraging the --config-file CLI option, or similar.

Note that you can still use the “old” method of supplying both username and password in the configuration file if you wish. If both a username and password are present in the configuration, then the client will automatically try to authenticate with these credentials.

If you want to disable auth token caching and want the CLI to retrieve a new auth token on each invocation, you can do that by setting cache_token option to False:

[cli]
cache_token = False

The CLI will by default also try to retrieve a new token if an existing one has expired.

If you have manually deleted or revoked a token before the expiration you can clear the cached token from by removing the ~/.st2/token file.

Setting API key as authentication credentials in configuration file will result in CLI using it as a primary method of authentication instead of auth token.

Using debug mode

The command line tools accepts --debug flag. When this flag is provided, debug mode will be enabled. Debug mode consists of the following:

  • On error / exception, full stack trace and client settings (api url, auth url, proxy information, etc.) are printed to the console.
  • Curl command for each request is printed to the console. This makes it easy to reproduce actions performed by the CLI using curl.
  • Raw API responses are printed to the console.

For example:

st2 --debug action list --pack=core

Example output (no error):

st2 --debug action list --pack=core
# -------- begin 140702450464272 request ----------
curl -X GET -H  'Connection: keep-alive' -H  'Accept-Encoding: gzip, deflate' -H  'Accept: */*' -H  'User-Agent: python-requests/2.5.1 CPython/2.7.6 Linux/3.13.0-36-generic' 'http://localhost:9101/v1/actions?pack=core'
# -------- begin 140702450464272 response ----------
[
    {
        "runner_type": "http-runner",
        "name": "http",
        "parameters": {
        ...

Example output (error):

st2 --debug action list --pack=core
ERROR: ('Connection aborted.', error(111, 'Connection refused'))

Client settings:
----------------
ST2_BASE_URL: http://localhost
ST2_AUTH_URL: https://localhost:9100
ST2_API_URL: http://localhost:9101/v1

Proxy settings:
---------------
HTTP_PROXY:
HTTPS_PROXY:

Traceback (most recent call last):
  File "./st2client/st2client/shell.py", line 175, in run
    args.func(args)
  File "/data/stanley/st2client/st2client/commands/resource.py", line 218, in run_and_print
    instances = self.run(args, **kwargs)
  File "/data/stanley/st2client/st2client/commands/resource.py", line 37, in decorate
    return func(*args, **kwargs)
    ...

Using CLI inside scripts

The CLI returns a non-zero return code for any erroneous operation. You can capture the return code of CLI commands to check whether the command succeeded.

For example:

st2 action get twilio.send_sms

+-------------+--------------------------------------------------------------+
| Property    | Value                                                        |
+-------------+--------------------------------------------------------------+
| id          | 54bfff490640fd2f6224ac1a                                     |
| ref         | twilio.send_sms                                              |
| pack        | twilio                                                       |
| name        | send_sms

Now, let’s get the exit code of the previous command.

echo $?

0

Now, let’s run a command that we know will fail.

st2 action get twilio.make_call

Action "twilio.make_call" is not found.

Let’s check the exit code of the last command.

echo $?

2

Obtaining an authentication token inside scripts

If you want to authenticate and obtain an authentication token inside your (shell) scripts, you can use the st2 auth CLI command in combination with the -t flag.

This flag will cause the command to only print the token to the stdout on successful authentication. This means you don’t need to deal with parsing JSON or CLI output format.

Example command usage:

st2 auth test1 -p 'testpassword' -t

0280826688c74bb9bd541c26631df298

Example usage inside a Bash script:

TOKEN=$(st2 auth test1 -p 'testpassword' -t)

# Now you can use the token (e.g. pass it to other commands, set an
# environment variable, etc.)
echo ${TOKEN}

Changing the CLI output format

By default, the CLI returns and prints results in a user-friendly table oriented format. For example:

st2 action list --pack=slack

+--------------------+-------+--------------+-------------------------------+
| ref                | pack  | name         | description                   |
+--------------------+-------+--------------+-------------------------------+
| slack.post_message | slack | post_message | Post a message to the Slack   |
|                    |       |              | channel.                      |
+--------------------+-------+--------------+-------------------------------+

If you want a raw JSON result as returned by the API (e.g. you are calling CLI as part of your script and you want the raw result which you can parse), you can pass the -j flag to the command.

For example:

st2 action list -j --pack=slack

[
    {
        "description": "Post a message to the Slack channel.",
        "name": "post_message",
        "pack": "slack",
        "ref": "slack.post_message"
    }
]

Only displaying a particular attribute when retrieving action result

By default when retrieving action execution result using execution get command, the whole result object will be printed.

For example:

st2 execution get 54d8c52e0640fd1c87b9443f

STATUS: succeeded
RESULT:
{
    "failed": false,
    "stderr": "",
    "return_code": 0,
    "succeeded": true,
    "stdout": "Mon Feb  9 14:33:18 UTC 2015
"
}

If you only want to retrieve and print out a specified attribute, you can do that using -k <attribute name> flag.

For example, if you only want to print stdout attribute of the result object:

st2 execution get -k stdout 54d8c52e0640fd1c87b9443f

Mon Feb  9 14:33:18 UTC 2015

If you only want to retrieve and print out a specified attribute of the execution, you can do that using --attr <attribute name> flag.

For example, if you only want to print start_timestamp attribute of the result object:

st2 execution get 54d8c52e0640fd1c87b9443f -a start_timestamp

start_timestamp: 2015-02-24T23:01:15.088293Z

You can also specify multiple attributes:

st2 execution get 54d8c52e0640fd1c87b9443f --attr status result.stdout result.stderr

status: succeeded
result.stdout: Mon Feb  9 14:33:18 UTC 2015

result.stderr:

Similarly for the execution list command:

st2 execution list -a id status result

+--------------------------+-----------+---------------------------------+
| id                       | status    | result                          |
+--------------------------+-----------+---------------------------------+
| 54eb51000640fd34e0a9a2ce | succeeded | {u'succeeded': True, u'failed': |
|                          |           | False, u'return_code': 0,       |
|                          |           | u'stderr': u'', u'stdout':      |
|                          |           | u'2015-02-23                    |
|                          |           | 16:10:39.916375\n'}             |
| 54eb51000640fd34e0a9a2d2 | succeeded | {u'succeeded': True, u'failed': |
|                          |           | False, u'return_code': 0,       |
|                          |           | u'stderr': u'', u'stdout':      |
|                          |           | u'2015-02-23                    |
|                          |           | 16:10:40.444848\n'}             |

Escaping shell variables when using core.local and core.remote actions

When you use local and remote actions (e.g. core.local, core.remote, etc.), you need to wrap cmd parameter values in a single quote or escape the variables. Otherwise the shell variables will be expanded locally which is something you usually don’t want.

Example (using single quotes):

st2 run core.local env='{"key1": "val1", "key2": "val2"}' cmd='echo "ponies ${key1} ${key2}"'

Example (escaping the variables):

st2 run core.remote hosts=localhost env='{"key1": "val1", "key2": "val2"}' cmd="echo ponies \${key1} \${key2}

Specifying parameters with type “array”

When running an action using st2 run command, you specify the value of parameters with type array as a comma delimited string.

Inside the CLI, this string gets split on commas and passed to the API as a list.

For example:

st2 run mypack.myaction parameter_name="value 1,value2,value3"

In this case, the parameter_name value would get passed to the API as a list (JSON array) with three items - ["value 1", "value2", "value3"].

Keep in mind that this only works for simple types (e.g. arrays of strings). For more complex types (e.g. arrays of objects) you need to use JSON notation as shown below:

st2 run mypack.myaction parameter_name='[{"Name": "MyVMName"}]'

Note

When using JSON string notation, parameter value needs to be wrapped inside single quotes (e.g. parameter='{"Key": "Value"}'), otherwise quotes (") inside the JSON string need to be escaped with a backslash (\ - e.g. parameter="{\"Key\": \"Bar\"}").

Specifying parameters with type “object”

When running an action using st2 run command, you can specify the value of parameters with type object using two different approaches:

JSON string notation

For complex objects, you should use JSON notation. For example:

st2 run core.remote hosts=localhost env='{"key1": "val1", "key2": "val2"}' cmd="echo ponies \${key1} \${key2}

Note

When using JSON string notation, parameter value needs to be wrapped inside single quotes (e.g. parameter='{"Key": "Value"}'), otherwise quotes (") inside the JSON string need to be escaped with a backslash (\ - e.g. parameter="{\"Key\": \"Bar\"}").

Comma-delimited key=value pairs string notation

For simple objects (such as specifying a dictionary where both keys and values are simple strings), you should use this notation:

st2 run core.remote hosts=localhost env="key1=val1,key2=val2" cmd="echo ponies \${key1} \${key2}"

Reading parameter value from a file

CLI also supports special @parameter notation which makes it read parameter value from a file.

An example of when this might be useful is when you are using http runner actions, or when you want to read information such a private SSH key content from a file.

Example:

st2 run core.remote hosts=<host> username=<username> @private_key=/home/myuser/.ssh/id_rsa cmd=<cmd>

Re-running an action

To re-run a particular action, you can use the execution re-run <existing execution id> command.

By default, this command re-runs an action with the same set of input parameters which were used with the original action.

The command takes the same arguments as the run / action execute command. This means you can pass additional runner or action specific parameters to the command. Those parameters are then merged with the parameters from the original action and used to run a new action.

For example:

st2 run core.local env="VAR=hello" cmd='echo $VAR; date'
.
+-----------------+--------------------------------+
| Property        | Value                          |
+-----------------+--------------------------------+
| id              | 54e37a3c0640fd0bd07b1930       |
| context         | {                              |
|                 |     "user": "stanley"          |
|                 | }                              |
| parameters      | {                              |
|                 |     "cmd": "echo $VAR; date",  |
|                 |     "env": {                   |
|                 |         "VAR": "hello"         |
|                 |     }                          |
|                 | }                              |
| status          | succeeded                      |
| start_timestamp | Tue, 17 Feb 2015 17:28:28 UTC  |
| result          | {                              |
|                 |     "failed": false,           |
|                 |     "stderr": "",              |
|                 |     "return_code": 0,          |
|                 |     "succeeded": true,         |
|                 |     "stdout": "hello           |
|                 | Tue Feb 17 17:28:28 UTC 2015   |
|                 | "                              |
|                 | }                              |
| action          | core.local                     |
| callback        |                                |
| end_timestamp   | Tue, 17 Feb 2015 17:28:28 UTC  |
+-----------------+--------------------------------+

st2 run re-run 54e37a3c0640fd0bd07b1930
.
+-----------------+--------------------------------+
| Property        | Value                          |
+-----------------+--------------------------------+
| id              | 54e37a630640fd0bd07b1932       |
| context         | {                              |
|                 |     "user": "stanley"          |
|                 | }                              |
| parameters      | {                              |
|                 |     "cmd": "echo $VAR; date",  |
|                 |     "env": {                   |
|                 |         "VAR": "hello"         |
|                 |     }                          |
|                 | }                              |
| status          | succeeded                      |
| start_timestamp | Tue, 17 Feb 2015 17:29:07 UTC  |
| result          | {                              |
|                 |     "failed": false,           |
|                 |     "stderr": "",              |
|                 |     "return_code": 0,          |
|                 |     "succeeded": true,         |
|                 |     "stdout": "hello           |
|                 | Tue Feb 17 17:29:07 UTC 2015   |
|                 | "                              |
|                 | }                              |
| action          | core.local                     |
| callback        |                                |
| end_timestamp   | Tue, 17 Feb 2015 17:29:07 UTC  |
+-----------------+--------------------------------+

st2 run re-run 7a3c0640fd0bd07b1930 env="VAR=world"
.
+-----------------+--------------------------------+
| Property        | Value                          |
+-----------------+--------------------------------+
| id              | 54e3a8f50640fd140ae20af7       |
| context         | {                              |
|                 |     "user": "stanley"          |
|                 | }                              |
| parameters      | {                              |
|                 |     "cmd": "echo $VAR; date",  |
|                 |     "env": {                   |
|                 |         "VAR": "world"         |
|                 |     }                          |
|                 | }                              |
| status          | succeeded                      |
| start_timestamp | Tue, 17 Feb 2015 20:47:49 UTC  |
| result          | {                              |
|                 |     "failed": false,           |
|                 |     "stderr": "",              |
|                 |     "return_code": 0,          |
|                 |     "succeeded": true,         |
|                 |     "stdout": "world           |
|                 | Tue Feb 17 20:47:49 UTC 2015   |
|                 | "                              |
|                 | }                              |
| action          | core.local                     |
| callback        |                                |
| end_timestamp   | Tue, 17 Feb 2015 20:47:49 UTC  |
+-----------------+--------------------------------+

Cancel an execution

When dealing with long running executions, you may want to cancel some of them before they are done.

To cancel an execution, run:

st2 execution cancel <existing execution id>

Inheriting all the environment variables which are accessible to the CLI and passing them to runner as env parameter

Local, remote and Python runner support env parameter. This parameter tells the runner which environment variables should be accessible to the action which is being executed.

User can specify environment variables manually using env parameter exactly the same way as other parameters.

For example:

st2 run core.remote hosts=localhost env="key1=val1,key2=val2" cmd="echo ponies \${key1} \${key2}"

In addition to that, users can pass the -e / --inherit-env flag to the action run command.

This flag will cause the command to inherit all the environment variables which are accessible to the CLI and send them as an env parameter to the action.

Keep in mind that some global shell login variables such as PWD, PATH and others are ignored and not inherited. The full list of ignored variables can be found in action.py file.

For example:

st2 run --inherit-env core.remote cmd=...