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.
- Unix-Like Systems
- Windows
export CLARIFAI_PAT=YOUR_PERSONAL_ACCESS_TOKEN_HERE
set CLARIFAI_PAT=YOUR_PERSONAL_ACCESS_TOKEN_HERE
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.
- CLI
clarifai COMMAND --help
For example:
- CLI
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
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."
- CLI
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.
- CLI
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.
- CLI
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.
- CLI
clarifai context delete CONTEXT_NAME_HERE
// or
clarifai context rm CONTEXT_NAME_HERE
Here is an example:
- CLI
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.
- CLI
clarifai context use CONTEXT_NAME_HERE
Here is an example:
- CLI
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.
- CLI
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.
- CLI
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:
- CLI
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:
- CLI
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.
- CLI
clarifai config current-context
// or
clarifai config current
Here is an example:
- CLI
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.
- CLI
clarifai config dump
// or
clarifai config cat
Here is an example:
- CLI
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.
- CLI
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.
- CLI
clarifai config env
// or
clarifai config cat
Here is an example:
- CLI
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 runclarifai config env
first, copy the output, and then manually run theset
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.
- CLI
clarifai config get-contexts
// or
clarifai config list
// or
clarifai config ls
Here is an example:
- CLI
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.
- CLI
clarifai config use-context
// or
clarifai config use
Here is an example:
- CLI
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.