tavus-cli

Agent-facing surfaces that let another agent (Claude, Codex, or any MCP-aware client) drive Tavus PAL creation end-to-end — separate from the human-facing PAL Maker.

What's here

• MCP server. PAL CRUD plus mutations for tools, KB, guardrails, pronunciation dicts, layers, and objectives. Local stdio for IDE-embedded clients, remote (Cloudflare Worker) for hosted agents.
• CLI. Scripted PAL authoring + publish. tavus pal list / options / patch, JSON round-tripping, OS-keychain auth.
• Codex skill. Publishable skill so an external agent can invoke the MCP server and CLI without reading the full Tavus API.

Why standalone (not under PAL Maker)

The PAL Maker project is the human builder — face-driven, in-product. This repo is for agents driving the API without that UI. Adjacent in code and concepts, but a different deliverable and audience.

The Tavus API exposes /v2/pals and /v2/faces as backwards-compatible vocabulary aliases over /v2/personas and /v2/replicas. This toolkit speaks the new pal/face vocabulary throughout.

Out of scope (for now)

• Face/video preview surfaces (live in the PAL Maker)
• Marketplace / sharing UX
• Multi-tenant auth beyond the existing dev-portal token model

Local Setup

uv sync --extra dev
cp .env.example .env

By default the CLI targets production (PROD). To switch to the test DB, either set TAVUS_ENV=TEST in .env / your shell or pass --env TEST to the CLI. You can set TAVUS_API_KEY directly for automation or run:

uv run tavus auth login

Examples:

# Production defaults; only the API key is required.
TAVUS_API_KEY=... uv run tavus pal list

# Test DB without URL overrides.
TAVUS_ENV=TEST TAVUS_API_KEY=... uv run tavus pal list
uv run tavus --env TEST pal list

The login flow opens the dev-portal at /dev/cli-authorize with a loopback callback URL and an anti-CSRF state. The dev-portal mints an API key for your signed-in user (tagged source: cli) and POSTs it back to the loopback receiver. The CLI stores that key in the OS keychain under the selected environment. No Firebase config lives in the CLI — the browser side handles all of it.

CLI

Install the CLI from PyPI:

uv tool install tavus-cli

Or run it without installing:

uvx --from tavus-cli tavus doctor

Local development commands:

uv run tavus doctor
uv run tavus pal list
uv run tavus pal options <pal_id>
uv run tavus pal patch <pal_id> --op replace --path /pal_name --value '"New Name"'
uv run tavus pal capabilities list <pal_id>
uv run tavus pal capabilities attach <pal_id> web_search
uv run tavus pal capabilities attach <pal_id> slide_presenter --document-id <document_id> --slides-trigger walk_the_deck
uv run tavus document create --url https://example.com/handbook.pdf --tag onboarding
TAVUS_PORTAL_BEARER_TOKEN=<firebase-id-token> uv run tavus document upload ./handbook.pdf --tag onboarding
uv run tavus pal knowledge add <pal_id> --document-id <document_id>
TAVUS_PORTAL_BEARER_TOKEN=<firebase-id-token> uv run tavus pal knowledge upload <pal_id> ./handbook.pdf

pal capabilities mirrors PAL Maker's built-in capability surface: Magic Canvas (magic_canvas), Slide Presenter (slide_presenter), Web Search (web_search), Perception (perception), and Memory (memory). The first, second, third, and fifth map to RQH PAL skills; Perception maps to layers.perception.

document and pal knowledge mirror PAL Maker's Knowledge section. With a normal Tavus API key, create Knowledge documents from an already reachable URL via RQH /v2/documents. Local file upload uses the same portal-only flow as PAL Maker (local file -> tavus-api upload/S3 URL -> RQH document record), so it requires TAVUS_PORTAL_BEARER_TOKEN. PAL Knowledge attachment uses document_ids and document_tags; RAG tuning lives under layers.knowledge_base.

MCP

{
  "mcpServers": {
    "tavus": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/tavus-mcp", "tavus-mcp"]
    }
  }
}

MCP tools return data and file manifests. They do not write files.

Cloudflare Worker

The remote MCP server lives in workers/tavus-mcp/ and uses Cloudflare's stateless createMcpHandler transport at /mcp.

cd workers/tavus-mcp
npm install
cp .dev.vars.example .dev.vars
npm run dev

The local remote-MCP endpoint is http://127.0.0.1:8787/mcp.

Hosted remote MCP

Hosted remote MCP clients should point directly at the HTTPS /mcp URL. Do not put a Tavus API key or shared bearer token in client config. The Worker exposes standard OAuth metadata, dynamic client registration, authorize, and token endpoints so MCP clients can authenticate through Tavus browser auth.

Claude Code example:

claude mcp add -s user --transport http tavus https://mcp.tavus.io/mcp

The OAuth authorize step redirects to Tavus developer portal /dev/cli-authorize?mode=oauth. After the user signs in, the portal mints a per-user Tavus API key and redirects back to the MCP client's loopback callback. The Worker exchanges that code for an MCP bearer token, then forwards the bearer to RQH as x-api-key. This keeps Tavus API keys user-scoped and out of MCP client configuration.

Developer portal must support the mode=oauth authorize flow for remote MCP auth to complete. If a local portal is running on port 3000, test the full browser-auth path against TEST with:

cd workers/tavus-mcp
npm run dev -- --env test --var TAVUS_DEV_PORTAL_URL:http://localhost:3000

claude mcp add -s user --transport http tavus-dev http://127.0.0.1:8787/mcp

Keep the Worker environment aligned with the portal environment that minted the key. For example, a TEST key from a local or dev portal must hit a Worker running with --env test, otherwise downstream Tavus API calls will return 401.

For Tavus deployment, configure these GitHub environment secrets for each deployable environment (test, stg, prod):

• CLOUDFLARE_API_TOKEN
• CLOUDFLARE_ACCOUNT_ID

Worker runtime secrets, such as the legacy TAVUS_API_KEY or MCP_BEARER_TOKEN fallback, should be set in Cloudflare with wrangler secret put <NAME> --env <environment>. They persist across deploys; the GitHub workflow does not read or overwrite them.

Merges to main automatically run the Deploy Tavus MCP Worker workflow for prod. You can also run the workflow manually for test, stg, or prod. The public MCP endpoint is always https://mcp.tavus.io/mcp. The mcp.tavus-preview.io custom domain belongs only to the stg Worker and must not be published as a production fallback.

For direct Wrangler usage, the default config targets production; use wrangler deploy --env test or wrangler dev --env test to point at TEST.

Useful production checks:

curl https://mcp.tavus.io/.well-known/oauth-protected-resource/mcp
curl https://mcp.tavus.io/.well-known/oauth-authorization-server
curl -i https://mcp.tavus.io/mcp

Unauthenticated /mcp should return 401 with a WWW-Authenticate header that points at the protected-resource metadata URL. A 404 Not Found at discovery usually means the Worker version serving the custom domain does not include the OAuth routes yet.

Codex Skill

A publishable Codex skill for this repo lives at skills/tavus-agentic-pals/. It documents the CLI and MCP workflows, safe PAL patching, environment setup, and concrete examples for agents using this toolkit.

Install it by copying that folder into ${CODEX_HOME:-$HOME/.codex}/skills/, or publish the folder directly through whatever skill distribution flow you use.