The Decodable CLI

The Decodable command line interface (CLI) is the primary way to work with Connections, Streams, Pipelines, and Secrets in Decodable. It’s fast, easy to use and suitable for both interactive or scripted use.

The CLI is available for the following platforms:

  • Linux

  • macOS (10.15 and later)

  • Windows

Install the Decodable CLI

There are several ways you can install the Decodable CLI. Follow the instructions for your respective operating system to install the CLI.

Install manually

To install the Decodable CLI manually, go to the Downloads page and download the version of the Decodable CLI that you want to install. If you are downloading these binaries via a browser on macOS, you need to approve this as an application from an unidentified developer.

You might want to move the CLI directory to an appropriate place on your system such as /usr/local or /opt, and add the bin directory to your shell’s $PATH. Alternatively, you can copy the decodable executable to an existing location already in the shell’s path.

Install with Homebrew

If you have Homebrew, run the following command to install the Decodable CLI. This option is only supported for macOS systems.

brew tap decodableco/decodable && brew install decodable

Install with Decodable’s install script

You can install the latest version of the Decodable CLI using our simple install script. Running this command downloads the latest version of the Decodable CLI in /usr/local/bin. This option is supported for both macOS and Linux systems.

curl -L releases.decodable.co/install | bash

Setup

Before using the CLI, you must run the setup command with your account name.

decodable config setup <your_account>

This will create the configuration directory .decodable in your OS user’s home folder and generate a configuration file named config. After the initial setup, this file will contain a single profile (default) referencing your Decodable account.

# Decodable configuration file.
#
# Generated by ...

version: 1.0.0
active-profile: default

profiles:
  default:
    account: <your_account>
If you plan to use the CLI with several Decodable accounts, you can configure multiple profiles and conveniently switch back and forth between them. See the Managing CLI Profiles for more information.

Commands

All CLI functionality is grouped into logical (sub)commands. Running the CLI with no arguments will show you the list of supported commands as well as some basic help information.

decodable

# Output:
# Usage:
#   decodable [command]
#
# Available Commands:
#   apply       Apply resource YAML file(s)
#   completion  Generate shell completion script
#   config      Manage client configuration
#   connection  Manage connections
#   help        Help about any command
#   login
#   pipeline    Manage pipelines
#   query       Query account resources
#   secret      Manage secrets
#   stream      Manage streams
#   token       Print auth tokens

# Flags:
#   -h, --help      help for decodable
#   -v, --version   version for decodable

# Use "decodable [command] --help" for more information about a command.

When in doubt, just use the help command or the --help/-h flags to get more help about a command. Find some examples below:

  • Display the help for the pipeline command

decodable pipeline -h
# or
decodable help pipeline

# Output:
# Manage pipelines

# Usage:
#   decodable pipeline [command]

# Aliases:
#   pipeline, pl

# Available Commands:
#   activate    Activate a pipeline
#   create      Create a new pipeline
#   deactivate  Deactivate a pipeline
#   delete      Delete a pipeline
#   get         Get the definition for a pipeline
#   list        List pipelines
#   logs        Retrieve pipeline logs
#   preview     Run a preview
#   snapshot    Manage pipeline snapshots
#   update      Update an existing pipeline

# Flags:
#   -h, --help   help for pipeline

# Use "decodable pipeline [command] --help" for more information about a command.

  • Display help for the create subcommand of the pipeline command.

decodable pipeline create -h
# or
decodable help pipeline create

# Output:
# Create a new pipeline

# Usage:
#   decodable pipeline create <sql> [flags]

# Aliases:
#   create, new

# Flags:
#       --account string             override the account
#       --base-url string            override the control plane base URL
#       --conf-file string           specify (or override) the conf file location
#       --config-file stringArray    for custom pipelines, a config file to upload (repeatable)
#       --description string         pipeline description
#       --entry-class string         for custom pipelines, the name of the entry class to run
#       --flink-version string       for custom pipelines, the Flink version to run on
#   -h, --help                       help for create
#       --job-arguments string       for custom pipelines, argument(s) to pass to the main() method
#       --job-file string            for custom pipelines, the path to the JAR file (Java) or ZIP file (Python) to upload
#       --name string                pipeline name
#   -o, --output string              output format (one of json|plain|yaml)
#   -p, --profile string             override active profile
#       --secrets string             for custom pipelines, a comma-separated list of secret resource ids to make available
#       --snapshots                  whether to enable periodic snapshots
#       --snapshots-cron string      a cron expression for periodic snapshots
#       --snapshots-retention uint   how long to retain periodic snapshots, in seconds
#       --type string                for custom pipelines, the pipeline type (JAVA|PYTHON)

Configuration

The CLI stores configuration about profiles and authentication credentials in the ~/.decodable/ directory. These are YAML files which are safe to explore, if you’re curious.

The auth file contains sensitive access tokens and must not be shared or committed to version control.

Authentication

In most cases, you’ll only need to login once.

To login, run decodable login and follow the directions in your terminal / browser.

After a successful login, the CLI stores the necessary tokens in a file named auth in the configuration directory. While access tokens have a limited lifespan, the CLI will automatically refresh them as needed.

An example of the auth file after logging into the account name referenced in the default profile is shown below:

version: 1.0.0
tokens:
    default:
        access_token: ...
        refresh_token: ...
        id_token: ...
        expiry: ...

General usage

Now that you’re logged in, you’re ready to get started using the Decodable CLI! Run decodable help for information about what you can do.

# Output:
# Usage:
#   decodable [command]
#
# Available Commands:
#   apply       Apply resource YAML file(s)
#   completion  Generate shell completion script
#   config      Manage client configuration
#   connection  Manage connections
#   help        Help about any command
#   login
#   pipeline    Manage pipelines
#   query       Query account resources
#   secret      Manage secrets
#   stream      Manage streams
#   token       Print auth tokens

# Flags:
#   -h, --help      help for decodable
#   -v, --version   version for decodable

# Use "decodable [command] --help" for more information about a command.
Almost all resource-related CLI commands - connection, stream, pipeline, secret - use the same general subcommands of get, list, create, delete, and update with the same flags. Additionally, all commands always support --help / -h!

If you’d like a more in-depth walkthrough of how to use the Decodable CLI to perform an end-to-end use case, see the Using the Decodable CLI tutorial.