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.

© 2025 Clarifai, Inc. All rights reserved