Use the CLI from scripts

Whilst the CLI will often be used interactively, it can also be used "headless" from scripts. This can be as part of a CI/CD workflow through something like GitHub Actions, other for other bespoke purposes.

In order to use the CLI without user interaction there are two files that should be configured when using the CLI from a script. The files are stored in ~/.decodable/.

  • config contains details of account names and associated profiles.

  • auth contains details about authentication including refresh token value. This is sensitive data and should be protected in the same manner as passwords, etc.

The account name in config must be the same one that the authentication details held in auth are for. If they don’t match you will get an error such as Organization in JWT does not match account in URL

Account configuration

The file ~/.decodable/config holds the name of your account. A basic example looks like this:

version: 1.0.0
active-profile: default

profiles:
  default:
    account: <your account name>

Authentication

The CLI needs valid credentials to access your account in Decodable. It uses the file ~/.decodable/auth to access credentials and needs either:

  • An access token that hasn’t expired

  • A refresh token. A refresh token can be used by the CLI to generate a valid access token.

Since an access token is time-bound, it’s better practice to use a refresh token when invoking the CLI from a script.

Obtaining a refresh token

There are two ways to get a refresh token.

  1. If you are already logged into the correct account with the CLI run:

    decodable token refresh

    This writes the token to the screen. You can write it to an environment variable directly by doing the following:

    DECODABLE_REFRESH_TOKEN="$(decodable token refresh)"

  2. If you aren’t already logged into the account in the CLI use the --file argument for the login command to write the authentication credentials directly to a file.

    # Login and store credentials in my_account.auth
decodable login --file my_account.auth

    In the resulting my_account.auth file will be the refresh token, along with the access token. You only need the refresh token, since the other authentication values can be regenerated from it.

    We recommend that you delete my_account.auth once you’ve retrieved the refresh token due to the sensitivity of its contents.

    You can also use decodable login on its own. In this case the authentication values will be written to ~/.decodable/auth.

Store the refresh token in a secure file or secret store (for example Vault, AWS Secret Manager, GitHub Secrets).

Always keep authentication tokens secure.

  • The access token allows the holder to run API operations as the user that obtained it for the duration of its life (typically 24 hours).

  • The refresh token can be used to obtain new access tokens and is thus even more powerful as it doesn’t expire.

Improper handling of these tokens can allow malicious users to capture all data to which you have access through Decodable.

Machine-readable output

By default, the CLI prints output in a plain-text format designed for human readability. However, a more structured, machine readable output format is better suited to scripted applications. Many of the CLI commands support the -o or --output flags for this purpose, allowing you to choose a format like JSON or YAML. This, combined with something like jq or the scripting language of your choice, makes it easy to automate tasks with the decodable CLI.

For example, if you wanted to get the IDs of all running pipelines, you can pipe the output of decodable pipeline ls -o json to jq for filtering and projection:

$ decodable pipeline ls -o json | jq -r 'select(.actual_state == "RUNNING") | .id'
c15448bc
fd4f8016

See also the declarative resource management query option for further querying and output options.