Installing and Configuring the Turbot CLI


  • You will need Turbot API access keys. If you do not have keys for your profile, you can generate new ones.
  • You will need to know the URL of your Turbot workspace(s)

Install the Turbot CLI

  • Download the latest Turbot CLI. The latest version is available from the Turbot Developer Portal.
  • Unzip the turbot binary into a directory in your PATH (for example /usr/local/bin/turbot)
  • Run turbot --version to verify your CLI version.
If the ALB is using a self signed certificate (Enterprise only), it is necessary to set the environment variable NODE_TLS_REJECT_UNAUTHORIZED to 0. It is possible to update the node certificate store with third party CA root certs using environment variable NODE_EXTRA_CA_CERTS.

Setup Your Turbot Credentials

Turbot follows a similar approach to AWS in managing their authentication and authorization mechanism. The format and structure of the Turbot credentials file resembles the credentials file structure used by the AWS CLI.

To configure the Turbot CLI tool to connect to your workspace, run the turbot configure command. When prompted, enter your Workspace URL, Turbot API Access Key, and Turbot API Secret Key:

$ turbot configure
Migrating CLI config from /Users/TestUser/.turbot/config.yml to /Users/TestUser/.config/turbot/config.yml
Migrating registry file from /Users/TestUser/.turbot/registry.json to /Users/TestUser/.config/turbot/registry.yml
✔ Profile name [default] …default✔ Workspace URL …✔ Turbot Access Key … ************************************✔ Turbot Secret Key … ************************************Written profile 'default' to '/Users/TestUser/.config/turbot/credentials.yml'

This command will generate a default profile and add it to your Turbot credentials file. The default profile is used when you run the turbot command without explicitly specifying a --profile .

Named Profiles

The Turbot CLI supports the use of multiple named profiles that are stored in the credentials file. Having multiple named profiles helps you switch between workspaces at ease. Meaningful and easy to remember profile names allow users to effectively handle multiple workspaces simultaneously.

$ turbot configure
Migrating CLI config from /Users/TestUser/.turbot/config.yml to /Users/TestUser/.config/turbot/config.yml
Migrating registry file from /Users/TestUser/.turbot/registry.json to /Users/TestUser/.config/turbot/registry.yml
✔ Profile name [default] …newwarriors✔ Workspace URL …✔ Turbot Access Key … ************************************✔ Turbot Secret Key … ************************************Written profile 'default' to '/Users/TestUser/.config/turbot/credentials.yml'

The above example creates a profile named newwarriors. To run turbot commands in this context, add the --profile newwarriors argument to turbot.

Find controls in error or alarm state in the workspace using the command: turbot --profile newwarriors graphql controls --filter "state:alarm,error"

A Sample Credentials File

The turbot configure command generates a text file that contains your access keys. By deafult, this file will be named credentials.yml and will be located in the .config/turbot/ folder in your home directory. Note that the turbot configure output will tell you the location where the credentials file is written,

The format of the Turbot credentials file should look something like the following.

  accessKey: 14ab*****-****-****-****-**********998c
  secretKey: t54d*****-****-****-****-**********876e
  workspace: ''
  accessKey: ab41*****-****-****-****-**********978c
  secretKey: t74e*****-****-****-****-**********846f
  workspace: ''

The above example shows a credentials file with two profiles. The first is used when you run a CLI command with no profile. The second is used when you run a CLI command with the --profile newwarriors parameter.

Environment Variables

Environment variables provide another way to specify default Turbot CLI credentials:

export TURBOT_SECRET_KEY=xxxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export TURBOT_ACCESS_KEY=xxxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

If environment variables are set, they will be used when no --profile is specified.

You can also change the default profile to a named profile with the TURBOT_PROFILE environment variable:

export TURBOT_PROFILE=newwarriors

CLI commands that do not specify a --profile will now default to the newwarriors profile


The Turbot CLI searches for credentials in the following order:

  1. workspace,accessKey,secretKey passed on the command line. Please note that all three of these must be given together.
  2. profile passed on the command line.
  4. TURBOT_PROFILE in the environment.
  5. workspace,accessKey,secretKey in config.yml.
  6. profile in config.yml .
  7. default profile.