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.
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.
Step 1: Install the package
uv tool install tavus-mcp
uvx --from tavus-mcp tavus doctor
tavus-mcp 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 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
Browser login (recommended)
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"
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
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"
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.
| 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. |
| 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 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. |
