tavus-cli 0.1.0__tar.gz

tavus_cli-0.1.0/.env.example

@@ -0,0 +1,38 @@
+# Target environment. Defaults to PROD when unset.
+# Set TAVUS_ENV=TEST to use the test DB.
+# Accepted values: TEST, TEST_DB, STG, PROD.
+# TAVUS_ENV=TEST
+
+# Defaults are selected from TAVUS_ENV, but explicit URLs always win.
+# TEST defaults:
+#   TAVUS_PUBLIC_API_BASE_URL=https://test.rqh.tavusapi.com/v2
+#   TAVUS_PORTAL_API_BASE_URL=https://test-api.tavus.io/api
+#   TAVUS_DEV_PORTAL_URL=https://dev.platform.tavus.io
+# STG defaults:
+#   TAVUS_PUBLIC_API_BASE_URL=https://stg.rqh.tavusapi.com/v2
+#   TAVUS_PORTAL_API_BASE_URL=https://stg-api.tavus.io/api
+#   TAVUS_DEV_PORTAL_URL=https://stage.platform.tavus.io
+# PROD defaults:
+#   TAVUS_PUBLIC_API_BASE_URL=https://tavusapi.com/v2
+#   TAVUS_PORTAL_API_BASE_URL=https://prod-api.tavus.io/api
+#   TAVUS_DEV_PORTAL_URL=https://platform.tavus.io
+TAVUS_PUBLIC_API_BASE_URL=
+TAVUS_PORTAL_API_BASE_URL=
+TAVUS_DEV_PORTAL_URL=
+
+# Optional per-env overrides. These beat the defaults but not the generic vars above.
+TAVUS_TEST_PUBLIC_API_BASE_URL=
+TAVUS_TEST_PORTAL_API_BASE_URL=
+TAVUS_TEST_DEV_PORTAL_URL=
+TAVUS_STG_PUBLIC_API_BASE_URL=
+TAVUS_STG_PORTAL_API_BASE_URL=
+TAVUS_STG_DEV_PORTAL_URL=
+TAVUS_PROD_PUBLIC_API_BASE_URL=
+TAVUS_PROD_PORTAL_API_BASE_URL=
+TAVUS_PROD_DEV_PORTAL_URL=
+
+# Optional auth fallback. If set, it wins over keyring for the selected env.
+TAVUS_API_KEY=
+TAVUS_TEST_API_KEY=
+TAVUS_STG_API_KEY=
+TAVUS_PROD_API_KEY=

tavus_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv
+        run: pip install uv
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Ruff
+        run: uv run ruff check .
+      - name: Pytest
+        env:
+          # Rich/typer reads COLUMNS to decide help-text wrap width. CI's
+          # default of 80 wraps option names like --limit across lines,
+          # which breaks substring assertions in test_cli.py.
+          COLUMNS: '200'
+        run: uv run pytest -q
+      - name: Build
+        run: uv build

tavus_cli-0.1.0/.github/workflows/deploy-cloudflare-worker.yml

@@ -0,0 +1,68 @@
+name: Deploy Tavus MCP Worker
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Cloudflare Worker environment to deploy
+        required: true
+        default: test
+        type: choice
+        options:
+          - test
+          - stg
+          - prod
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    env:
+      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+      CLOUDFLARE_ENV: ${{ inputs.environment }}
+      TAVUS_API_KEY: ${{ secrets.TAVUS_API_KEY }}
+      MCP_BEARER_TOKEN: ${{ secrets.MCP_BEARER_TOKEN }}
+    defaults:
+      run:
+        working-directory: workers/tavus-mcp
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: workers/tavus-mcp/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type-check
+        run: npm run build
+
+      - name: Test
+        run: npm run test
+
+      - name: Configure legacy shared-token fallback secrets
+        run: |
+          if [ -n "${TAVUS_API_KEY:-}" ]; then
+            printf '%s' "$TAVUS_API_KEY" | npx wrangler secret put TAVUS_API_KEY --env "$CLOUDFLARE_ENV"
+          else
+            echo "Skipping TAVUS_API_KEY; OAuth user bearer tokens do not require the legacy fallback."
+          fi
+
+          if [ -n "${MCP_BEARER_TOKEN:-}" ]; then
+            printf '%s' "$MCP_BEARER_TOKEN" | npx wrangler secret put MCP_BEARER_TOKEN --env "$CLOUDFLARE_ENV"
+          else
+            echo "Skipping MCP_BEARER_TOKEN; OAuth user bearer tokens do not require the legacy fallback."
+          fi
+
+      - name: Deploy Worker
+        run: npx wrangler deploy --env "$CLOUDFLARE_ENV"

