Skip to content
Tavora

tavora-tui

tavora-tui is the interactive terminal UI for talking to an agent you already configured. A scrolling output viewport on top, a prompt input on the bottom, and every SSE event from the agent (execute_js, tool_call, tool_result, sandbox_event, response) streams into the viewport live. It’s built on Bubble Tea and consumes the public tavora-sdk-go, so it doubles as a worked example of SDK integration.

Use it when you want to:

  • Test an agent end-to-end without a browser.
  • Demo what an agent does without spinning up a frontend.
  • Resume a long-running session you started elsewhere.
  • Read tool traces inline as the agent runs.

For authoring agents, skills, or MCP servers — use the tavora CLI. For chatting with them, use the TUI.

Install

Section titled “Install”
Terminal window
go install github.com/tavora-ai/tavora-tools/cmd/tavora-tui@latest
# or from a source checkout:
go install ./cmd/tavora-tui

First run

Section titled “First run”
Terminal window
tavora-tui

First run drops you into a setup screen that asks for the Tavora URL and an app-scoped API key. The key is validated against /api/sdk/app before anything is saved. On success the credentials persist to:

  • macOS: ~/Library/Application Support/tavora/agent-tui.json
  • Linux: $XDG_CONFIG_HOME/tavora/agent-tui.json (or ~/.config/tavora/agent-tui.json)
  • Override: TAVORA_TUI_CONFIG=/path/to/file

After credentials, the TUI picks an agent:

  • One agent in the app → auto-select.
  • Two or more → interactive picker (filter with /).
  • Zero → error pointing you at tavora agents versions create <agent-id> ....

The session is created bound to the agent’s active version, so persona, model, and the version’s skills_json filtering resolve automatically. No agent → no TUI, by design.

Subsequent runs

Section titled “Subsequent runs”
Terminal window
tavora-tui                                # uses stored config
TAVORA_URL=... TAVORA_API_KEY=... tavora-tui   # env wins (not persisted)
tavora-tui --reset-config                 # rerun setup
tavora-tui --agent <id-or-name>           # skip the picker
tavora-tui --tools search,list_stores     # enable extra platform tools
tavora-tui --session <id>                 # resume a prior server-side session

When the TUI exits (/quit, ctrl+c, or fatal error) it prints the current session ID and the exact --session invocation to resume it. Sessions live server-side and retain their full history, so resuming picks up where the conversation left off.

In the chat

Section titled “In the chat”
Key / commandEffect
enterSend the prompt
up / downBrowse prompt history; in-progress draft restored on down past newest
ctrl+cQuit (also prints resume command)
/upload <path>Upload a file as a document and reference it in the next turn
/quitQuit
/helpPrint the keybinding cheat sheet

Tool calls render inline as → <tool>(args) / ← <tool> ok. The viewport autoscrolls to follow output, but pgup / pgdn pause follow and let you scroll the history.

When you’d reach for it vs the CLI

Section titled “When you’d reach for it vs the CLI”
Want to…Use
Send one message and capture output for a scripttavora agents run <session-id> "<msg>" --output json
Iterate on a prompt or skill against the same agenttavora-tui --agent <id>
Demo what an agent does in a screencasttavora-tui (terminal recordings render beautifully)
Replay a session from a specific step with a tweaked prompttavora studio replay <session-id> --from-step N
Resume a session whose ID you havetavora-tui --session <id>

The CLI is for ops and scripting; the TUI is for conversation. Use both — they share configuration, so swapping between them is friction- free.

Section titled “Related”