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

# CLI

> Install, authenticate, and drive the Tavus CLI to manage PALs, faces, conversations, and the agentic resource library from your terminal.

The Tavus CLI (`tavus`) is a Typer-based command-line client for the Tavus API. It manages PALs, faces, conversations, and the full agentic resource library (guardrails, objectives, tools, pronunciation dictionaries), plus the conversational PAL builder and text-only chat mode.

<Note>
  The CLI and the Tavus MCP server share the same backend client. Use the CLI for scripting and manual workflows; use MCP when an agent should drive Tavus through tools.
</Note>

For the autonomous new-PAL loop, see [Agentic PAL building & testing](/sections/agent-tools/pal-build-and-verify). The CLI command is `tavus pal build`; the MCP equivalent is `tavus_pal_build_and_verify`.

## Install

The CLI is distributed as the `tavus-mcp` Python package and exposes a `tavus` command on your `PATH`.

<Steps>
  <Step title="Step 1: Install the package">
    <Tabs>
      <Tab title="uv">
        ```bash theme={null}
        uv tool install tavus-mcp
        ```

        Or run it without installing:

        ```bash theme={null}
        uvx --from tavus-mcp tavus doctor
        ```
      </Tab>

      <Tab title="pip">
        ```bash theme={null}
        pip install tavus-mcp
        ```
      </Tab>
    </Tabs>

    <Note>
      `tavus-mcp` is the package name; confirm the package index you install from with your Tavus contact.
    </Note>
  </Step>

  <Step title="Step 2: Select an environment (optional)">
    The CLI defaults to the production environment (`PROD`). To target the test database, set `TAVUS_ENV=TEST` in your shell or pass `--env TEST` on any command.
  </Step>

  <Step title="Step 3: Verify the install">
    ```bash theme={null}
    tavus doctor
    ```

    `tavus doctor` prints the selected environment, the resolved API base URLs, the PAL Maker URL, and the auth source, then checks API reachability. Pass `--skip-network` to validate local configuration only.
  </Step>
</Steps>

## Authenticate

### Browser login (recommended)

```bash theme={null}
tavus auth login
```

This opens PAL Maker at `/dev/cli-authorize` with a loopback callback URL and an anti-CSRF state token. After you sign in, PAL Maker mints an API key for your account (tagged `source: cli`) and POSTs it back to the local loopback receiver. The CLI then stores the key in your OS keychain, scoped to the selected environment.

To store an existing key instead of opening the browser, pass `--api-key` (and optionally `--name` to label the minted key):

```bash theme={null}
tavus auth login --api-key <your-key> --name "ci-key"
```

Check or clear credentials:

```bash theme={null}
tavus auth status   # {env, authenticated, source}
tavus auth logout   # deletes the env-scoped keychain entry
```

### API key fallback

For automation, set `TAVUS_API_KEY` directly instead of using the keychain:

```bash theme={null}
TAVUS_API_KEY=... tavus pal list
```

Per-environment overrides are also supported: `TAVUS_TEST_API_KEY`, `TAVUS_STG_API_KEY`, and `TAVUS_PROD_API_KEY`.

## Environments

Every command accepts a global `--env` / `-e` option that sets `TAVUS_ENV`. Recognized values are `TEST`, `STG`, and `PROD` (default). When unset, the CLI targets `PROD`.

```bash theme={null}
# Production (default)
tavus pal list

# Test database
tavus --env TEST pal list
TAVUS_ENV=TEST tavus pal list
```

<Warning>
  The environment must match the portal that minted your API key. A `TEST` key used against a `PROD` environment (or vice versa) will return `401` on downstream Tavus API calls.
</Warning>

## JSON round-tripping

The CLI moves structured payloads through JSON consistently:

* Most commands print JSON by default; commands with table output expose a `--json` flag to switch to raw JSON.
* File inputs (`--file`, `--layers-file`, `--patch-file`) are parsed with `json.loads()`.
* The `pal patch` `--value` option attempts a JSON parse first, then falls back to a plain string if parsing fails, so wrap string values in quotes (e.g. `--value '"New Name"'`).
* Repeatable options (`--memory`, `--guardrail-id`, `--tag`, `--document-id`, etc.) are collected into lists in the request body.

## Examples

```bash theme={null}
# 1. List PALs as a table, then as JSON
tavus pal list --limit 10
tavus pal list --json

# 2. Inspect a PAL plus the account resources you can attach to it
tavus pal options <pal_id>

# 3. Rename a PAL with a validated JSON Patch (note the quoted JSON value)
tavus pal patch <pal_id> \
  --op replace --path /pal_name --value '"New Name"'

# 4. Validate a patch without sending it
tavus pal patch <pal_id> \
  --op replace --path /pal_name --value '"New Name"' --dry-run

# 5. Build a PAL through the conversational builder, then verify in chat mode
tavus pal build --prompt "I want a PAL for an office greeter" --json

# 6. Send one chat turn to a builder session
tavus builder chat <builder_id> --message "Make the greeting warmer"
```

