Skip to main content

Clarifai CLI

Learn how to use the Clarifai Command Line Interface (CLI)


Clarifai’s Command Line Interface (CLI) is a powerful, user-friendly tool designed to simplify and enhance your experience with our AI platform.

By offering a streamlined way to execute tasks directly from the terminal, the CLI eliminates the need for extensive coding or constant reliance on the web interface.

Bundled within our Python SDK package, the CLI empowers both technical and non-technical users to efficiently execute a wide range of tasks and boost productivity on the Clarifai platform.

Installation

To begin, install the latest version of the clarifai Python package.

pip install --upgrade clarifai

Set a PAT Key

You need to set the CLARIFAI_PAT (Personal Access Token) as an environment variable before using the CLI tool. You can generate the PAT key in your personal settings page by navigating to the Security section.

This token is essential for authenticating your connection to the Clarifai platform.

 export CLARIFAI_PAT=YOUR_PERSONAL_ACCESS_TOKEN_HERE 
tip

On Windows, the Clarifai Python SDK expects a HOME environment variable, which isn’t set by default. To ensure compatibility with file paths used by the SDK, set HOME to the value of your USERPROFILE. You can set it in your Command Prompt this way: set HOME=%USERPROFILE%.

Basics

The CLI tool supports a broad range of use cases with intuitive commands and convenient aliases.

Usage: clarifai [OPTIONS] COMMAND [ARGS]...

Clarifai CLI

Options:
--config TEXT
--help Show this message and exit.

Commands:
computecluster (cc) Manage Compute Clusters: create, delete, list
config (cfg) Manage CLI configuration
context Manage contexts
deployment (dp) Manage Deployments: create, delete, list
login Login command to set PAT and other configurations.
model Manage models: upload, test, local dev, predict, etc
nodepool (np) Manage Nodepools: create, delete, list
run Execute a script with the current context's environment
shell-completion Shell completion script

The --help option is particularly useful to quickly understand the available functionalities and how to use them.

clarifai COMMAND --help

For example:

clarifai config --help

Produces this output:

Usage: clarifai config [OPTIONS] COMMAND [ARGS]...

Manage CLI configuration

Options:
--help Show this message and exit.

Commands:
current-context (current) Get the current context
dump (cat) Dump the configuration to stdout
edit (e) Edit the configuration file
env (cat) Print env vars. Use: eval "$(clarifai config env)"
get-contexts (list, ls) Get all contexts
use-context (use) Set the current context
Context

A context refers to the active environment settings that determine how your commands interact with the Clarifai platform. Think of a context as a saved set of credentials (such as a PAT key or a specific application ID) you want to work with.

Clarifai Context

The clarifai context command allows you to manage different Clarifai configurations or environments, referred to as "contexts."

clarifai context [OPTIONS] COMMAND [ARGS]...

This command provides subcommands to create, delete, and switch between different named Clarifai contexts. Each context can encapsulate specific authentication details (like PATs), API URLs, or other configurations relevant to a particular Clarifai project or user.

Create Context

The create subcommand creates a new Clarifai context.

clarifai context create CONTEXT_NAME_HERE

Here is an example of creating a context called my_new_context. Note that you'll be prompted to configure the context by providing the necessary details for that context — user ID, API URL, and PAT.

C:#############>clarifai context create my_new_context user id: alfrick base url (default: https://api.clarifai.com): personal access token value (default: "ENVVAR" to get out of env var rather than config): xxxxxxxxxxxx

Delete Context

The delete (alias rm) subcommand deletes an existing Clarifai context.

clarifai context delete CONTEXT_NAME_HERE // or clarifai context rm CONTEXT_NAME_HERE

Here is an example:

clarifai context delete old_project_context

Switch Contexts

The use subcommand sets a specified context as the currently active context. All subsequent Clarifai CLI commands will operate within the configurations defined by this context.

This is useful when you need to switch between different Clarifai applications, user accounts, or API settings without repeatedly re-authenticating or reconfiguring.

clarifai context use CONTEXT_NAME_HERE

Here is an example:

clarifai context use my_other_project

Clarifai Login

The clarifai login command is used to authenticate and configure your access to the Clarifai platform. This involves setting up a Personal Access Token (PAT) and other necessary configurations for making API requests.

clarifai login [OPTIONS] [API_URL]

Here is an example of the standard way to use the command. You'll be prompted to enter a context name (a new, existing, or the default name), user ID, and PAT interactively.

C:#############>clarifai login context name (default: "default"): my_new_context user id: alfrick personal access token value (default: "ENVVAR" to get out of env var rather than config): XXXXXXXXXXXX

You can also log in with a user ID:

C:#############>clarifai login --user_id alfrick context name (default: "default"): my_new_context personal access token value (default: "ENVVAR" to get out of env var rather than config): XXXXXXXXXX

