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

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
  --help         Show this message and exit.

Commands:
  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.
  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
  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 other necessary configurations for making API requests.

Authentication Precedence

Authentication follows a specific order of precedence. If environment variables — such as CLARIFAI_PAT — are set, they take priority and are used first. If no relevant environment variables are provided, the CLI falls back to using the credentials and settings defined in the active context.

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 PAT and user ID. The PAT input field is hidden for security purposes — simply paste the value and press Enter.

After providing the credentials, they will be validated automatically, and you'll be notified if any errors occur.

Note: To generate or copy your PAT, go to the Security section of your personal settings page. Your user ID is also available under the Account section on the same page.

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.

You’ll also be prompted to enter a context name — this can be a new name, an existing one, or simply "default". The credentials will be saved to the specified context, which becomes the active context used for interacting with the Clarifai platform.

Example

clarifai login
To authenticate, you'll need a Personal Access Token (PAT).
You can create one from your account settings: https://clarifai.com/settings/security
Enter your Personal Access Token:
Enter your Clarifai user ID: XXXX
Verifying token...
[INFO] 17:29:42.188183 Validating the Context Credentials... |  thread=5816
[INFO] 17:29:43.832686 ✅ Context is valid |  thread=5816
Let's save these credentials to a new context.
You can have multiple contexts to easily switch between accounts or projects.
Enter a name for this context [default]: my_new_context
✅ Success! You are now logged in.
Credentials saved to the 'my_new_context' context.
💡 To switch contexts later, use `clarifai config use-context <name>`.
[INFO] 17:30:29.907399 Login successful for user 'XXXX' in context 'my_new_context' |  thread=5816

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 XXXX
To authenticate, you'll need a Personal Access Token (PAT).
You can create one from your account settings: https://clarifai.com/settings/security
Enter your Personal Access Token:
Verifying token...
[INFO] 18:08:00.158062 Validating the Context Credentials... |  thread=11532
[INFO] 18:08:06.153526 ✅ Context is valid |  thread=11532
Let's save these credentials to a new context.
You can have multiple contexts to easily switch between accounts or projects.
Enter a name for this context [default]: my_new_context
✅ Success! You are now logged in.
Credentials saved to the 'my_new_context' context.
💡 To switch contexts later, use `clarifai config use-context <name>`.
[INFO] 18:08:21.163966 Login successful for user 'XXXX' in context 'my_new_context' |  thread=11532

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/
To authenticate, you'll need a Personal Access Token (PAT).
You can create one from your account settings: https://clarifai.com/settings/security
Enter your Personal Access Token: 
Enter your Clarifai user ID: XXXX
Verifying token...
[INFO] 17:04:30.321616 Validating the Context Credentials... |  thread=23096

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"

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.

Currently, we support initialization using the Ollama toolkit.

Here is how to initialize a model using Ollama in the current directory:

clarifai model init --toolkit ollama

Additionally, you can specify different options when initializing a model from the Ollama library:

--model-name – Name of the Ollama model to use (default: llama3.2). This lets you specify any model from the Ollama library
--port – Port where the model is running (default: 23333)
--context-length – Define the context window size for the model in tokens (default: 8192)
--verbose – Enables detailed Ollama logs during execution. By default, logs are suppressed unless this option is specified.

Here is an example of initializing a gemma3n model with a context length of 16,000 tokens, running on port 8008:

clarifai model init --toolkit ollama --model-name gemma3n --port 8008 --context-length 16000

Learn more

Learn how to run Ollama models using Clarifai Local Runners here.

Installation​

Basics​

Clarifai Login​

Log in​

Log in With a User ID​

Log in With a Custom API URL​

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 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