> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI documentation

Create, deploy, and manage voice agents from the command line.

## Installation

<Warning>By running the quick install commands, you are accepting Cartesia's [Terms of Service (TOS)](https://cartesia.ai/legal/terms.html). Please make sure to review the full TOS here before proceeding.</Warning>

Install and download from our servers:

```zsh lines theme={null}
curl -fsSL https://cartesia.sh | sh
```

Update to the latest version:

```zsh lines theme={null}
cartesia update
```

## Quick Start

<Steps>
  <Step title="Login with API key">
    Authenticate with your Cartesia API key.
    To make an API key, go to [play.cartesia.ai/keys](https://play.cartesia.ai/keys) and select your organization.

    ```zsh lines theme={null}
    cartesia auth login  # paste your API key when prompted
    ```
  </Step>

  <Step title="Clone an example agent">
    Clone an example agent from the Line repository.

    ```zsh lines theme={null}
    cartesia create my-agent
    # Choose any example you like.
    cd my-agent
    ```
  </Step>

  <Step title="Initialize your agent">
    Give your agent a name and link it to your organization.

    ```zsh lines theme={null}
    cartesia init
    ```
  </Step>

  <Step title="Deploy your agent">
    Deploy your agent to make it available in the playground.

    ```zsh lines theme={null}
    cartesia deploy
    ```
  </Step>
</Steps>

## Features

### Initialize a Project

Link any directory to a new or existing Cartesia agent:

```zsh lines theme={null}
cartesia init
```

Create a project from an example:

```zsh lines theme={null}
cartesia create
```

<Tip>
  Inside a project directory, the CLI auto-detects the agent. Run `cartesia status` to see the current agent ID.
</Tip>

### Chat with Your Agent

Test your agent's text reasoning locally.

Terminal 1. Run your text logic fastapi server:

```zsh lines theme={null}
PORT=8000 uv run python main.py
```

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

```zsh lines theme={null}
cartesia chat 8000
```

## Commands

### Authentication

To get an API key, go to [play.cartesia.ai/keys](https://play.cartesia.ai/keys), select your organization, and generate a new key.

```zsh lines theme={null}
cartesia auth login
```

To validate the existing API key:

```zsh lines theme={null}
cartesia auth status
```

To logout (clears cached credentials):

```zsh lines theme={null}
cartesia auth logout
```

### Voice Agents

Deploy your agent to Cartesia cloud.

```zsh lines theme={null}
cartesia deploy
```

List out all the agents in your organization:

```zsh lines theme={null}
cartesia agents ls
```

#### Managed Deployments

Versions of your agent running on Cartesia's cloud. Each deployment rebuilds the environment, instantiates your project, and runs a health check.

To see all of your deployments:

```zsh lines theme={null}
cartesia deployments ls
```

Check the status of a deployment:

```zsh lines theme={null}
cartesia status [<deployment-id> or <agent-id>]
```

#### Self-Hosted Agent Code

While Cartesia's managed deployments are the simplest way to deploy low-latency voice agents, if you'd like to manage your own deployments of your agent code, you can pass us a URL for your agent to connect to during calls.

Connect an existing agent to your self-hosted code:

```zsh lines theme={null}
cartesia connect --agent-id <agent-id> --url https://my-agent.example.com
```

Or run without `--agent-id` to interactively select an existing agent or create a new one:

```zsh lines theme={null}
cartesia connect --url https://my-agent.example.com
```

Disconnect an agent from your self-hosted code:

```zsh lines theme={null}
cartesia disconnect --agent-id <agent-id>
```

### Environment Variables

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

Set environment variables for your agent:

```zsh lines theme={null}
cartesia env set API_KEY=FOOBAR MY_CONFIG=FOOBAZ
```

<Warning icon="lock">
  Environment variables are encrypted for storage and can only be accessed by your code.
</Warning>

Port environment variables from a `.env` file:

```zsh lines theme={null}
cartesia env set --from .env
```

```text .env theme={null}
API_KEY=FOOBAR
MY_CONFIG=FOOBAZ
```

Remove an environment variable:

```zsh lines theme={null}
cartesia env rm <env-var-name>
```

### Help Menu

For more details on any command:

```zsh lines theme={null}
cartesia --help
```