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 SDK package.

pip install --upgrade clarifai

Once installed, you can confirm the version by running the following command:

clarifai --version

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:
  --version       Show the version and exit.
  --config TEXT   Path to config file
  --context TEXT  Context to use for this command
  --help          Show this message and exit.

Commands:
  artifact (af)                   Manage Artifacts: create, upload, download,
                                  list, get, delete
  computecluster (cc)             Manage Compute Clusters: create, delete,
                                  list
  config                              Manage multiple configuration profiles
                                      (contexts).
                                  
                                      Authentication Precedence:
                                  
                                        1. Environment variables (e.g.,
                                        `CLARIFAI_PAT`) are used first if set.
                                        2. The settings from the active
                                        context are used if no environment
                                        variables are provided.
                                  
  deployment (dp)                 Manage Deployments: create, delete, list
  login                           Login command to set PAT and other
                                  configurations.
  logout                          Log out by clearing saved credentials.
                                  
                                      Without flags, an interactive menu is
                                      shown. Use flags for     programmatic /
                                      non-interactive usage.
                                  
                                          Examples:
                                            clarifai logout                        # Interactive
                                            clarifai logout --current              # Clear current context PAT
                                            clarifai logout --context staging      # Clear 'staging' PAT
                                            clarifai logout --context staging --delete  # Remove 'staging' entirely
                                            clarifai logout --all                  # Clear every context PAT
                                          
  model                           Manage & Develop Models: init, download-
                                  checkpoints, signatures, upload
                                  
                                      Run & Test Models Locally: local-runner,
                                      local-grpc, local-test
                                  
                                      Model Inference: list, predict
  nodepool (np)                   Manage Nodepools: create, delete, list
  pipeline (pl)                   Manage pipelines: upload, init, list, etc
  pipeline-step (pipelinestep, ps)
                                  Manage pipeline steps: upload, test, list,
                                  etc
  pipelinerun (pr)                Manage Pipeline Version Runs: pause, cancel,
                                  resume, monitor
  pipelinetemplate (pt)           Manage pipeline templates: list, discover,
                                  etc
  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 login --help

Produces this output:

Usage: clarifai login [OPTIONS] [API_URL]

  Login command to set PAT and other configurations.

Options:
  --user_id TEXT  User ID
  --help          Show this message and exit.

clarifai login [OPTIONS] [API_URL]

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

Note: To find your Clarifai user ID, open the collapsible left sidebar and click Settings, then select Account from the dropdown — your user ID is listed there. From the same Settings menu, select Secrets to generate a new PAT or copy an existing one.

Authentication Precedence

Authentication follows a defined order of precedence. If you set values (such as CLARIFAI_PAT) as environment variables in your terminal, these take priority and are used first. If no relevant environment variables are found, the CLI falls back to the credentials and settings defined in the active context. For security best practices, we recommend using environment variables instead of hardcoding credentials directly in your code.

Here is an example of setting PAT as an environment variable:

Unix-Like Systems
Windows

export CLARIFAI_PAT=YOUR_PERSONAL_ACCESS_TOKEN_HERE

set CLARIFAI_PAT=YOUR_PERSONAL_ACCESS_TOKEN_HERE

Log in

clarifai login

The clarifai login command will prompt you to enter your Clarifai user ID and PAT. The PAT input field is masked for security purposes — simply paste the value and press Enter.

Note: The masked field supports Backspace (delete one character), Ctrl+U (clear the entire line), Ctrl+W (delete the last word), and Ctrl+C (cancel input).

After you provide your credentials, they’re validated automatically, and you’ll be notified immediately if there are any errors. A default context (default) is also created for you automatically.

Example

clarifai login
Enter your Clarifai user ID: alfrick

> To authenticate, you'll need a Personal Access Token (PAT).
> Create one at: https://clarifai.com/alfrick/settings/secrets
> Tip: Set CLARIFAI_PAT environment variable to skip this prompt.

Enter your Personal Access Token (PAT): ********************************

> Verifying token...
✅ Success! You're logged in as alfrick
💡 Tip: Use `clarifai config` to manage multiple accounts or environments
[INFO] 10:39:07.660424 Login successful for user 'alfrick' in context 'default' |  thread=8480497856 

What is a 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 user ID) you want to work with.

Log in With a User ID

You can log in using your user ID.

clarifai login --user_id your_user_id_here

