CLI / TUI
The Upivia terminal (upivia-tui) is a governed agent terminal built on Textual. Chat with Yupi, watch agents delegate work in real time, and edit files on your machine — all metered, policy-checked, and audited.
Overview
upivia-tui is a thin Python client over the platform's governed chat-turn pipeline. It streams over WebSocket (with SSE fallback) so the web app and the terminal can share one live session, and registers as a local device so the web app can edit files on your machine.
Installation
uv tool install upivia-tui # or: pipx install upivia-tui (requires Python 3.10+)
Architecture
- WebSocket realtime chat streaming with multi-client fan-out (SSE fallback)
- Local file operations (read, write, edit, search, run) sandboxed to the project dir
- OpenCode-style line-numbered, syntax-highlighted edit diffs
- Multi-agent delegation with a live Team panel + worker detail view
- Code graph navigation via Graphify (token-efficient)
- Background device mode — the web app edits files on this machine
- Web-driven working-directory control (cd + browse with tab-complete)
Install the TUI
Install once with uv or pipx; available as 'upivia-tui'.
Commands
| Command | Description |
|---|---|
| upivia-tui | Launch the full-screen TUI in the current directory. |
| upivia-tui --dir PATH | Launch rooted at a specific project directory. |
| upivia-tui --background | Headless device daemon — the web app can edit files on this machine. |
| upivia-tui init | First-time setup: authenticate and select workspace. Options: --url, --pat, --force. |
| upivia-tui whoami | Show the current session (URL, workspace, team). |
It reuses the shared ~/.upivia/config.json; you can also set UPIVIA_PAT and UPIVIA_BASE_URL instead of running init.
TUI Application
Layout
- Top Bar — Workspace, agent, mode (BUILD/PLAN), device link (● live / ○ local), balance, model
- Conversation — Boxed message cards with native markdown; edits render as +/- diffs
- Team Panel — Orchestrator + delegated workers with live status, spend, and activity
- Composer — Input with @file and / command autocomplete
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| Ctrl+P | Command palette — models, agents, sessions, worker detail, and more |
| Ctrl+O | Model picker — curated list + the full OpenRouter catalog |
| Ctrl+T | Agent switcher — pick the orchestrator |
| Ctrl+B | Session switcher — open a previous session (loads history) |
| Ctrl+G | Toggle BUILD / PLAN mode |
| Ctrl+L | New / clear session |
| Ctrl+Y | Copy (selection, or the last reply) |
| drag | Select text — auto-copies on release (OSC 52) |
| Escape | Close modals / dropdowns |
| Ctrl+Q | Exit the TUI |
Modes
| Mode | Behavior |
|---|---|
| build | Full tool access — delegates, edits files, runs commands. |
| plan | Proposes a plan only. No tools, no file writes. |
| semi-autonomous | Asks for major decisions, executes everything else. |
| autonomous | Works independently; asks any questions upfront. |
Command Palette (Ctrl+P)
Fuzzy-search every command: switch model/agent/session, worker detail, requests, export, compact.
Realtime sync & device mode
When the TUI is open, or while upivia-tui --background is running, this machine appears as a live device in the web app's Sessions view. Any web session attached to that device can read, write, edit, and run files on this machine — every operation flows through the same policy / budget / approval / audit pipeline.
A subtle folder control in the web Sessions header lets you set the device's working directory: type a path (Tab completes against available sub-directories) or click a listed folder. This rebases where the agent operates, sandboxed to the chosen root.
Local File Tools
Yupi and its workers can call these tools during a session. All file paths are sandboxed to the project root, and shell commands are gated by a one-time per-session permission grant.
| Tool | Signature | Description |
|---|---|---|
| local_read_file | (path) | Read file from project directory. |
| local_write_file | (path, content) | Create/overwrite file. Creates parent dirs. |
| local_edit_file | (path, old, new) | Surgical string replacement — token-efficient. |
| local_list_dir | (path?) | List directory contents. |
| local_run_command | (command) | Run a shell command (permission-gated). |
| local_search | (pattern, path?, glob?) | Regex grep across project files. |
| local_code_graph | (query) | Query the codebase AST graph via Graphify. |
Quick Reference
Install & Setup
uv tool install upivia-tui upivia-tui init; upivia-tui whoami
Everyday
upivia-tui # launch in current dir upivia-tui --dir ~/project # launch in a project upivia-tui --background # headless device for the web app
Shortcuts
| Key | Action |
|---|---|
| Ctrl+P | Command palette |
| Ctrl+O | Model picker |
| Ctrl+T | Agent switcher |
| Ctrl+B | Session switcher |
| Ctrl+G | Build / Plan |
| Ctrl+Y | Copy |
| Ctrl+L | New session |
| Escape | Close / abort |