tavora CLI

The tavora CLI lives in tavora-tools. It’s the primary authoring surface for Tavora agents: a local tavora/ folder is the source of truth, and the CLI’s init / dev / deploy verbs sync it to the platform. The same binary also wraps the /api/sdk/* runtime surface for ops, scripting, and CI gates.

A second binary, tavora-tui, is the interactive terminal UI for chatting with a configured agent.

Install

Pre-built binaries: see the Releases page.

From source:

git clone https://github.com/tavora-ai/tavora-tools
cd tavora-tools
go install ./cmd/tavora      # CLI
go install ./cmd/tavora-tui  # TUI

Configure

Two paths, both work:

Interactive (recommended)

tavora login

Prompts for the Tavora URL and an app-scoped API key, validates the key against /api/sdk/app, and writes the config to ~/.tavora.yaml. Subsequent commands pick it up automatically.

Environment variables

export TAVORA_URL=https://api.tavora.ai
export TAVORA_API_KEY=tvr_...

tavora show

Flags

tavora --url https://api.tavora.ai --api-key tvr_... show

Precedence is flag > env > config file. The CLI never echoes the key back at you — tavora show confirms the connection by showing the app metadata.

API keys are app-scoped (one key, one app). To work against multiple apps from one shell, swap TAVORA_API_KEY per command or pass --api-key directly.

Global flags

Flag	Effect
--api-key <key>	API key (tvr_…); env: TAVORA_API_KEY.
--url <url>	Server URL; env: TAVORA_URL.
--config <path>	Override ~/.tavora.yaml.
--output text|json	json is structured and pipeable into jq. Default text.
--quiet / -q	Suppress status messages — emit data only. Pairs well with --output json.

Subcommand reference

Every subcommand prints --help; the tables below are the orienting map.

Code-first authoring

The authoring loop:

tavora init                       # scaffold tavora/{tavora.jsonc, agents/...}
tavora dev                        # watch + sync drafts on save (250ms debounce)
tavora run <agent> "<input>"      # run the local draft; writes .runs/<ts>-<agent>-<sid>.md
tavora deploy                     # validate + sync + snapshot as an immutable version
tavora deploy --dry-run           # validate only — CI gate

Agent identity is (project, local_id) from tavora.jsonc and agent.jsonc. Renames and deletes are explicit:

tavora rename <old-id> <new-id>   # keeps the server-side binding stable
tavora delete <id> [--yes]        # destroys the agent + cascades versions, sessions, evals

Resolved-config inspection:

tavora config show <agent>        # resolved JSON (post env-var substitution)
tavora open <ref>                 # open the source file backing a config field

Session forensics

Every tavora run writes a self-contained markdown trace to tavora/.runs/. Browse them offline:

tavora session latest             # newest run for any agent in the project
tavora session get <id-prefix>    # full markdown for a specific session
tavora session list               # most-recent N sessions in the project

Retention defaults to 50 runs (override via tavora.jsonc → retention.runs). For server-side traces — including SDK-triggered and scheduled runs — use the session detail view in the browser (/sessions/:id).

Agents — runtime

The runtime side of agents (sessions, not configs):

tavora agents list                                  # all sessions in this app
tavora agents create [--system "..."] [--title]     # new ad-hoc session
tavora agents get      <session-id>
tavora agents run      <session-id> "<message>"     # stream a turn
tavora agents interactive <session-id>              # one-off REPL — TUI is the richer surface
tavora agents delete   <session-id>
tavora agents prompt                                # print the runtime system prompt for this app

Skills

Skills are authored as .js / .md files under tavora/agents/<id>/skills/ and arrive via tavora dev. The CLI’s skills verbs are read-only:

tavora skills list
tavora skills get <skill-id>
tavora skills authoring-guide -o skill-authoring.md   # → feed to your editor's LLM

tavora skills authoring-guide fetches the live runtime’s authoring reference — sandbox primitives, reserved names, ES5.1 constraints — and writes Markdown you can hand to Claude Code / Cursor as context when drafting skills.

MCP servers

MCP servers are declared inline in agent.jsonc → mcp and flow through tavora dev. There is no tavora mcp subcommand — edit agent.jsonc, save, and tavora dev syncs and validates the block (URL reachable, auth refs resolve). See MCP servers for the JSONC shape.

Documents & search

tavora stores list
tavora stores create --name "Support docs" --description "..."
tavora stores delete <store-id>

tavora documents upload  --store <store-id> ./faq.md
tavora documents upload  --store <store-id> ./docs/              # whole directory
tavora documents wait    <doc-id>          # block until embeddings ready
tavora documents list    --store <store-id>
tavora documents get     <doc-id>
tavora documents delete  <doc-id>

tavora search "what document formats are supported?" --store <store-id> --limit 5

Naming drift

The CLI’s stores subcommand wraps the same surface the SDK exposes as Index / createIndex. The rename to indexes is rolling through the codebase; the CLI subcommand will become tavora indexes in a future release. Use tavora stores until then.

Evals (advisory)

Eval cases live as JSON files under tavora/agents/<id>/evals/ and flow through source-sync. The CLI’s evals verbs are read + trigger:

tavora evals list                                 # cases for the current app
tavora evals run <agent>                          # advisory eval on the agent's pinned suite
tavora evals runs list                            # recent eval runs
tavora evals runs get <run-id>
tavora evals latest <agent>                       # last eval run for this agent

tavora deploy --run-evals will run the agent’s pinned suite as part of a deploy. Eval results never block deploy — the Phase-12 promotion gate was removed in the 2026-05-11 slim-down.

RAG eval (CI gates)

Two pre-built CI gates over the RAG pipeline, both designed for unattended execution:

tavora rag-eval formats --gate          # exit non-zero if any supported format fails to index
tavora rag-eval judge   --gate --pass-threshold 7   # LLM-as-judge against fixture invoices

rag-eval judge requires GEMINI_API_KEY in env (or the equivalent provider key for your judge model). Useful as a smoke test after a schema migration or a chunker tweak.

Scheduled runs

tavora schedules list
tavora schedules create --agent <id> --cron "0 9 * * 1" --message "Weekly brief"
tavora schedules get    <schedule-id>
tavora schedules delete <schedule-id>

Prompt templates

tavora templates list
tavora templates create --name <name> --body @template.md
tavora templates get    <template-id>
tavora templates update <template-id> --body @template.md
tavora templates delete <template-id>

App + metrics

tavora show             # app metadata + tier
tavora metrics          # tokens / agent / eval rollup (billing-dashboard shape)

Output formats and piping

Every command honours --output json. Combine with jq for one-line ops:

# All sessions over the last day that errored
tavora agents list --output json | \
  jq '.[] | select(.status=="error") | {id, created_at}'

# Trigger an advisory eval on every code-first agent in the project
for agent in $(tavora config show --output json | jq -r '.agents[].id'); do
  tavora evals run "$agent"
done

--quiet strips the status banner so --output json lands as clean JSON suitable for piping.

Next steps

• CI integration — tavora deploy --dry-run and rag-eval --gate patterns for GitHub Actions / GitLab CI / arbitrary shells.
• Interactive TUI — tavora-tui for chatting with an agent from the terminal.
• SDK overview — programmatic equivalents in Go and TypeScript.
• Tutorials — step-by-step integrator walkthroughs.