## Command reference

All sub-apps support `-h` / `--help`, and invoking a sub-app with no arguments prints its help.

### Top-level commands

| Command                            | What it does                                                                                       |
| ---------------------------------- | -------------------------------------------------------------------------------------------------- |
| `tavus doctor`                     | Show environment, auth source, and API reachability. `--skip-network` validates local config only. |
| `tavus quickstart <system_prompt>` | Create a PAL and a conversation using a stock face by default. Options: `--name`, `--face-id`.     |
| `tavus embed <conversation_url>`   | Build an embed file manifest. `--target` (default `iframe`), `--write` to write files.             |

### `tavus auth`

| Command       | What it does                                                                              |
| ------------- | ----------------------------------------------------------------------------------------- |
| `auth login`  | Browser-based login that stores an env-scoped key in the keychain. `--api-key`, `--name`. |
| `auth logout` | Delete the env-scoped key from the keychain.                                              |
| `auth status` | Show whether credentials are available for the selected env.                              |

### `tavus pal`

| Command                | What it does                                                                                                                                                                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pal list`             | List PALs. `--limit`, `--page`, `--pal-type`, `--json`.                                                                                                                                                                                                                        |
| `pal get <pal_id>`     | Fetch a PAL as JSON. `--include-settings`.                                                                                                                                                                                                                                     |
| `pal create`           | Create a PAL. `--system-prompt`, `--name`, `--face-id`, `--pipeline-mode`, `--greeting`, `--context`, `--layers-file`, `--memory`, `--objectives-id`, `--guardrails-id`, `--guardrail-id`, `--guardrail-tag`, `--document-id`, `--document-tag`, `--template`/`--no-template`. |
| `pal delete <pal_id>`  | Delete a PAL.                                                                                                                                                                                                                                                                  |
| `pal patch <pal_id>`   | Apply a validated JSON Patch. `--op`, `--path`, `--value`, `--patch-file`, `--dry-run`.                                                                                                                                                                                        |
| `pal options <pal_id>` | Return the PAL plus valid account resources and patchable paths.                                                                                                                                                                                                               |
| `pal paths`            | List locally known JSON Patch paths for PALs.                                                                                                                                                                                                                                  |
| `pal build`            | Build a PAL via the conversational builder, then verify in chat mode. `--prompt`, `--face-id`, `--max-rounds`, `--json`.                                                                                                                                                       |
| `pal preview <pal_id>` | Start a full preview conversation and print the conversation URL. `--face-id`, `--name`, `--json`.                                                                                                                                                                             |

<Note>
  Tools are first-class objects: attach them after creating a PAL with `tavus pal tools attach` rather than inlining them at create time.
</Note>

#### `tavus pal tools`

| Command                                   | What it does                                      |
| ----------------------------------------- | ------------------------------------------------- |
| `pal tools list <pal_id>`                 | List tools attached to a PAL.                     |
| `pal tools attach <pal_id> <tool_ids...>` | Attach one or more existing tools to a PAL by ID. |
| `pal tools detach <pal_id> <tool_id>`     | Detach a tool from a PAL.                         |

### `tavus face`

| Command     | What it does                                                          |
| ----------- | --------------------------------------------------------------------- |
| `face list` | List faces. `--limit`, `--stock` (system/stock faces only), `--json`. |

### `tavus conversation`

| Command                              | What it does                                              |
| ------------------------------------ | --------------------------------------------------------- |
| `conversation create`                | Create a conversation. `--pal-id`, `--face-id`, `--name`. |
| `conversation end <conversation_id>` | End a conversation.                                       |

### `tavus resource`

| Command                                 | What it does                                                                                      |
| --------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `resource list <resource>`              | List a supported resource: `guardrails`, `objectives`, `documents`, `voices`, `tools`. `--limit`. |
| `resource get <resource> <resource_id>` | Get a single resource by ID.                                                                      |

### `tavus guardrail`

| Command                           | What it does                                                                                                                                   |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `guardrail list`                  | List guardrails (new flat shape by default). `--limit`, `--page`, `--type`, `--name-or-uuid`, `--tags`, `--legacy`, `--verbose`, `--json`.     |
| `guardrail get <guardrail_id>`    | Get a guardrail. `--verbose`, `--legacy`.                                                                                                      |
| `guardrail create`                | Create a flat guardrail. `--name`, `--prompt`, `--modality`, `--callback-url`, `--tool-call`, `--app-message`/`--no-app-message`, `--tag`.     |
| `guardrail patch <guardrail_id>`  | Patch a guardrail. `--file`, `--name`, `--prompt`, `--modality`, `--callback-url`, `--tool-call`, `--app-message`/`--no-app-message`, `--tag`. |
| `guardrail delete <guardrail_id>` | Delete a guardrail.                                                                                                                            |
| `guardrail tags`                  | List tags applied to the account's guardrails. `--search`, `--page`, `--limit`.                                                                |

### `tavus objective`

| Command                            | What it does                                                                              |
| ---------------------------------- | ----------------------------------------------------------------------------------------- |
| `objective list`                   | List objective sets. `--limit`, `--page`, `--type`, `--name-or-uuid`, `--sort`, `--json`. |
| `objective get <objectives_id>`    | Get an objective set.                                                                     |
| `objective create`                 | Create an objective set from a JSON file. `--file` (`{name, data, allow_loops}`).         |
| `objective patch <objectives_id>`  | Patch an objective set with JSON Patch ops. `--file`.                                     |
| `objective delete <objectives_id>` | Delete an objective set.                                                                  |
| `objective validate`               | Validate an objective-set payload without persisting. `--file`.                           |
| `objective example`                | Print a starter JSON body for `objective create --file`.                                  |

### `tavus tool`

| Command                 | What it does                                                                     |
| ----------------------- | -------------------------------------------------------------------------------- |
| `tool list`             | List tools. `--limit`, `--page`, `--type`, `--name-or-uuid`, `--sort`, `--json`. |
| `tool get <tool_id>`    | Get a tool.                                                                      |
| `tool create`           | Create a tool from a JSON file. `--file`.                                        |
| `tool patch <tool_id>`  | Patch a tool from a JSON file. `--file`.                                         |
| `tool delete <tool_id>` | Delete a tool.                                                                   |
| `tool example`          | Print a starter JSON body. `--delivery` (`app_message`, `http`, `http_oauth2`).  |

<Warning>
  When patching a tool, omit any secret fields you don't intend to change. The backend rejects PATCHes that echo back the scrubbed-secret placeholder (`********`) returned from a prior GET.
</Warning>

### `tavus pronunciation-dictionary`

| Command                                           | What it does                                                                 |
| ------------------------------------------------- | ---------------------------------------------------------------------------- |
| `pronunciation-dictionary list`                   | List pronunciation dictionaries. `--limit`, `--page`, `--sort`, `--json`.    |
| `pronunciation-dictionary get <dictionary_id>`    | Get a pronunciation dictionary.                                              |
| `pronunciation-dictionary create`                 | Create from a JSON file. `--file` (`{name, rules}`).                         |
| `pronunciation-dictionary patch <dictionary_id>`  | Patch from a JSON file. `--file` (supplying `rules` replaces the full list). |
| `pronunciation-dictionary delete <dictionary_id>` | Delete a pronunciation dictionary.                                           |
| `pronunciation-dictionary example`                | Print a starter JSON body.                                                   |

### `tavus builder`

| Command                                | What it does                                                                            |
| -------------------------------------- | --------------------------------------------------------------------------------------- |
| `builder create`                       | Start a builder session. `--name`, `--greeting`, `--pal-id`, `--model`.                 |
| `builder list`                         | List builder sessions. `--limit`, `--page`, `--pal-id`, `--name`, `--status`, `--json`. |
| `builder get <builder_id>`             | Fetch a single builder session.                                                         |
| `builder delete <builder_id>`          | Soft-delete a builder session.                                                          |
| `builder chat <builder_id>`            | Send a chat turn to the builder. `--message`, `--json`.                                 |
| `builder history <builder_id>`         | Print the chat transcript. `--limit`, `--json`.                                         |
| `builder append-messages <builder_id>` | Append raw `{role, content}` messages without invoking the LLM. `--file`.               |
| `builder publish <builder_id>`         | Mark the session complete and publish its PAL.                                          |

#### `tavus builder update`

| Command                                   | What it does                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------------- |
| `builder update objectives <builder_id>`  | Run an LLM update on the PAL's objectives. `--message`.                         |
| `builder update guardrails <builder_id>`  | Run an LLM update on the PAL's guardrails. `--message`.                         |
| `builder update greeting <builder_id>`    | Run an LLM refinement of the greeting. `--message`.                             |
| `builder update personality <builder_id>` | Refine PAL name and/or system prompt. `--message`, `--name`, `--system-prompt`. |

### `tavus chat`

| Command                       | What it does                                                                      |
| ----------------------------- | --------------------------------------------------------------------------------- |
| `chat start`                  | Start a text-only conversation against a PAL. `--pal-id`, `--greeting`, `--name`. |
| `chat turn <conversation_id>` | Send one user turn and print the reply as plain text. `--message`, `--timeout`.   |
| `chat end <conversation_id>`  | End a chat-mode conversation.                                                     |