tavus-cli 0.1.0__py3-none-any.whl

tavus_mcp/cli/main.py

@@ -0,0 +1,1467 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import platform
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from tavus_mcp.sdk.auth import keyring_store
+from tavus_mcp.sdk.auth.oauth import login_with_browser
+from tavus_mcp.sdk.auth.session import get_session
+from tavus_mcp.sdk.client.http import TavusClient
+from tavus_mcp.sdk.env import load_config
+from tavus_mcp.sdk.errors import TavusError
+from tavus_mcp.sdk.patch import allowed_patch_paths, validate_patch_operations
+from tavus_mcp.sdk.recipes.build_and_verify import build_and_verify as build_and_verify_recipe
+from tavus_mcp.sdk.recipes.options import describe_persona_options
+from tavus_mcp.sdk.recipes.quickstart import quickstart as quickstart_recipe
+from tavus_mcp.sdk.recipes.scaffold_embed import scaffold_embed
+
+HELP_CONTEXT = {"help_option_names": ["-h", "--help"]}
+
+app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+auth_app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+persona_app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+replica_app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+conversation_app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+resource_app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+guardrail_app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+objective_app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+tool_app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+pronunciation_app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+persona_tools_app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+builder_app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+builder_update_app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+chat_app = typer.Typer(no_args_is_help=True, context_settings=HELP_CONTEXT)
+app.add_typer(auth_app, name="auth")
+app.add_typer(persona_app, name="persona")
+persona_app.add_typer(persona_tools_app, name="tools")
+app.add_typer(replica_app, name="replica")
+app.add_typer(conversation_app, name="conversation")
+app.add_typer(resource_app, name="resource")
+app.add_typer(guardrail_app, name="guardrail")
+app.add_typer(objective_app, name="objective")
+app.add_typer(tool_app, name="tool")
+app.add_typer(pronunciation_app, name="pronunciation-dictionary")
+app.add_typer(builder_app, name="builder")
+builder_app.add_typer(builder_update_app, name="update")
+app.add_typer(chat_app, name="chat")
+console = Console()
+
+
+@app.callback()
+def main(
+    env: str | None = typer.Option(
+        None,
+        "--env",
+        "-e",
+        help="Target Tavus environment. Defaults to PROD; use TEST for the test DB.",
+    ),
+) -> None:
+    """Tavus CLI."""
+    if env:
+        os.environ["TAVUS_ENV"] = env
+
+
+def _run(coro: Any) -> Any:
+    try:
+        return asyncio.run(coro)
+    except TavusError as error:
+        console.print(f"[red]{error}[/red]")
+        raise typer.Exit(1) from error
+
+
+def _json(data: Any) -> None:
+    console.print_json(json.dumps(data, default=str))
+
+
+def _parse_value(value: str) -> Any:
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError:
+        return value
+
+
+@app.command()
+def doctor(
+    skip_network: bool = typer.Option(False, help="Only validate local configuration."),
+) -> None:
+    """Show selected environment, auth source, and API reachability."""
+    config = load_config()
+    session = get_session(config, required=False)
+    table = Table(title="Tavus MCP Doctor")
+    table.add_column("Key")
+    table.add_column("Value")
+    table.add_row("env", config.env.value)
+    table.add_row("env_file", str(config.env_file) if config.env_file else "(none)")
+    table.add_row("public_api_base_url", str(config.public_api_base_url))
+    table.add_row("portal_api_base_url", str(config.portal_api_base_url))
+    table.add_row("dev_portal_url", str(config.dev_portal_url))
+    table.add_row("auth_source", session.source if session else "(missing)")
+    console.print(table)
+
+    if skip_network:
+        return
+    if not session:
+        raise typer.Exit(1)
+
+    async def check() -> None:
+        async with TavusClient(config, session) as client:
+            await client.personas.list(limit=1)
+            await client.replicas.list(limit=1)
+
+    _run(check())
+    console.print("[green]Network check passed.[/green]")
+
+
+@auth_app.command("login")
+def auth_login(
+    api_key: str | None = typer.Option(
+        None,
+        help="Store an existing Tavus API key instead of opening Firebase login.",
+    ),
+    name: str | None = typer.Option(None, help="Name for the minted API key."),
+) -> None:
+    """Log in with Firebase and store an env-scoped Tavus API key."""
+    config = load_config()
+    if api_key:
+        keyring_store.set_api_key(config, api_key)
+        console.print(f"Stored API key for {config.env.value}.")
+        return
+
+    key_name = name or f"tavus-cli ({platform.node() or 'unknown-host'} {config.env.value})"
+    result = _run(login_with_browser(config, key_name=key_name))
+    console.print(f"Logged in as {result.email or 'Tavus user'} for {config.env.value}.")
+
+
+@auth_app.command("logout")
+def auth_logout() -> None:
+    """Delete the env-scoped API key from local keyring."""
+    config = load_config()
+    keyring_store.delete_api_key(config)
+    console.print(f"Deleted keyring API key for {config.env.value}.")
+
+
+@auth_app.command("status")
+def auth_status() -> None:
+    """Show whether credentials are available for the selected env."""
+    config = load_config()
+    session = get_session(config, required=False)
+    _json(
+        {
+            "env": config.env.value,
+            "authenticated": session is not None,
+            "source": session.source if session else None,
+        }
+    )
+
+
+@persona_app.command("list")
+def persona_list(
+    limit: int = typer.Option(25),
+    page: int = typer.Option(0),
+    persona_type: str | None = typer.Option(None),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """List personas for the selected env/account."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.personas.list(limit=limit, page=page, persona_type=persona_type)
+
+    data = _run(run())
+    if json_output:
+        _json(data)
+        return
+    _print_rows(data, ["persona_id", "persona_name", "default_replica_id", "updated_at"])
+
+
+@persona_app.command("get")
+def persona_get(persona_id: str, include_settings: bool = typer.Option(False)) -> None:
+    """Get a persona as JSON."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.personas.get(
+                persona_id,
+                include_settings=str(include_settings).lower(),
+            )
+
+    _json(_run(run()))
+
+
+@persona_app.command("create")
+def persona_create(
+    system_prompt: str | None = typer.Option(None, "--system-prompt"),
+    name: str = typer.Option("Agentic Tavus Persona", "--name"),
+    replica_id: str | None = typer.Option(None),
+    pipeline_mode: str = typer.Option(
+        "full", "--pipeline-mode", help="full | speech-to-speech | echo"
+    ),
+    greeting: str | None = typer.Option(None, "--greeting"),
+    context: str | None = typer.Option(None, "--context"),
+    layers_file: Path | None = typer.Option(
+        None, "--layers-file", help="JSON file with layer overrides."
+    ),
+    memories: list[str] | None = typer.Option(
+        None, "--memory", help="Initial seed memory. Repeat for multiple."
+    ),
+    objectives_id: str | None = typer.Option(None, "--objectives-id"),
+    guardrails_id: str | None = typer.Option(
+        None, "--guardrails-id", help="Legacy guardrail-set id."
+    ),
+    guardrail_ids: list[str] | None = typer.Option(
+        None, "--guardrail-id", help="Repeat for multiple. New flat shape."
+    ),
+    guardrail_tags: list[str] | None = typer.Option(
+        None, "--guardrail-tag", help="Repeat for multiple. New flat shape."
+    ),
+    document_ids: list[str] | None = typer.Option(
+        None, "--document-id", help="Repeat for multiple."
+    ),
+    document_tags: list[str] | None = typer.Option(
+        None, "--document-tag", help="Repeat for multiple."
+    ),
+    is_template: bool = typer.Option(
+        False, "--template/--no-template", help="Flag as a clonable template."
+    ),
+) -> None:
+    """Create a persona. ``--system-prompt`` is required for the default
+    ``--pipeline-mode=full``; omit it for ``speech-to-speech`` or ``echo``.
+    Attach tools post-create with ``tavus persona tools attach``."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            body: dict[str, Any] = {"persona_name": name}
+            if pipeline_mode and pipeline_mode != "full":
+                body["pipeline_mode"] = pipeline_mode
+            if system_prompt is not None:
+                body["system_prompt"] = system_prompt
+            if replica_id:
+                body["default_replica_id"] = replica_id
+            if greeting is not None:
+                body["greeting"] = greeting
+            if context is not None:
+                body["context"] = context
+            if layers_file:
+                body["layers"] = json.loads(layers_file.read_text())
+            if memories:
+                body["memories"] = list(memories)
+            if objectives_id:
+                body["objectives_id"] = objectives_id
+            if guardrails_id:
+                body["guardrails_id"] = guardrails_id
+            if guardrail_ids:
+                body["guardrail_ids"] = list(guardrail_ids)
+            if guardrail_tags:
+                body["guardrail_tags"] = list(guardrail_tags)
+            if document_ids:
+                body["document_ids"] = list(document_ids)
+            if document_tags:
+                body["document_tags"] = list(document_tags)
+            if is_template:
+                body["is_template"] = True
+            return await client.personas.create(body)
+
+    _json(_run(run()))
+
+
+@persona_app.command("delete")
+def persona_delete(persona_id: str) -> None:
+    """Delete a persona."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.personas.delete(persona_id)
+
+    _json(_run(run()))
+
+
+@persona_app.command("patch")
+def persona_patch(
+    persona_id: str,
+    op: str = typer.Option("replace", help="JSON Patch op."),
+    path: str = typer.Option(..., help="JSON Pointer path, e.g. /persona_name."),
+    value: str | None = typer.Option(None, help="JSON value; strings may be passed as plain text."),
+    patch_file: Path | None = typer.Option(None, help="JSON patch file. Overrides op/path/value."),
+    dry_run: bool = typer.Option(False, help="Validate but do not send."),
+) -> None:
+    """Apply a validated JSON Patch to a persona."""
+    if patch_file:
+        ops = json.loads(patch_file.read_text())
+    else:
+        item: dict[str, Any] = {"op": op, "path": path}
+        if value is not None:
+            item["value"] = _parse_value(value)
+        ops = [item]
+    validated = validate_patch_operations(ops)
+    if dry_run:
+        _json({"valid": True, "ops": validated})
+        return
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.personas.patch(persona_id, validated)
+
+    _json(_run(run()))
+
+
+@persona_app.command("options")
+def persona_options(persona_id: str) -> None:
+    """Return the persona plus valid account resources and patchable paths."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await describe_persona_options(client, persona_id)
+
+    _json(_run(run()))
+
+
+@persona_app.command("paths")
+def persona_paths() -> None:
+    """List locally known JSON Patch paths for personas."""
+    _json(sorted(allowed_patch_paths()))
+
+
+@persona_app.command("build")
+def persona_build(
+    prompt: str | None = typer.Option(
+        None,
+        "--prompt",
+        help="Initial creator prompt, e.g. 'I want to make a persona for an office greeter...'.",
+    ),
+    goal: str | None = typer.Option(None, "--goal", hidden=True),
+    replica_id: str | None = typer.Option(
+        None,
+        "--replica-id",
+        help="Override the default replica selected by the builder backend.",
+    ),
+    max_rounds: int = typer.Option(
+        4,
+        "--max-rounds",
+        min=1,
+        help="Maximum builder question/answer rounds before publishing.",
+    ),
+    json_output: bool = typer.Option(False, "--json"),
+    answer: list[str] | None = typer.Option(None, "--answer", hidden=True),
+    model: str = typer.Option("claude-sonnet-4-6", "--model", hidden=True),
+    inner_model: str | None = typer.Option(None, "--inner-model", hidden=True),
+) -> None:
+    """Build a persona through the same conversational builder flow used by
+    creator-studio, then verify the published persona through CVI chat mode."""
+
+    creator_prompt = (prompt or goal or "").strip()
+    if not creator_prompt:
+        raise typer.BadParameter("Provide --prompt.", param_hint="--prompt")
+
+    io_console = Console(stderr=json_output)
+
+    def print_builder_reply(
+        reply: dict[str, Any], round_number: int, _transcript: list[dict[str, Any]]
+    ) -> None:
+        text = str(reply.get("text") or "").strip()
+        if text:
+            io_console.print(f"\n[bold]Builder[/bold] [{round_number}/{max_rounds}]: {text}")
+        suggestions = [str(item) for item in (reply.get("suggestions") or []) if item]
+        if suggestions:
+            io_console.print("[dim]Suggestions:[/dim] " + " | ".join(suggestions))
+
+    def ask_creator(
+        _reply: dict[str, Any], _round_number: int, _transcript: list[dict[str, Any]]
+    ) -> str | None:
+        try:
+            value = io_console.input("[bold]You[/bold] (blank to finish): ")
+        except (EOFError, KeyboardInterrupt):
+            return None
+        return value.strip() or None
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await build_and_verify_recipe(
+                client,
+                prompt=creator_prompt,
+                replica_id=replica_id,
+                model=model,
+                inner_model=inner_model,
+                max_rounds=max_rounds,
+                answers=list(answer) if answer else None,
+                answer_provider=None if answer else ask_creator,
+                on_builder_reply=print_builder_reply,
+                auto_refine=True,
+                max_refine_rounds=1,
+            )
+
+    data = _run(run())
+    if json_output:
+        _json(data)
+        return
+    verdict = data.get("verdict") or {}
+    console.print(f"[bold]builder_id[/bold]: {data.get('builder_id')}")
+    console.print(f"[bold]persona_id[/bold]: {data.get('persona_id')}")
+    if data.get("replica_id"):
+        console.print(f"[bold]replica_id[/bold]: {data.get('replica_id')}")
+    if data.get("persona_url"):
+        console.print(f"[bold]persona_url[/bold]: {data.get('persona_url')}")
+    console.print(f"[bold]overall[/bold]: {verdict.get('overall', '?')}")
+    if data.get("refine_rounds_used"):
+        console.print(f"[dim]refine_rounds_used={data['refine_rounds_used']}[/dim]")
+    summary = verdict.get("summary")
+    if summary:
+        console.print(f"\n{summary}")
+    if data.get("system_prompt"):
+        console.print("\n[bold]system_prompt[/bold]:")
+        console.print(data["system_prompt"])
+
+
+@persona_app.command("preview")
+def persona_preview(
+    persona_id: str,
+    replica_id: str | None = typer.Option(None),
+    name: str | None = typer.Option(None, "--name"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Start a full preview conversation against a persona and print the
+    conversation_url so a human can verify visually."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            body: dict[str, Any] = {"persona_id": persona_id}
+            if replica_id:
+                body["replica_id"] = replica_id
+            else:
+                persona = await client.personas.get(persona_id)
+                default_replica = (
+                    persona.get("default_replica_id") if isinstance(persona, dict) else None
+                )
+                if default_replica:
+                    body["replica_id"] = default_replica
+            if name:
+                body["conversation_name"] = name
+            return await client.conversations.create(body)
+
+    data = _run(run())
+    if json_output:
+        _json(data)
+        return
+    url = data.get("conversation_url") if isinstance(data, dict) else None
+    if url:
+        console.print(url)
+    else:
+        _json(data)
+
+
+@replica_app.command("list")
+def replica_list(
+    limit: int = typer.Option(25),
+    stock: bool = typer.Option(False, "--stock"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """List replicas."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.replicas.list(limit=limit, replica_type="system" if stock else None)
+
+    data = _run(run())
+    if json_output:
+        _json(data)
+        return
+    _print_rows(data, ["replica_id", "replica_name", "status", "model_name"])
+
+
+@conversation_app.command("create")
+def conversation_create(
+    persona_id: str | None = typer.Option(None),
+    replica_id: str | None = typer.Option(None),
+    name: str | None = typer.Option(None),
+) -> None:
+    """Create a conversation."""
+
+    async def run() -> Any:
+        body = {"persona_id": persona_id, "replica_id": replica_id, "conversation_name": name}
+        async with TavusClient.from_env() as client:
+            return await client.conversations.create({k: v for k, v in body.items() if v})
+
+    _json(_run(run()))
+
+
+@conversation_app.command("end")
+def conversation_end(conversation_id: str) -> None:
+    """End a conversation."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.conversations.end(conversation_id)
+
+    _json(_run(run()))
+
+
+@builder_app.command("create")
+def builder_create(
+    name: str = typer.Option(..., "--name"),
+    greeting: str | None = typer.Option(None),
+    persona_id: str | None = typer.Option(None),
+    model: str | None = typer.Option(None, help="claude or gpt-oss-120b"),
+) -> None:
+    """Start a builder session. The CLI mirrors the dev-portal creator-studio
+    flow — give the session a name and optionally seed a greeting or attach
+    an existing persona."""
+
+    async def run() -> Any:
+        body: dict[str, Any] = {"name": name}
+        if greeting is not None:
+            body["greeting"] = greeting
+        if persona_id:
+            body["persona_id"] = persona_id
+        if model:
+            body["model"] = model
+        async with TavusClient.from_env() as client:
+            return await client.builders.create(body)
+
+    _json(_run(run()))
+
+
+@builder_app.command("list")
+def builder_list(
+    limit: int | None = typer.Option(None),
+    page: int | None = typer.Option(None),
+    persona_id: str | None = typer.Option(None),
+    name: str | None = typer.Option(None),
+    status: str | None = typer.Option(None),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """List builder sessions for the authenticated account."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.builders.list(
+                limit=limit, page=page, persona_id=persona_id, name=name, status=status
+            )
+
+    data = _run(run())
+    if json_output:
+        _json(data)
+        return
+    sessions = data.get("sessions", data) if isinstance(data, dict) else data
+    if not isinstance(sessions, list):
+        _json(data)
+        return
+    columns = ("uuid", "name", "persona_id", "status", "updated_at")
+    table = Table()
+    for column in columns:
+        table.add_column(column)
+    for row in sessions:
+        table.add_row(*[str(row.get(column, "")) for column in columns])
+    console.print(table)
+
+
+@builder_app.command("get")
+def builder_get(builder_id: str) -> None:
+    """Fetch a single builder session."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.builders.get(builder_id)
+
+    _json(_run(run()))
+
+
+@builder_app.command("delete")
+def builder_delete(builder_id: str) -> None:
+    """Soft-delete a builder session."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.builders.delete(builder_id)
+
+    _json(_run(run()))
+
+
+@builder_app.command("chat")
+def builder_chat(
+    builder_id: str,
+    message: str = typer.Option(..., "--message"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Send a chat turn to the builder. Prints the assistant text, any
+    suggestion chips, then a footer with ``draft_ready`` and the targets the
+    builder LLM signaled (use ``tavus builder update <target> ...`` next)."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.builders.chat(builder_id, message)
+
+    data = _run(run())
+    if json_output:
+        _json(data)
+        return
+    text = data.get("text") or ""
+    suggestions = data.get("suggestions") or []
+    targets = data.get("targets") or []
+    draft_ready = data.get("draft_ready", False)
+    if text:
+        console.print(text)
+    if suggestions:
+        console.print("\n[bold]Suggestions[/bold]")
+        for i, suggestion in enumerate(suggestions, 1):
+            console.print(f"  {i}. {suggestion}")
+    console.print(f"\n[dim]draft_ready={draft_ready}  targets={targets or '[]'}[/dim]")
+
+
+@builder_app.command("history")
+def builder_history(
+    builder_id: str,
+    limit: int = typer.Option(50),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Print the chat transcript for a builder session."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.builders.chat_history(builder_id, limit=limit)
+
+    data = _run(run())
+    if json_output:
+        _json(data)
+        return
+    messages = data.get("messages", data) if isinstance(data, dict) else data
+    if not isinstance(messages, list):
+        _json(data)
+        return
+    for entry in messages:
+        role = entry.get("role", "?")
+        content = entry.get("content", "")
+        console.print(f"[bold]{role}[/bold]: {content}")
+
+
+@builder_app.command("append-messages")
+def builder_append_messages(
+    builder_id: str,
+    file: Path = typer.Option(..., "--file", help="JSON file with a messages array."),
+) -> None:
+    """Append raw {role, content} messages to a session without invoking the LLM."""
+    messages = json.loads(file.read_text())
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.builders.append_messages(builder_id, messages)
+
+    _json(_run(run()))
+
+
+@builder_app.command("publish")
+def builder_publish(builder_id: str) -> None:
+    """Mark a builder session complete and publish its persona."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.builders.publish(builder_id)
+
+    _json(_run(run()))
+
+
+@builder_update_app.command("objectives")
+def builder_update_objectives(
+    builder_id: str,
+    message: str = typer.Option(..., "--message"),
+) -> None:
+    """Run an LLM update on the persona's objectives list."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.builders.update_objectives(builder_id, message)
+
+    _json(_run(run()))
+
+
+@builder_update_app.command("guardrails")
+def builder_update_guardrails(
+    builder_id: str,
+    message: str = typer.Option(..., "--message"),
+) -> None:
+    """Run an LLM update on the persona's guardrails list."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.builders.update_guardrails(builder_id, message)
+
+    _json(_run(run()))
+
+
+@builder_update_app.command("greeting")
+def builder_update_greeting(
+    builder_id: str,
+    message: str = typer.Option(..., "--message"),
+) -> None:
+    """Run an LLM refinement of the persona's greeting."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.builders.update_greeting(builder_id, message)
+
+    _json(_run(run()))
+
+
+@builder_update_app.command("personality")
+def builder_update_personality(
+    builder_id: str,
+    message: str = typer.Option(..., "--message"),
+    persona_name: bool = typer.Option(False, "--name", help="Also update persona_name."),
+    system_prompt: bool = typer.Option(False, "--system-prompt", help="Also update system_prompt."),
+) -> None:
+    """Run an LLM refinement of persona name and/or system prompt."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.builders.update_personality(
+                builder_id,
+                message,
+                persona_name=persona_name,
+                system_prompt=system_prompt,
+            )
+
+    _json(_run(run()))
+
+
+@chat_app.command("start")
+def chat_start(
+    persona_id: str = typer.Option(..., "--persona-id"),
+    greeting: str | None = typer.Option(None),
+    name: str | None = typer.Option(None, "--name"),
+) -> None:
+    """Start a text-only conversation against a persona."""
+
+    async def run() -> Any:
+        body: dict[str, Any] = {"persona_id": persona_id, "chat": True}
+        if greeting:
+            body["custom_greeting"] = greeting
+        if name:
+            body["conversation_name"] = name
+        async with TavusClient.from_env() as client:
+            return await client.conversations.create(body)
+
+    _json(_run(run()))
+
+
+@chat_app.command("turn")
+def chat_turn(
+    conversation_id: str,
+    message: str = typer.Option(..., "--message"),
+    timeout: float = typer.Option(20.0, "--timeout"),
+) -> None:
+    """Send one user turn and print the persona's reply."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.conversations.chat_turn(
+                conversation_id, message, timeout_s=timeout
+            )
+
+    console.print(_run(run()))
+
+
+@chat_app.command("end")
+def chat_end(conversation_id: str) -> None:
+    """End a chat-mode conversation."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.conversations.end(conversation_id)
+
+    _json(_run(run()))
+
+
+@app.command()
+def quickstart(
+    system_prompt: str = typer.Option(...),
+    name: str = typer.Option("Agentic Tavus Persona", "--name"),
+    replica_id: str | None = typer.Option(None),
+) -> None:
+    """Create a persona and conversation using a stock replica by default."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await quickstart_recipe(
+                client,
+                system_prompt=system_prompt,
+                persona_name=name,
+                replica_id=replica_id,
+            )
+
+    _json(_run(run()))
+
+
+@app.command()
+def embed(
+    conversation_url: str = typer.Option(...),
+    target: str = typer.Option("iframe"),
+    write: bool = typer.Option(False, help="Write files. Default prints manifest only."),
+) -> None:
+    """Create an embed file manifest, optionally writing it locally."""
+    manifest = scaffold_embed(conversation_url=conversation_url, target=target)  # type: ignore[arg-type]
+    if not write:
+        _json(manifest.model_dump())
+        return
+    for entry in manifest.files:
+        path = Path(entry.path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(entry.content)
+        console.print(f"Wrote {path}")
+
+
+@resource_app.command("list")
+def resource_list(resource: str, limit: int = typer.Option(25)) -> None:
+    """List a supported resource: guardrails, objectives, documents, voices, tools."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            selected = _resource(client, resource)
+            return await selected.list(limit=limit)
+
+    _json(_run(run()))
+
+
+@resource_app.command("get")
+def resource_get(resource: str, resource_id: str) -> None:
+    """Get a supported resource."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            selected = _resource(client, resource)
+            return await selected.get(resource_id)
+
+    _json(_run(run()))
+
+
+@guardrail_app.command("list")
+def guardrail_list(
+    limit: int = typer.Option(25),
+    page: int = typer.Option(1),
+    type: str = typer.Option("user", help="user | system | all"),
+    name_or_uuid: str | None = typer.Option(None),
+    tags: str | None = typer.Option(None, help="Comma-separated tag filter."),
+    legacy: bool = typer.Option(False, help="Return the legacy set-shape list."),
+    verbose: bool = typer.Option(False, help="Include persona_refs + guardrail_type."),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """List guardrails. Defaults to the new flat (per-rule) shape."""
+
+    async def run() -> Any:
+        params: dict[str, Any] = {
+            "limit": limit,
+            "page": page,
+            "type": type,
+            "legacy": "true" if legacy else "false",
+        }
+        if name_or_uuid:
+            params["name_or_uuid"] = name_or_uuid
+        if tags:
+            params["tags"] = tags
+        if verbose:
+            params["verbose"] = "true"
+        async with TavusClient.from_env() as client:
+            return await client.guardrails.list(**params)
+
+    data = _run(run())
+    if json_output:
+        _json(data)
+        return
+    _print_rows(
+        data, ["uuid", "guardrail_name", "modality", "tags", "updated_at"]
+    )
+
+
+@guardrail_app.command("get")
+def guardrail_get(
+    guardrail_id: str,
+    verbose: bool = typer.Option(False),
+    legacy: bool | None = typer.Option(None),
+) -> None:
+    async def run() -> Any:
+        params: dict[str, Any] = {}
+        if verbose:
+            params["verbose"] = "true"
+        if legacy is not None:
+            params["legacy"] = "true" if legacy else "false"
+        async with TavusClient.from_env() as client:
+            return await client.guardrails.get(guardrail_id, **params)
+
+    _json(_run(run()))
+
+
+@guardrail_app.command("create")
+def guardrail_create(
+    name: str = typer.Option(..., "--name", help="guardrail_name"),
+    prompt: str = typer.Option(..., "--prompt", help="guardrail_prompt"),
+    modality: str = typer.Option("verbal", help="verbal | visual | audio"),
+    callback_url: str = typer.Option(""),
+    tool_call: str | None = typer.Option(None, help="JSON object."),
+    app_message: bool = typer.Option(True, "--app-message/--no-app-message"),
+    tags: list[str] | None = typer.Option(None, "--tag", help="Repeat for multiple."),
+) -> None:
+    """Create a flat (non-set) guardrail."""
+
+    async def run() -> Any:
+        body: dict[str, Any] = {
+            "guardrail_name": name,
+            "guardrail_prompt": prompt,
+            "modality": modality,
+            "callback_url": callback_url,
+            "app_message": app_message,
+            "tags": list(tags) if tags else [],
+        }
+        if tool_call:
+            body["tool_call"] = json.loads(tool_call)
+        async with TavusClient.from_env() as client:
+            return await client.guardrails.create(body)
+
+    _json(_run(run()))
+
+
+@guardrail_app.command("patch")
+def guardrail_patch(
+    guardrail_id: str,
+    file: Path | None = typer.Option(
+        None, "--file", help="JSON file with fields to update."
+    ),
+    name: str | None = typer.Option(None, "--name"),
+    prompt: str | None = typer.Option(None, "--prompt"),
+    modality: str | None = typer.Option(None),
+    callback_url: str | None = typer.Option(None),
+    tool_call: str | None = typer.Option(None, help="JSON object."),
+    app_message: bool | None = typer.Option(None, "--app-message/--no-app-message"),
+    tags: list[str] | None = typer.Option(None, "--tag"),
+) -> None:
+    """Patch a guardrail. RQH replaces each supplied field whole."""
+
+    async def run() -> Any:
+        if file:
+            body = json.loads(file.read_text())
+        else:
+            body = {}
+            if name is not None:
+                body["guardrail_name"] = name
+            if prompt is not None:
+                body["guardrail_prompt"] = prompt
+            if modality is not None:
+                body["modality"] = modality
+            if callback_url is not None:
+                body["callback_url"] = callback_url
+            if tool_call is not None:
+                body["tool_call"] = json.loads(tool_call)
+            if app_message is not None:
+                body["app_message"] = app_message
+            if tags is not None:
+                body["tags"] = list(tags)
+        async with TavusClient.from_env() as client:
+            return await client.guardrails.patch(guardrail_id, body)
+
+    _json(_run(run()))
+
+
+@guardrail_app.command("delete")
+def guardrail_delete(guardrail_id: str) -> None:
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.guardrails.delete(guardrail_id)
+
+    _json(_run(run()))
+
+
+@guardrail_app.command("tags")
+def guardrail_tags(
+    search: str | None = typer.Option(None),
+    page: int | None = typer.Option(None),
+    limit: int | None = typer.Option(None),
+) -> None:
+    """List tags applied to the account's guardrails."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.guardrails.tags(
+                search=search, page=page, limit=limit
+            )
+
+    _json(_run(run()))
+
+
+@objective_app.command("list")
+def objective_list(
+    limit: int = typer.Option(25),
+    page: int = typer.Option(1),
+    type: str = typer.Option("user", help="user | system | all"),
+    name_or_uuid: str | None = typer.Option(None),
+    sort: str = typer.Option("ascending"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """List objective sets."""
+
+    async def run() -> Any:
+        params: dict[str, Any] = {
+            "limit": limit,
+            "page": page,
+            "type": type,
+            "sort": sort,
+        }
+        if name_or_uuid:
+            params["name_or_uuid"] = name_or_uuid
+        async with TavusClient.from_env() as client:
+            return await client.objectives.list(**params)
+
+    data = _run(run())
+    if json_output:
+        _json(data)
+        return
+    _print_rows(
+        data, ["objectives_id", "objectives_name", "updated_at"]
+    )
+
+
+@objective_app.command("get")
+def objective_get(objectives_id: str) -> None:
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.objectives.get(objectives_id)
+
+    _json(_run(run()))
+
+
+@objective_app.command("create")
+def objective_create(
+    file: Path = typer.Option(
+        ...,
+        "--file",
+        help="JSON file with {name, data, allow_loops}.",
+    ),
+) -> None:
+    """Create an objective set from a JSON file."""
+
+    async def run() -> Any:
+        body = json.loads(file.read_text())
+        async with TavusClient.from_env() as client:
+            return await client.objectives.create(body)
+
+    _json(_run(run()))
+
+
+@objective_app.command("patch")
+def objective_patch(
+    objectives_id: str,
+    file: Path = typer.Option(
+        ..., "--file", help="JSON file with a JSON Patch ops array."
+    ),
+) -> None:
+    """Patch an objective set with JSON Patch ops."""
+
+    async def run() -> Any:
+        ops = json.loads(file.read_text())
+        async with TavusClient.from_env() as client:
+            return await client.objectives.patch(objectives_id, ops)
+
+    _json(_run(run()))
+
+
+@objective_app.command("delete")
+def objective_delete(objectives_id: str) -> None:
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.objectives.delete(objectives_id)
+
+    _json(_run(run()))
+
+
+@objective_app.command("validate")
+def objective_validate(
+    file: Path = typer.Option(
+        ..., "--file", help="JSON file with {name, data, allow_loops}."
+    ),
+) -> None:
+    """Validate an objective-set payload without persisting."""
+
+    async def run() -> Any:
+        body = json.loads(file.read_text())
+        async with TavusClient.from_env() as client:
+            return await client.objectives.validate(body)
+
+    _json(_run(run()))
+
+
+@objective_app.command("example")
+def objective_example() -> None:
+    """Print a starter JSON body for ``tavus objective create --file``."""
+    _json(
+        {
+            "name": "support_intake",
+            "allow_loops": False,
+            "data": [
+                {
+                    "objective_name": "greet",
+                    "objective_prompt": "Greet the caller and ask for their name.",
+                    "output_variables": ["caller_name"],
+                    "next_required_objective": "diagnose",
+                },
+                {
+                    "objective_name": "diagnose",
+                    "objective_prompt": "Ask what problem they're calling about.",
+                    "next_conditional_objectives": {
+                        "billing": "the caller mentions billing, charges, refund",
+                        "technical": "the caller mentions an error, outage, broken feature",
+                    },
+                },
+                {
+                    "objective_name": "billing",
+                    "objective_prompt": "Hand off to billing support.",
+                },
+                {
+                    "objective_name": "technical",
+                    "objective_prompt": "Collect error details and offer a callback.",
+                },
+            ],
+        }
+    )
+
+
+@tool_app.command("list")
+def tool_list(
+    limit: int = typer.Option(25),
+    page: int = typer.Option(1),
+    type: str = typer.Option("user", help="user | system | all"),
+    name_or_uuid: str | None = typer.Option(None),
+    sort: str = typer.Option("ascending"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """List tools."""
+
+    async def run() -> Any:
+        params: dict[str, Any] = {
+            "limit": limit,
+            "page": page,
+            "type": type,
+            "sort": sort,
+        }
+        if name_or_uuid:
+            params["name_or_uuid"] = name_or_uuid
+        async with TavusClient.from_env() as client:
+            return await client.tools.list(**params)
+
+    data = _run(run())
+    if json_output:
+        _json(data)
+        return
+    _print_rows(data, ["tool_id", "name", "origin", "on_call", "updated_at"])
+
+
+@tool_app.command("get")
+def tool_get(tool_id: str) -> None:
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.tools.get(tool_id)
+
+    _json(_run(run()))
+
+
+@tool_app.command("create")
+def tool_create(
+    file: Path = typer.Option(
+        ...,
+        "--file",
+        help="JSON file with the full tool body (name/description/parameters/delivery/...).",
+    ),
+) -> None:
+    """Create a tool from a JSON file. The file mirrors the `POST /v2/tools`
+    body shape — see ``ToolCreate`` in the SDK for fields, or
+    ``tavus tool example`` for a starter."""
+
+    async def run() -> Any:
+        body = json.loads(file.read_text())
+        async with TavusClient.from_env() as client:
+            return await client.tools.create(body)
+
+    _json(_run(run()))
+
+
+@tool_app.command("patch")
+def tool_patch(
+    tool_id: str,
+    file: Path = typer.Option(
+        ..., "--file", help="JSON file with fields to update."
+    ),
+) -> None:
+    """Patch a tool from a JSON file. RQH rejects PATCHes that echo back
+    the scrubbed-secret placeholder (``********``) from a prior GET — omit
+    secret fields you don't intend to change."""
+
+    async def run() -> Any:
+        body = json.loads(file.read_text())
+        async with TavusClient.from_env() as client:
+            return await client.tools.patch(tool_id, body)
+
+    _json(_run(run()))
+
+
+@tool_app.command("delete")
+def tool_delete(tool_id: str) -> None:
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.tools.delete(tool_id)
+
+    _json(_run(run()))
+
+
+@tool_app.command("example")
+def tool_example(
+    delivery: str = typer.Option(
+        "app_message", help="app_message | http | http_oauth2"
+    ),
+) -> None:
+    """Print a starter JSON body for ``tavus tool create --file``. Edit the
+    output and save to a file, then pass it to ``create``."""
+    examples = {
+        "app_message": {
+            "name": "weather_lookup",
+            "description": "Get the current weather for a city.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "city": {"type": "string", "description": "City name."}
+                },
+                "required": ["city"],
+            },
+            "delivery": {"app_message": True},
+            "origin": "llm",
+            "on_call": "generate_filler",
+            "on_resolve": "generate_response",
+        },
+        "http": {
+            "name": "weather_lookup",
+            "description": "Look up current weather via a third-party HTTPS endpoint.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "city": {"type": "string", "description": "City name."}
+                },
+                "required": ["city"],
+            },
+            "delivery": {
+                "api": {
+                    "url": "https://api.example.com/weather/{city}",
+                    "method": "GET",
+                    "timeout": 10,
+                    "headers": {"Accept": "application/json"},
+                    "auth": {"type": "bearer", "token": "sk-..."},
+                }
+            },
+            "origin": "llm",
+            "on_call": "generate_filler",
+            "on_resolve": "generate_response",
+        },
+        "http_oauth2": {
+            "name": "salesforce_lead_create",
+            "description": "Create a Salesforce lead via OAuth2 client credentials.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "email": {"type": "string"},
+                    "name": {"type": "string"},
+                },
+                "required": ["email", "name"],
+            },
+            "delivery": {
+                "api": {
+                    "url": "https://acme.my.salesforce.com/services/data/v59.0/sobjects/Lead",
+                    "method": "POST",
+                    "body_template": {"Email": "{email}", "LastName": "{name}"},
+                    "auth": {
+                        "type": "oauth2_client_credentials",
+                        "token_url": "https://acme.my.salesforce.com/services/oauth2/token",
+                        "client_id": "...",
+                        "client_secret": "...",
+                    },
+                }
+            },
+            "origin": "llm",
+            "on_call": "generate_filler",
+            "on_resolve": "fire_and_forget",
+        },
+    }
+    if delivery not in examples:
+        raise typer.BadParameter(
+            f"delivery must be one of {sorted(examples)}", param_hint="--delivery"
+        )
+    _json(examples[delivery])
+
+
+@pronunciation_app.command("list")
+def pronunciation_list(
+    limit: int = typer.Option(25),
+    page: int = typer.Option(0),
+    sort: str = typer.Option("desc"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """List pronunciation dictionaries — referenced from
+    ``layers.tts.pronunciation_dictionary_id``."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.pronunciation_dictionaries.list(
+                limit=limit, page=page, sort=sort
+            )
+
+    data = _run(run())
+    if json_output:
+        _json(data)
+        return
+    _print_rows(data, ["uuid", "name", "updated_at"])
+
+
+@pronunciation_app.command("get")
+def pronunciation_get(dictionary_id: str) -> None:
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.pronunciation_dictionaries.get(dictionary_id)
+
+    _json(_run(run()))
+
+
+@pronunciation_app.command("create")
+def pronunciation_create(
+    file: Path = typer.Option(
+        ..., "--file", help="JSON file with {name, rules}."
+    ),
+) -> None:
+    """Create a pronunciation dictionary from a JSON file. Rules are
+    ``{text, pronunciation, type, alphabet?, case_sensitive?, word_boundaries?}``."""
+
+    async def run() -> Any:
+        body = json.loads(file.read_text())
+        async with TavusClient.from_env() as client:
+            return await client.pronunciation_dictionaries.create(body)
+
+    _json(_run(run()))
+
+
+@pronunciation_app.command("patch")
+def pronunciation_patch(
+    dictionary_id: str,
+    file: Path = typer.Option(
+        ..., "--file", help="JSON file with fields to update."
+    ),
+) -> None:
+    """Patch a pronunciation dictionary. Supplying ``rules`` replaces the
+    full list (RQH does not merge rule arrays)."""
+
+    async def run() -> Any:
+        body = json.loads(file.read_text())
+        async with TavusClient.from_env() as client:
+            return await client.pronunciation_dictionaries.patch(
+                dictionary_id, body
+            )
+
+    _json(_run(run()))
+
+
+@pronunciation_app.command("delete")
+def pronunciation_delete(dictionary_id: str) -> None:
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.pronunciation_dictionaries.delete(dictionary_id)
+
+    _json(_run(run()))
+
+
+@pronunciation_app.command("example")
+def pronunciation_example() -> None:
+    """Print a starter JSON body for ``pronunciation-dictionary create``."""
+    _json(
+        {
+            "name": "tavus-defaults",
+            "rules": [
+                {
+                    "text": "tavus",
+                    "pronunciation": "TAH-vus",
+                    "type": "alias",
+                },
+                {
+                    "text": "kubernetes",
+                    "pronunciation": "ˌkuːbərˈnɛtɪz",
+                    "type": "ipa",
+                },
+            ],
+        }
+    )
+
+
+@persona_tools_app.command("list")
+def persona_tools_list(persona_id: str) -> None:
+    """List tools attached to a persona."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.personas.list_tools(persona_id)
+
+    _json(_run(run()))
+
+
+@persona_tools_app.command("attach")
+def persona_tools_attach(
+    persona_id: str,
+    tool_ids: list[str] = typer.Argument(..., help="One or more tool_id values."),
+) -> None:
+    """Attach existing tools to a persona by tool_id."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.personas.attach_tools(persona_id, list(tool_ids))
+
+    _json(_run(run()))
+
+
+@persona_tools_app.command("detach")
+def persona_tools_detach(persona_id: str, tool_id: str) -> None:
+    """Detach a tool from a persona."""
+
+    async def run() -> Any:
+        async with TavusClient.from_env() as client:
+            return await client.personas.detach_tool(persona_id, tool_id)
+
+    _json(_run(run()))
+
+
+def _resource(client: TavusClient, resource: str) -> Any:
+    normalized = resource.strip().lower().replace("-", "_")
+    aliases = {
+        "guardrail": "guardrails",
+        "objective": "objectives",
+        "document": "documents",
+        "voice": "voices",
+        "tool": "tools",
+    }
+    attr = aliases.get(normalized, normalized)
+    if attr not in {"guardrails", "objectives", "documents", "voices", "tools"}:
+        raise typer.BadParameter(
+            "resource must be guardrails, objectives, documents, voices, or tools"
+        )
+    return getattr(client, attr)
+
+
+def _print_rows(data: Any, columns: list[str]) -> None:
+    rows = data.get("data", data) if isinstance(data, dict) else data
+    if not isinstance(rows, list):
+        _json(data)
+        return
+    table = Table()
+    for column in columns:
+        table.add_column(column)
+    for row in rows:
+        table.add_row(*[str(row.get(column, "")) for column in columns])
+    console.print(table)
+
+
+if __name__ == "__main__":
+    app()