Skip to main content

​
Overview

Cartesia’s CLI enables developers to create, deploy and manage their Voice Agents through the command line.

​
Installation

By running the quick install commands, you are accepting Cartesia’s Terms of Service (TOS). Please make sure to review the full TOS here before proceeding.
Install and download from our servers: 
curl -fsSL https://cartesia.sh | sh
And ask the CLI to self update: 
cartesia update

​
Quick Start

1

Login with API key

Authenticate with your Cartesia API key. To make an API key, go to play.cartesia.ai/keys and select your organization.
cartesia auth login  # paste your API key when prompted
2

Create an agent

Create a new agent from a template.
cartesia create my-agent
# Choose any template you like.
cd my-agent
3

Initialize your agent

Give your agent a name and link it to your organization.
cartesia init
4

Deploy your agent

Deploy your agent to make it available in the playground.
cartesia deploy

​
Features

​
Initialize a Project

Link any directory to a new or existing Cartesia agent: 
cartesia init
Create a project from a template: 
cartesia create
When are you working inside a project directory, the CLI will automatically detect the agent. You can skip passing --agent-id argument.Run cartesia status to see the current agent id.

​
Chat with Your Agent

Test the text reasoning logic for your voice agent locally. Terminal 1. Run your text logic fastapi server: 
PORT=8000 uv run python main.py
Terminal 2. Run the CLI to chat with your agent: 
cartesia chat 8000

​
Commands

​
Authentication

To get an API key, go to play.cartesia.ai/keys, select your organization, and generate a new key. 
cartesia auth login
To validate the existing API key: 
cartesia auth status
To logout (clears cached credentials): 
cartesia auth logout

​
Voice Agents

Deploy your agent to Cartesia cloud. 
cartesia deploy
List out all the agents in your organization: 
cartesia agents ls

​
Deployments

Deployments are versions of your agent running on Cartesia’s cloud. When we receive a new deployment, cartesia servers will rebuild the virtual environment, instantiate your project, and perform a health check to ensure it is ready to receive calls. To see all of your deployments: 
cartesia deployments ls
Check the status of a deployment: 
cartesia status [<deployment-id> or <agent-id>]

​
Environment Variables

Create, list, and remove environment variables for your agent. Set environment variables for your agent: 
cartesia env set API_KEY=FOOBAR MY_CONFIG=FOOBAZ
Environment variables are encrypted for storage and can only be accessed by your code.
Port environment variables from a .env file: 
cartesia env set --from .env

cat .env
API_KEY=FOOBAR
MY_CONFIG=FOOBAZ
Remove an environment variable: 
cartesia env rm <env-var-name>

​
Help Menu

For more details on any command: 
cartesia --help