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=...actionlist, 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.

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.1api_version=v1# Path to the CA cert bundle used to validate the SSL certificatescacert=[cli]debug=True# True to cache the retrieved auth token during authentication in ~/.st2/token# and use the cached token in the subsequent API requestscache_token=True# Timezone used for timestamps displayed in the CLI. If not provided it defaults# to UTCtimezone=Europe/Ljubljana[credentials]# Credentials used to authenticate against the auth API and retrieve the auth# tokenusername=test1password=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:

If you don’t wish to store your password in plain-text as shown in the previous section,
the st2login command offers an alternative. Similar to st2auth, 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

st2login 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 st2whoami command for a quick look at who is the currently
configured user.

Switching between users is also as easy as re-running the st2login 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, st2login 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.

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.

To re-run a particular action, you can use the executionre-run<existingexecutionid> 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 / actionexecute
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.