Example

clarifai login --user_id alfrick

> To authenticate, you'll need a Personal Access Token (PAT).
> Create one at: https://clarifai.com/alfrick/settings/secrets
> Tip: Set CLARIFAI_PAT environment variable to skip this prompt.

Enter your Personal Access Token (PAT): ********************************

> Verifying token...
✅ Success! You're logged in as alfrick
💡 Tip: Use `clarifai config` to manage multiple accounts or environments
[INFO] 11:59:31.377843 Login successful for user 'alfrick' in context 'default' |  thread=8480497856 

Log in With a Custom API URL

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

clarifai login your_custom_url_here

Example

clarifai login https://api-dev.clarifai.com/
Enter your Clarifai user ID: alfrick

> To authenticate, you'll need a Personal Access Token (PAT).
> Create one at: https://clarifai.com/alfrick/settings/secrets
> Tip: Set CLARIFAI_PAT environment variable to skip this prompt.

Enter your Personal Access Token (PAT): ********************************

> Verifying token...

Clarifai Logout

clarifai logout [OPTIONS]

The clarifai logout command is used to securely remove saved PATs and credentials from your local environment. By default, the command launches an interactive menu. You can also use flags for non-interactive or scripted workflows.

This is useful when rotating credentials, switching accounts, or cleaning up unused contexts.

Interactive Logout

When run without any flags, the command shows the currently active context and launches an interactive, numbered menu for you to select an action.

clarifai logout

These are the menu menu options:

1. Switch to another context — Lists all other available contexts along with their associated user IDs and allows you to select one. No credentials are cleared. If only a single context exists, the CLI informs you that there are no other contexts to switch to.

2. Log out of current context (clear credentials) — Clears the PAT from the active context’s configuration. The context itself (including user_id and api_base) is preserved, allowing you to re-authenticate later using clarifai login without re-entering all details.

3. Log out and delete current context — Removes the entire context entry, including credentials and metadata. If the current context is the only one available, the CLI clears the PAT but retains the context (at least one context must always exist). If other contexts are available, the CLI automatically switches the active context to the next available one.

4. Log out of all contexts — Clears the PAT from every configured context in the local config file. This option is useful on shared machines or in security-sensitive environments.

5. Cancel — Exits the menu without making any changes.

Example

clarifai logout

