CLI - Tavus

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.

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.

For the autonomous new-PAL loop, see Agentic PAL building & testing. 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.

Step 1: Install the package

uv tool install tavus-cli

Or run it without installing:

uvx --from tavus-cli tavus doctor

pip install tavus-cli

tavus-cli is the package name; confirm the package index you install from with your Tavus contact.

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 3: Verify the install

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.

Authenticate

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):

tavus auth login --api-key <your-key> --name "ci-key"

Check or clear credentials:

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:

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.

# Production (default)
tavus pal list

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

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.

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

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

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

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

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.

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

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

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

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.

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

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.

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

​Install

​Authenticate

​Browser login (recommended)

​API key fallback

​Environments

​JSON round-tripping

​Examples

​Command reference

​Top-level commands

​tavus auth

​tavus pal

​tavus pal tools

​tavus pal capabilities

​tavus pal skills

​tavus pal knowledge

​tavus face

​tavus conversation

​tavus resource

​tavus document

​tavus guardrail

​tavus objective

​tavus tool

​tavus skill

​tavus pronunciation-dictionary

​tavus builder

​tavus builder update

​tavus chat

Install

Authenticate

Browser login (recommended)

API key fallback

Environments

JSON round-tripping

Examples

Command reference

Top-level commands

`tavus auth`

`tavus pal`

`tavus pal tools`

`tavus pal capabilities`

`tavus pal skills`

`tavus pal knowledge`

`tavus face`

`tavus conversation`

`tavus resource`

`tavus document`

`tavus guardrail`

`tavus objective`

`tavus tool`

`tavus skill`

`tavus pronunciation-dictionary`

`tavus builder`

`tavus builder update`

`tavus chat`