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, etc
pipeline-step (pipelinestep, ps)
Manage pipeline steps: upload, test, 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.
- CLI
clarifai COMMAND --help
For example:
- CLI
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
- CLI
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 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
- CLI
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.
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.
- CLI
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.
- CLI
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.
- CLI
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 (set-context) Create a new context.
current-context Show the current context's details.
delete-context 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) List all available contexts.
use-context Set the current context.
view (show) Display the current configuration.
Create Context
The create-context
(or set-context
) 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.
If you'd like to use the default values (such as the base-url
), simply press Enter.
- CLI
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:
- CLI
Usage: clarifai config set-context [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:
- CLI
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:
- CLI
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
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.
- CLI
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.
Here is how you can show the currently active context:
- CLI
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:
- CLI
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:
- CLI
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:
- CLI
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
subcommand deletes an existing Clarifai context.
- CLI
Usage: clarifai config delete-context [OPTIONS] NAME
Delete a context.
Here is how you can delete a context by specifying its name:
- CLI
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.
- CLI
Usage: clarifai config edit [OPTIONS]
Open the configuration file for editing.
Or:
- CLI
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:
- CLI
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.
- CLI
Usage: clarifai config env [OPTIONS]
Print env vars for the active context.
Or:
- CLI
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:
- CLI
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
) 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.
- CLI
Usage: clarifai config get-contexts [OPTIONS]
List all available contexts.
Options:
-o, --output-format [wide|name|json|yaml]
Or:
- CLI
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.
- CLI
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:
- CLI
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:
- CLI
clarifai config get-contexts --output-format json
Here is how you can output context data as YAML:
- CLI
clarifai config get-contexts -o yaml
Switch Contexts
The use-context
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.
- CLI
Usage: clarifai config use-context [OPTIONS] NAME
Set the current context.
Here’s how you can switch to a different context by specifying its name:
- CLI
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.
- CLI
Usage: clarifai config view [OPTIONS]
Display the current configuration.
Options:
-o, --output-format [json|yaml]
Or:
- CLI
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.
- CLI
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:
- CLI
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.
- CLI
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:
- CLI
clarifai model init
Here is how to initialize a model in a new directory:
- CLI
clarifai model init my_custom_model
This will create a directory my_custom_model
with the standard model structure inside it.
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:
- CLI
clarifai model init --model-type-id mcp
Here is how to initialize an MCP model in a specific path:
- CLI
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:
- CLI
clarifai model init --model-type-id openai
Here is how to initialize an OpenAI-compatible model in a specific path:
- CLI
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:
- CLI
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:
- CLI
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:
- CLI
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
andYOUR_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:
- CLI
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:
- CLI
clarifai model init --toolkit ollama --model-name gemma3n --port 8008 --context-length 16000
Learn how to run Ollama models using Clarifai Local Runners here.