> ## 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-cli` 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-cli
        ```

        Or run it without installing:

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

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

    <Note>
      `tavus-cli` 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"

# 7. Turn on built-in PAL Maker capabilities (Web Search, then Slide Presenter)
tavus pal capabilities attach <pal_id> web_search
tavus pal capabilities attach <pal_id> slide_presenter \
  --document-id <document_id> --slides-trigger walk_the_deck

# 8. Create a Knowledge document from a URL and attach it to a PAL
tavus document create --url https://example.com/handbook.pdf --tag onboarding
tavus pal knowledge add <pal_id> --document-id <document_id>
```

## 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 pal capabilities`

Manage the built-in PAL Maker capabilities - Magic Canvas, Slide Presenter, Web Search, Perception, and Memory - with friendly IDs instead of raw JSON Patch. Accepted capability IDs are `magic_canvas`, `slide_presenter`, `web_search`, `perception`, and `memory` (the portal IDs `builtin:magic_canvas`, `builtin:slide_presenter`, `builtin:web_search`, and `skill:memory` also work).

| Command                                         | What it does                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pal capabilities catalog`                      | List the five PAL Maker capabilities and their backend mappings.                                                                                                                                                                                                                                                                                                                                                  |
| `pal capabilities list <pal_id>`                | Show Magic Canvas, Slide Presenter, Web Search, Perception, and Memory attachment state and config for a PAL.                                                                                                                                                                                                                                                                                                     |
| `pal capabilities attach <pal_id> <capability>` | Attach a capability by friendly or portal ID. Capability-specific options: `--document-id`, `--slides-trigger`, `--prompt` (Slide Presenter); `--component`, `--usage-guidance`, `--scheduling-url`, `--scheduling-provider` (Magic Canvas); `--perception-model`, `--visual-query`, `--audio-query`, `--visual-tool-prompt`, `--audio-tool-prompt` (Perception). Also `--config`/`--config-file` for raw config. |
| `pal capabilities patch <pal_id> <capability>`  | Update the config of an already-attached capability. Same options as `attach`.                                                                                                                                                                                                                                                                                                                                    |
| `pal capabilities detach <pal_id> <capability>` | Detach a capability. For Perception this sets the perception model to off.                                                                                                                                                                                                                                                                                                                                        |

<Note>
  Magic Canvas, Slide Presenter, Web Search, and Memory persist through the PAL's skills (`/pals/{id}/skills`); Perception persists through `layers.perception`. `pal capabilities` handles that difference for you - prefer it over `pal skills` for these five.
</Note>

#### `tavus pal skills`

Lower-level access to the raw RQH skills attached to a PAL. Use `pal capabilities` for the five PAL Maker capabilities; reach for `pal skills` only when you need to work with a skill by its raw registry ID.

| Command                                 | What it does                                                              |
| --------------------------------------- | ------------------------------------------------------------------------- |
| `pal skills list <pal_id>`              | List raw RQH skills attached to a PAL.                                    |
| `pal skills attach <pal_id> <skill_id>` | Attach or replace one raw RQH skill. `--config`, `--config-file`.         |
| `pal skills patch <pal_id> <skill_id>`  | Merge config into an already-attached skill. `--config`, `--config-file`. |
| `pal skills detach <pal_id> <skill_id>` | Detach one raw RQH skill from a PAL.                                      |

#### `tavus pal knowledge`

Manage a PAL's Knowledge section - the `document_ids` and `document_tags` it draws on for retrieval, plus RAG tuning under `layers.knowledge_base`. Create the underlying documents first with [`tavus document`](#tavus-document).

| Command                                | What it does                                                                                                                                                                                                                     |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pal knowledge list <pal_id>`          | Show attached document IDs, tags, resolved document records, and `knowledge_base` layer settings.                                                                                                                                |
| `pal knowledge add <pal_id>`           | Attach documents or document tags. `--document-id`, `--document-tag` (both repeatable).                                                                                                                                          |
| `pal knowledge remove <pal_id>`        | Remove documents or document tags. `--document-id`, `--document-tag`.                                                                                                                                                            |
| `pal knowledge replace <pal_id>`       | Replace the PAL's document and tag selections. `--document-id`, `--document-tag`.                                                                                                                                                |
| `pal knowledge settings <pal_id>`      | Patch RAG tuning under `layers.knowledge_base`. `--rag-score-threshold`, `--rag-n-chunks`, `--rag-surrounding-chunk-radius`, `--rag-observability`/`--no-rag-observability`, `--procedure-goalchain`/`--no-procedure-goalchain`. |
| `pal knowledge upload <pal_id> <file>` | Upload a local file as a Knowledge document and attach it to the PAL. Same upload options as [`tavus document upload`](#tavus-document), plus `--attach`/`--upload-only`. Requires `TAVUS_PORTAL_BEARER_TOKEN`.                  |

### `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 document`

Manage Knowledge documents - the account-level records that back a PAL's Knowledge section. With a normal Tavus API key you can create documents from an already-reachable URL; local file upload uses the same portal-only path as PAL Maker (local file → tavus-api upload/S3 URL → document record) and therefore requires a Firebase portal bearer token in `TAVUS_PORTAL_BEARER_TOKEN`. Attach documents to a PAL with [`tavus pal knowledge`](#tavus-pal-knowledge).

| Command                          | What it does                                                                                                                                                                                                                                                                                                                     |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document list`                  | List Knowledge documents. `--limit`, `--page`, `--status`, `--tag`, `--participant-tag`, `--name-or-uuid`, `--verbose`/`--compact`, `--json`.                                                                                                                                                                                    |
| `document get <document_id>`     | Get one Knowledge document record. `--verbose`.                                                                                                                                                                                                                                                                                  |
| `document create`                | Create a document from an already-hosted URL. `--url` (required), `--name`, `--tag`, `--participant-tag`, `--crawl-depth`, `--crawl-max-pages`, `--custom-description`, `--customer-support`/`--regular-document`, `--standard-extraction`.                                                                                      |
| `document upload <file>`         | Upload a local file through tavus-api, then create the document record. Requires `TAVUS_PORTAL_BEARER_TOKEN`. `--name`, `--tag`, `--participant-tag`, `--custom-description`, `--customer-support`/`--regular-document`, `--font-size-aware-extraction`/`--standard-extraction`, `--bucket-name`, `--region`, `--sign-duration`. |
| `document tags`                  | List document tags available for Knowledge attachment. `--search`, `--page`, `--limit`.                                                                                                                                                                                                                                          |
| `document chunks <document_id>`  | Read the extracted chunks RQH indexed for a document. `--collection` (default `regular`), `--limit`, `--offset`.                                                                                                                                                                                                                 |
| `document recrawl <document_id>` | Trigger a recrawl for a crawl-backed document. `--crawl-depth`, `--crawl-max-pages`.                                                                                                                                                                                                                                             |

<Tip>
  Use `document chunks` to inspect what RQH actually ingested before making claims about a document's contents - it returns the indexed text, not the source file.
</Tip>

### `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 skill`

Browse the RQH skill registry - the skills that back PAL capabilities. This lists what is available to attach; attach and configure per-PAL with [`tavus pal capabilities`](#tavus-pal-capabilities) or [`tavus pal skills`](#tavus-pal-skills).

| Command                | What it does                                  |
| ---------------------- | --------------------------------------------- |
| `skill list`           | List RQH skills that can be attached to PALs. |
| `skill get <skill_id>` | Get one RQH skill registry entry.             |

### `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.                                                     |