tavus_cli-0.1.0/.github/workflows/pr-reviews.yml

@@ -0,0 +1,29 @@
+name: PR Review Notifications
+
+on:
+  pull_request:
+    types: [opened, ready_for_review, closed]
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.user.login != 'cvi-bot[bot]'
+    steps:
+      - name: Send PR notification
+        uses: Tavus-Engineering/pr-changelog-action/review@main
+        with:
+          slack-bot-token: ${{ secrets.CVI_BOT_SLACK_TOKEN }}
+          slack-channel-id: C0AFT2E9D5Y
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repo: ${{ github.repository }}
+          pr-number: ${{ github.event.pull_request.number }}
+          pr-title: ${{ github.event.pull_request.title }}
+          pr-url: ${{ github.event.pull_request.html_url }}
+          pr-author: ${{ github.event.pull_request.user.login }}
+          pr-merged: ${{ github.event.pull_request.merged }}
+          pr-draft: ${{ github.event.pull_request.draft }}
+          event-action: ${{ github.event.action }}

tavus_cli-0.1.0/.github/workflows/pypi-cli.yml

@@ -0,0 +1,39 @@
+name: Publish Tavus CLI to PyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: pypi-cli
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install uv
+        run: pip install uv
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Ruff
+        run: uv run ruff check .
+      - name: Pytest
+        env:
+          COLUMNS: '200'
+        run: uv run pytest -q
+      - name: Build
+        run: |
+          rm -rf dist
+          uv build
+      - name: Publish
+        run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/

tavus_cli-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.env
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+node_modules/
+workers/**/.dev.vars
+workers/**/.wrangler/
+
+# Claude Code local/runtime state (keep shared config in .claude/)
+.claude/scheduled_tasks.lock
+.claude/scheduled_tasks.json
+.claude/settings.local.json

