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:

1curl -fsSL https://cartesia.sh | sh

And ask the CLI to self update:

1cartesia 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.

1cartesia auth login # paste your API key when prompted
2

Create an agent

Create a new agent from a template.

1{{CREATE_COMMAND}} my-agent
2# Choose any template you like.
3cd my-agent
3

Initialize your agent

Give your agent a name and link it to your organization.

1cartesia init
4

Deploy your agent

Deploy your agent to make it available in the playground.

1cartesia deploy

Features

Initialize a Project

Link any directory to a new or existing Cartesia agent:

1cartesia init

Create a project from a template:

1cartesia 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:

1PORT=8000 uv run python main.py

Terminal 2. Run the CLI to chat with your agent:

1cartesia chat 8000

Commands

Authentication

To get an API key, go to play.cartesia.ai/keys, select your organization, and generate a new key.

1cartesia auth login

To validate the existing API key:

1cartesia auth status

To logout (clears cached credentials):

1cartesia auth logout

Voice Agents

Deploy your agent to Cartesia cloud.

1cartesia deploy

List out all the agents in your organization:

1cartesia 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:

1cartesia deployments ls

Check the status of a deployment:

1cartesia status [<deployment-id> or <agent-id>]

Environment Variables

Create, list, and remove environment variables for your agent.

Set environment variables for your agent:

1cartesia 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:

1cartesia env set --from .env
1cat .env
2API_KEY=FOOBAR
3MY_CONFIG=FOOBAZ

Remove an environment variable:

1cartesia env rm <env-var-name>

Help Menu

For more details on any command:

1cartesia --help