How To: Use the CLI From Scripts

Authentication

The CLI always needs a valid set of credentials to perform operations in Decodable. When you login, the CLI receives an access token as well as a refresh token that allows the CLI to fetch new access tokens in the future. You can obtain a refresh token and store it in a secure file or secret store (e.g. Vault, AWS Secret Manager, Github Secrets) and then use this in your script to authenticate. In this way, your refresh token acts like a dynamic API key.

To obtain a set of credentials you can use in scripts, you should login as the user you want the script to run as, but store the credentials in a separate file.

# Login, but store credentials in my_script.auth
decodable login -f my_script.auth

Since this file doesn't exist, you'll be prompted to login and the credentials will be stored in this file. You can also force this behavior by adding the --force flag if the file does exist and you want to update it.

❗️

Warning: Always keep auth tokens secure!

The access token allows the holder to perform API operations as the user that obtained it for the duration of its life (typically 24 hours). You must always keep this token secure. Similarly, the refresh token can be used to obtain new access tokens and must also be protected.

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

Arrange for this auth file to be available at the path ~/.decodable/auth on the hosts or containers where your scripts run and your scripts will work!

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 could 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

Did this page help you?