tavus_cli-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: tavus-cli
+Version: 0.1.0
+Summary: Tavus CLI and MCP server for agentic persona creation and editing.
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jsonpatch>=1.33
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.2.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tavus-cli
+
+Agent-facing surfaces that let another agent (Claude, Codex, or any MCP-aware client) drive Tavus persona creation end-to-end — separate from the human-facing Conversational Persona Builder.
+
+## What's here
+
+- **MCP server.** Persona 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 persona authoring + publish. `tavus persona 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 Conversational Persona Builder)
+
+The CPB project is the **human** builder — replica-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.
+
+## Out of scope (for now)
+
+- Replica/video preview surfaces (lives in CPB)
+- Marketplace / sharing UX
+- Multi-tenant auth beyond the existing dev-portal token model
+
+## Local Setup
+
+```bash
+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:
+
+```bash
+uv run tavus auth login
+```
+
+Examples:
+
+```bash
+# Production defaults; only the API key is required.
+TAVUS_API_KEY=... uv run tavus persona list
+
+# Test DB without URL overrides.
+TAVUS_ENV=TEST TAVUS_API_KEY=... uv run tavus persona list
+uv run tavus --env TEST persona 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:
+
+```bash
+uv tool install tavus-cli
+```
+
+Or run it without installing:
+
+```bash
+uvx --from tavus-cli tavus doctor
+```
+
+Local development commands:
+
+```bash
+uv run tavus doctor
+uv run tavus persona list
+uv run tavus persona options <persona_id>
+uv run tavus persona patch <persona_id> --op replace --path /persona_name --value '"New Name"'
+```
+
+## MCP
+
+```json
+{
+  "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`.
+
+```bash
+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:
+
+```bash
+claude mcp add -s user --transport http tavus https://mcp.tavus-preview.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:
+
+```bash
+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 Cloudflare/GitHub environment secrets:
+
+- `CLOUDFLARE_API_TOKEN`
+- `CLOUDFLARE_ACCOUNT_ID`
+- `TAVUS_API_KEY` and `MCP_BEARER_TOKEN` only if you need the legacy shared-token fallback
+
+Then run the `Deploy Tavus MCP Worker` workflow for `test`, `stg`, or `prod`.
+The `prod` Wrangler route is configured as a custom domain on `mcp.tavus.io`;
+use `https://mcp.tavus-preview.io/mcp` as the Cloudflare-owned endpoint until
+`mcp.tavus.io` DNS resolves.
+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:
+
+```bash
+curl https://mcp.tavus-preview.io/.well-known/oauth-protected-resource/mcp
+curl https://mcp.tavus-preview.io/.well-known/oauth-authorization-server
+curl -i https://mcp.tavus-preview.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-personas/`.
+It documents the CLI and MCP workflows, safe persona 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.

tavus_cli-0.1.0/README.md

@@ -0,0 +1,172 @@
+# tavus-cli
+
+Agent-facing surfaces that let another agent (Claude, Codex, or any MCP-aware client) drive Tavus persona creation end-to-end — separate from the human-facing Conversational Persona Builder.
+
+## What's here
+
+- **MCP server.** Persona 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 persona authoring + publish. `tavus persona 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 Conversational Persona Builder)
+
+The CPB project is the **human** builder — replica-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.
+
+## Out of scope (for now)
+
+- Replica/video preview surfaces (lives in CPB)
+- Marketplace / sharing UX
+- Multi-tenant auth beyond the existing dev-portal token model
+
+## Local Setup
+
+```bash
+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:
+
+```bash
+uv run tavus auth login
+```
+
+Examples:
+
+```bash
+# Production defaults; only the API key is required.
+TAVUS_API_KEY=... uv run tavus persona list
+
+# Test DB without URL overrides.
+TAVUS_ENV=TEST TAVUS_API_KEY=... uv run tavus persona list
+uv run tavus --env TEST persona 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:
+
+```bash
+uv tool install tavus-cli
+```
+
+Or run it without installing:
+
+```bash
+uvx --from tavus-cli tavus doctor
+```
+
+Local development commands:
+
+```bash
+uv run tavus doctor
+uv run tavus persona list
+uv run tavus persona options <persona_id>
+uv run tavus persona patch <persona_id> --op replace --path /persona_name --value '"New Name"'
+```
+
+## MCP
+
+```json
+{
+  "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`.
+
+```bash
+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:
+
+```bash
+claude mcp add -s user --transport http tavus https://mcp.tavus-preview.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:
+
+```bash
+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 Cloudflare/GitHub environment secrets:
+
+- `CLOUDFLARE_API_TOKEN`
+- `CLOUDFLARE_ACCOUNT_ID`
+- `TAVUS_API_KEY` and `MCP_BEARER_TOKEN` only if you need the legacy shared-token fallback
+
+Then run the `Deploy Tavus MCP Worker` workflow for `test`, `stg`, or `prod`.
+The `prod` Wrangler route is configured as a custom domain on `mcp.tavus.io`;
+use `https://mcp.tavus-preview.io/mcp` as the Cloudflare-owned endpoint until
+`mcp.tavus.io` DNS resolves.
+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:
+
+```bash
+curl https://mcp.tavus-preview.io/.well-known/oauth-protected-resource/mcp
+curl https://mcp.tavus-preview.io/.well-known/oauth-authorization-server
+curl -i https://mcp.tavus-preview.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-personas/`.
+It documents the CLI and MCP workflows, safe persona 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.