CLI documentation

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