You can optionally specify a custom API URL if you are connecting to a Clarifai instance other than the default. Here is an example:

C:#############>clarifai login https://api-dev.clarifai.com/ context name (default: "default"): my_new_context user id: alfrick personal access token value (default: "ENVVAR" to get out of env var rather than config): XXXXXXXXXXXX

Clarifai Config

The clarifai config commands help you manage your CLI configuration, including the different contexts used to interact with the Clarifai API.

This command provides subcommands to manage various aspects of your CLI configuration settings.

Display Current Context

The current-context (alias current) subcommand displays the currently active CLI context. This is useful when you have multiple contexts with different configurations and you want to ensure you're operating under the correct one.

clarifai config current-context // or clarifai config current

Here is an example:

C:#############>clarifai config current-context my_new_context

Display Configuration File

The dump (alias cat) subcommand displays the entire CLI configuration file (in YAML format) to your console. This is helpful for inspecting all your defined contexts and their associated details.

clarifai config dump // or clarifai config cat

Here is an example:

C:#############>clarifai config dump
contexts:
default:
CLARIFAI_API_BASE: https://api.clarifai.com
CLARIFAI_APP_ID: local-dev-runner-app
CLARIFAI_COMPUTE_CLUSTER_ID: local-dev-compute-cluster
CLARIFAI_DEPLOYMENT_ID: local-dev-deployment
CLARIFAI_MODEL_ID: local-dev-model
CLARIFAI_NODEPOOL_ID: local-dev-nodepool
CLARIFAI_PAT: XXXXXXXXXXXXXXXXXXX
CLARIFAI_RUNNER_ID: f35b7e4f3c774e48a8e54b74785debca
CLARIFAI_USER_ID: alfrick
my_new_context:
CLARIFAI_API_BASE: https://api.clarifai.com/
CLARIFAI_PAT: XXXXXXXXXXXX
CLARIFAI_USER_ID: alfrick
current_context: my_new_context

Edit Configuration File

The edit (alias e) subcommand opens the CLI configuration file in your default text editor, allowing you to manually add, modify, or delete contexts. This is often how you'd initially set up new contexts with different settings, such as PAT keys or application IDs.

Remember to save the file after making changes.

clarifai config edit // or clarifai config e

Output Environment Variables

The env (alias cat) subcommand outputs your currently active context in a format that can be directly sourced into your shell's environment.

It generates a string of shell commands that can be useful if you want to use these values in a script or another process that relies on environment variables rather than the Clarifai config file.

clarifai config env // or clarifai config cat

Here is an example:

C:#############>clarifai config env --help Usage: clarifai config env [OPTIONS]

Print env vars. Use: eval "$(clarifai config env)"

Options: --help Show this message and exit.

C:#############>clarifai config env export CLARIFAI_API_BASE="https://api.clarifai.com/" export CLARIFAI_PAT="XXXXXXXXXXXX" export CLARIFAI_USER_ID="alfrick"

Note: For Unix-like systems, running eval "$(clarifai config env)" configures your current shell session by loading Clarifai-related environment variables directly from your active CLI configuration. This automatically sets up authentication for subsequent Clarifai commands or scripts run within that same session, eliminating the need to manually enter credentials. It's particularly useful for scripting where environment variables are preferred for authentication and for quickly setting up a terminal session with the correct Clarifai credentials. For Windows, you'd typically need to run clarifai config env first, copy the output, and then manually run the set commands it generates.

List All Contexts

The get-contexts (alias list or ls) subcommand lists all Clarifai contexts defined in your configuration file, displayed in a table format. This provides an overview of the different Clarifai setups you can switch between.

clarifai config get-contexts // or clarifai config list // or clarifai config ls

Here is an example:

C::#############>clarifai config get-contexts
NAME USER_ID API_BASE PAT APP_ID COMPUTE_CLUSTER_ID DEPLOYMENT_ID MODEL_ID NODEPOOL_ID RUNNER_ID
default alfrick https://api.clarifai.com c02f7**** local-dev-runner-app local-dev-compute-cluster local-dev-deployment local-dev-model local-dev-nodepool f35b7e4f3c774e48a8e54b74785debca
* my_new_context alfrick https://api.clarifai.com/ XXXXX****

Switch Contexts

The use-context (alias use) subcommand switches the active Clarifai context to a different one that you have defined.

This is crucial when you want to interact with a different Clarifai application or use a different API key without manually changing it every time.

clarifai config use-context // or clarifai config use

Here is an example:

C:#############>clarifai config use-context my_other_project Set my_other_project as the current context

The Clarifai CLI will now use the my_other_project context for all subsequent commands (such as uploading models and generating predictions) until you switch it again.