⚠️

You must submit an early access request prior to use of the CLI

https://catalytic.pushbot.com/form/sdk-early-access

Installation

macOS

macOS installation is managed via Homebrew
Install:

$ brew install catalyticlabs/catalytic/catalytic-cli

Upgrade:

$ brew update && brew upgrade catalytic-cli

Linux

Linux installation is managed via Homebrew
Install:

$ brew install catalyticlabs/catalytic/catalytic-cli

Upgrade:

$ brew update && brew upgrade catalytic-cli

Alternatively, you can find the latest binaries on the CLI Releases page.

Windows

Install:
Download and run the latest MSI Installer or another Installer from the CLI Releases page.

Upgrade:
Download and run the latest MSI Installer or another Installer from the CLI Releases page.

Overview

Usage

Each command in the Catalytic CLI shares a similar pattern:

$ catalytic [entity] [action] [<argument>] [--options-with-argument=<val>] [--option]

You can access help for any entity by appending the --help flag:

$ catalytic [entity] --help

In the usage help for each command, words starting with "<" and ending with ">" are interpreted as positional arguments.

Options and arguments are required by default; however, options and arguments in brackets "[]" are optional.

Options with arguments may be written as --option=value or --option value; the two formats are equivalent.

High Level Commands:

$ catalytic login [help | -h | --help] [<args>...] [options...]
$ catalytic workflow [help | -h | --help] [<args>...] [options...]
$ catalytic instance [help | -h | --help] [<args>...] [options...]
$ catalytic credentials [help | -h | --help] [<args>...] [options...]
$ catalytic file [help | -h | --help] [<args>...] [options...]

Feedback

We'd love to hear your feedback! Please visit the Catalytic Community site and create a new question with the CLI tag.

Authentication

To make requests to the Catalytic platform via Catalytic CLI, a User Access Token must be provided.

Create User Access Token

You may generate new User Access Token either using the Catalytic UI or using Catalytic CLI.

📘

What's the difference between Credentials and User Access Tokens?

The terms "Credentials" and "User Access Token" can be used fairly interchangeably. Technically a User Access Token is a string-serialized version of a Credential. Generally, "User Access Token" will be used when discussing creation and Credentials will be used when discussing management and usage via the CLI.

Create User Access Token via Catalytic UI

You can create a new User Access Token from the "Access Tokens" tab of the "My Account" page in the Catalytic WebApp.

Click "Create a New Access Token" and give your new User Access Token a name.

⚠️

Make sure to copy or save the Token value

You won't be able to access it again.

You can then use the $ catalytic credentials add --token <Token> command to save for use with the CLI. See Credentials Management Commands for more details.

Create User Access Token via the login Command

You can create a new User Access Token directly from the CLI using the following command:

$ catalytic login

You will be prompted to enter you Catalytic team name, email, password, and a name for your User Access Token via StdIn.

If your Catalytic team uses SSO, do not provide email and password. The CLI will create the Access Token and open the Approval URL in the OS's default browser. You must approve the Access Token in the browser prior to use.

See Login Commands for more information.

📘

Credentials created via login command are automatically saved locally in the default Catalytic Credentials directory (%USERPROFILE%\.catalytic\credentials on Windows and ~/.catalytic/credentials on macOS and Linux)

Using Credentials in Commands

You can specify the Credentials to use for a given CLI command via either the --credentials CLI option or the CATALYTIC_CREDENTIALS environment variable.

--credentials option

$ catalytic workflow list --credentials <CredentialsName>

Environment Variable

$ CATALYTIC_CREDENTIALS=<your_token_string> catalytic workflow list

Default Credentials

If you have saved Credentials with the name default, those Credentials will automatically be used if no other Credentials are specified via either the CATALYTIC_CREDENTIALS environment variable or --credentials flag.