Current context is configured for user 'alfrick' (context: 'default', api: https://api.clarifai.com)

  1. Switch to another context
  2. Log out of current context (clear credentials)
  3. Log out and delete current context
  4. Log out of all contexts
  5. Cancel

Enter choice: 

Clear Current Session

You can log out of the context you are currently using without deleting the context settings.

clarifai logout --current

Example

clarifai logout --current
Logged out of context 'default'.

To also remove the context entry itself, use the --delete flag.

clarifai logout --current --delete

Caution: Use the --delete flag with caution. Clearing a PAT only requires you to log in again, but deleting a context removes the named reference entirely, requiring you to recreate it manually if needed later.

Targeted Context Logout

You can log out of a specific named context without deleting the context settings.

clarifai logout --context context-name

Example

clarifai logout --context default     
Logged out of context 'default'.

To also remove the context entry itself, use the --delete flag.

clarifai logout --context context-name --delete

Total Reset

You can clear all saved credentials across every configured context at once. This is useful for security auditing or starting fresh.

clarifai logout --all

Environment Variable Warning

After any logout action, if the CLARIFAI_PAT environment variable is still set, the CLI displays a warning:

Warning: CLARIFAI_PAT environment variable is still set. Run `unset CLARIFAI_PAT` (Linux/macOS) or `$env:CLARIFAI_PAT = ''` (PowerShell) to fully log out.

This warning is important because environment variables take precedence over values stored in the config file. As a result, clearing credentials from the config alone does not fully log you out if CLARIFAI_PAT is still defined.

Clarifai Config

The clarifai config command lets you create and manage various aspects of your Clarifai configuration profiles — known as contexts — which represent different interaction environments or setups, as explained earlier.

Each context can store specific authentication details (such as PATs), API URLs, and other configuration settings relevant to a particular Clarifai project or environment.

This command includes subcommands for creating, deleting, and switching between named Clarifai contexts, among other actions.

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

  Manage multiple configuration profiles (contexts).

  Authentication Precedence:

    1. Environment variables (e.g., `CLARIFAI_PAT`) are used first if set.
    2. The settings from the active context are used if no environment
    variables are provided.

Options:
  --help  Show this message and exit.

Commands:
  create-context (create)         Create a new context.
  current-context (current)       Show the current context's details.
  delete-context (delete)         Delete a context.
  edit (e)                        Open the configuration file for editing.
  env (get-env)                   Print env vars for the active context.
  get-contexts (list-contexts, ls)
                                  List all available contexts.
  use-context (use)               Set the current context.
  view (show)                     Display the current configuration.

Create Context

The create-context (or create) subcommand creates a new Clarifai context. Note that you'll be prompted to configure the context by providing the necessary details for that context — such as user ID, API URL, and PAT.

note

If you'd like to use the default values (such as the base-url), simply press Enter.

Usage: clarifai config create-context [OPTIONS] NAME
Create a new context.
Options:
--user-id TEXT   User ID
--base-url TEXT  Base URL
--pat TEXT       Personal access token

Or:

Usage: clarifai config create [OPTIONS] NAME
Create a new context.
Options:
--user-id TEXT   User ID
--base-url TEXT  Base URL
--pat TEXT       Personal access token

Here is how you can create a new context by providing a unique name for it:

clarifai config create-context your_context_name_here

Example

clarifai config create-context my_new_context
user id: XXXX
base url (default: https://api.clarifai.com):
personal access token value (default: "ENVVAR" to get our of env var rather than config): XXXX
[INFO] 20:05:52.602933 Validating the Context Credentials... |  thread=21200
[INFO] 20:05:59.957903 ✅ Context is valid |  thread=21200
[INFO] 20:05:59.970741 Context 'my_new_context' created successfully |  thread=21200

Here is how you can create a new context with all values specified inline:

clarifai config create-context your_context_name_here --user-id your_user_id_here --pat your_pat_here --base-url https://api.clarifai.com

Example

[INFO] 21:00:58.015800 Validating the Context Credentials... |  thread=20976
[INFO] 21:00:59.414716 ✅ Context is valid |  thread=20976
[INFO] 21:00:59.424841 Context 'my_new_context' created successfully |  thread=20976

Display Current Context

The current-context (or current) subcommand displays the details of the currently active Clarifai context. It helps you verify which context is in use and view its associated configuration, such as the user ID, PAT, and base URL.

Usage: clarifai config current-context [OPTIONS]

  Show the current context's details.

Options:
  -o, --output-format [name|json|yaml]

Note: The -o flag is the short form of the --output-format flag.

Or:

Usage: clarifai config current [OPTIONS]

  Show the current context's details.

Options:
  -o, --output-format [name|json|yaml]

Here is how you can show the currently active context:

clarifai config current-context

Example

clarifai config current-context
my_new_context

Here is how you can show only the name of the current context:

clarifai config current-context --output-format name

Example

clarifai config current-context --output-format name
my_new_context

Here is how you can show context details in JSON format:

clarifai config current-context -o json

Example

clarifai config current-context -o json
{"CLARIFAI_API_BASE": "https://api.clarifai.com", "CLARIFAI_PAT": "XXXX", "CLARIFAI_USER_ID": "XXXX"}

Here is how you can show context details in YAML format:

clarifai config current-context -o yaml

Example

clarifai config current-context -o yaml
CLARIFAI_API_BASE: https://api.clarifai.com
CLARIFAI_PAT: XXXX
CLARIFAI_USER_ID: XXXX

Delete Context

The delete-context or (delete) subcommand deletes an existing Clarifai context.

Usage: clarifai config delete-context [OPTIONS] NAME

  Delete a context.

Or:

Usage: clarifai config delete [OPTIONS] NAME

  Delete a context.

Here is how you can delete a context by specifying its name:

clarifai config delete-context your_context_name_here

Example

clarifai config delete-context my_new_context
my_new_context deleted

Edit Configuration File

The edit (alias e) subcommand opens the CLI configuration file for the current context in your default text editor. This allows you to manually add, modify, or remove contexts and their settings — such as PATs, application IDs, or base URLs.

This is a useful way to set up or manage multiple contexts directly.

Note: Remember to save the file after making changes.

Usage: clarifai config edit [OPTIONS]

  Open the configuration file for editing.

Or:

Usage: clarifai config e [OPTIONS]

  Open the configuration file for editing.

Here is how you can open the configuration file of your current context for editing:

clarifai config edit

Display Environment Variables

The env (or get-env) subcommand prints the environment variables that correspond to your active Clarifai context. It’s useful if you want to export these variables for use in other tools, scripts, or terminals.

Usage: clarifai config env [OPTIONS]

  Print env vars for the active context.

Or:

Usage: clarifai config get-env [OPTIONS]

  Print env vars for the active context.

Here is how you can display the environment variables of your current context:

clarifai config env

Example

clarifai config env
export CLARIFAI_API_BASE="https://api.clarifai.com"
export CLARIFAI_PAT="XXXX"
export CLARIFAI_USER_ID="XXXX"

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.

Get All Contexts

The get-contexts (or list-contexts, or ls) subcommand lists all Clarifai contexts defined in your configuration file, displayed in a table format. The currently active context is marked with an asterisk (*).

This provides an overview of the different Clarifai setups you can switch between.

Usage: clarifai config get-contexts [OPTIONS]

  List all available contexts.

Options:
  -o, --output-format [wide|name|json|yaml]

Or:

Usage: clarifai config list-contexts [OPTIONS]

  List all available contexts.

Options:
  -o, --output-format [wide|name|json|yaml]

Note: The -o flag is the short form of the --output-format flag.

Here’s how you can list all contexts in a table. By default, the wide output format is used, which displays a detailed table with information for each context.

clarifai config get-contexts

Example

clarifai config get-contexts
    NAME                    USER_ID    API_BASE                  PAT
    default                 XXXX      https://api.clarifai.com  c1eaa****
*   my_new_context          XXXX      https://api.clarifai.com  c1eaa****
    test_context            XXXX      https://api.clarifai.com  c1eaa****

Here is how you can list only the names of the contexts:

clarifai config get-contexts -o name

Example

clarifai config get-contexts -o name
default
my_new_context
test_context

Here is how you can output context data as JSON:

clarifai config get-contexts --output-format json

Here is how you can output context data as YAML:

clarifai config get-contexts -o yaml

Switch Contexts

The use-context (or use) subcommand sets a different Clarifai context as the active one. This is useful when you need to switch between environments or credentials without manually updating your configuration each time.

Usage: clarifai config use-context [OPTIONS] NAME

  Set the current context.

Or:

Usage: clarifai config use [OPTIONS] NAME

  Set the current context.

Here’s how you can switch to a different context by specifying its name:

clarifai config use-context your_context_name_here

The Clarifai CLI will now use the new specified context for all subsequent operations.

Example

clarifai config use-context test_context
Set test_context as the current context

Display Current Configuration

The view (or show) subcommand displays the full configuration file, including all defined contexts and their associated details. The currently active context is also indicated in the output.

Usage: clarifai config view [OPTIONS]

  Display the current configuration.

Options:
  -o, --output-format [json|yaml]

Or:

Usage: clarifai config show [OPTIONS]

  Display the current configuration.

Options:
  -o, --output-format [json|yaml]

Note: The -o flag is the short form of the --output-format flag.

Here’s how to display the current configuration. By default, the output is shown in YAML format.

clarifai config show

Example

clarifai config show
contexts:
  default:
    CLARIFAI_USER_ID: alfrick
  my_new_context:
    CLARIFAI_API_BASE: https://api.clarifai.com
    CLARIFAI_PAT: XXXX
    CLARIFAI_USER_ID: XXXX
  test_context:
    CLARIFAI_API_BASE: https://api.clarifai.com
    CLARIFAI_PAT: XXXX
    CLARIFAI_USER_ID: XXXX
current-context: test_context

Here is how you can display the current configuration in JSON format:

clarifai config show --output-format json

Example

clarifai config show --output-format json
{
  "current-context": "test_context",
  "contexts": {
    "default": {
      "CLARIFAI_USER_ID": "alfrick"
    },
    "my_new_context": {
      "CLARIFAI_API_BASE": "https://api.clarifai.com",
      "CLARIFAI_PAT": "XXXX",
      "CLARIFAI_USER_ID": "XXXX"
    },
    "test_context": {
      "CLARIFAI_API_BASE": "https://api.clarifai.com",
      "CLARIFAI_PAT": "XXXX",
      "CLARIFAI_USER_ID": "XXXX"
    }
  }
}

Clarifai Model Init

The clarifai model init command initializes a new Clarifai model directory structure. This command helps you set up the necessary files and folders to begin building a custom model suitable for the Clarifai platform.

 clarifai model init [OPTIONS] [MODEL_PATH] 

The command creates a standardized directory structure in the specified MODEL_PATH. If MODEL_PATH is not provided, the command will use the current directory by default.

The generated structure includes:

├── 1/
│   └── model.py
├── requirements.txt
└── config.yaml

1/ — A directory that holds the model file (Note that the folder is named as 1)
- model.py — This file will contain the Python code for your Clarifai model. You will define your model's logic and how it interacts with the Clarifai platform within this file.
requirements.txt — This file is used to list any Python dependencies your model requires. When your model is deployed, Clarifai will install these dependencies.
config.yaml — This YAML file is used for model configuration, allowing you to define settings and parameters for your model.

Basic Initialization

If no option value is provided, the command defaults to initializing the standard ModelClass.

Here is how to initialize a model in the current directory with the default model class:

clarifai model init

Here is how to initialize a model in a new directory:

clarifai model init my_custom_model

This will create a directory my_custom_model with the standard model structure inside it.

note

The --model-type-id option specifies the type of model class to initialize. This ensures that the generated files are tailored to the chosen model type.

Initialize `mcp` Model Type

Providing the mcp option initializes the model structure using MCPModelClass, which is used for models that will run on Clarifai using the Model Context Protocol (MCP).

Here is how to initialize an MCP model in the current directory:

clarifai model init --model-type-id mcp

Here is how to initialize an MCP model in a specific path:

clarifai model init /home/username/Projects/MyMCPModel --model-type-id mcp

Initialize `openai` Model Type

Providing the openai option initializes the model structure using OpenAIModelClass, intended for models that integrate with OpenAI's APIs.

Here is how to initialize an OpenAI-compatible model in the current directory:

clarifai model init --model-type-id openai

Here is how to initialize an OpenAI-compatible model in a specific path:

clarifai model init /home/username/Projects/MyOpenAIModel --model-type-id openai

Initialize With GitHub Template

You can initialize your model using a custom template from a GitHub repository using the --github-url option and providing the full repository URL.

Here is how to clone a public GitHub repository in the current directory:

clarifai model init --github-url https://github.com/Clarifai/runners-examples/tree/main/local-runners/ollama-model-upload

Here is how to clone a specific branch of a GitHub repository by including the branch reference directly in the URL:

clarifai model init --github-url https://github.com/Clarifai/runners-examples/tree/vllm-tool-calling

Here is how to clone a private GitHub repository using a GitHub Personal Access Token:

clarifai model init --github-url https://github.com/your-username/my-private-model --github-pat YOUR_GITHUB_PAT_TOKEN

Note: Replace https://github.com/your-username/my-private-model and YOUR_GITHUB_PAT_TOKEN with your actual values.

Initialize With Toolkit

You can initialize a new Clarifai model directory structure from a toolkit using the --toolkit option. Toolkits allow you to run large language models (LLMs) and other generative AI models locally on your own machine.

For example, here is how you can initialize a default model using the Ollama toolkit in the current directory:

clarifai model init --toolkit ollama

You can learn more about using toolkits here.

Installation​

Basics​

Clarifai Login​

Log in​

Log in With a User ID​

Log in With a Custom API URL​

Clarifai Logout​

Interactive Logout​

Clear Current Session​

Targeted Context Logout​

Total Reset​

Clarifai Config​

Create Context​

Display Current Context​

Delete Context​

Edit Configuration File​

Display Environment Variables​

Get All Contexts​

Switch Contexts​

Display Current Configuration​

Clarifai Model Init​

Basic Initialization​

Initialize mcp Model Type​

Initialize openai Model Type​

Initialize With GitHub Template​

Initialize With Toolkit​

Installation

Basics

Clarifai Login

Log in

Log in With a User ID

Log in With a Custom API URL

Clarifai Logout

Interactive Logout

Clear Current Session

Targeted Context Logout

Total Reset

Clarifai Config

Create Context

Display Current Context

Delete Context

Edit Configuration File

Display Environment Variables

Get All Contexts

Switch Contexts

Display Current Configuration

Clarifai Model Init

Basic Initialization

Initialize `mcp` Model Type

Initialize `openai` Model Type

Initialize With GitHub Template

Initialize With Toolkit