Command Reference
This page documents the current command surface in cli/src/main.rs and
cli/src/terminal_ui.rs.
See Verify & Recover for command approvals and file recovery.
TUI recovery commands are /checkpoints and /undo [id]. Enter submits a prompt;
Ctrl-J adds a newline, Tab completes slash commands, and Ctrl-R searches history.
Ctrl-L redraws the screen. Scrolling and resize work during replies. Esc/Ctrl-C
cancels a run or dismisses background model discovery and runtime checks.
Static help and setup controls work without a running model; Guide questions
and coding requests require one. See Fullscreen TUI for offline errors
and rendering behavior.
Shell Commands
Run through Cargo while developing:
cargo run --locked --manifest-path cli/Cargo.toml -- <command>
Installed examples use proto-cli <command>.
| Command | Meaning |
|---|---|
start | Start the fullscreen terminal UI. This is also the default when no command is passed. |
tui | Alias for fullscreen terminal UI. |
cli | Alias for fullscreen terminal UI. |
terminal | Alias for fullscreen terminal UI. |
ui | Alias for fullscreen terminal UI. |
checkpoints | List up to 50 native changes with their recovery states, plus up to 50 inspection-only legacy snapshots. |
undo [id] | Preview and approve restoring one checkpoint; defaults to latest and needs no model. |
run "task" | Run one task outside fullscreen mode. Requires an active project. |
dashboard, dash, status | Show cockpit status, provider strip, agent graph, and hotkeys. |
models | Show detected local/API models and validate API keys. |
model | Pick the active provider/model interactively. |
key [provider] | Store an API key for a supported API provider, then optionally choose a model. |
config | Show redacted provider config. |
version, versions, --version, -V | Show CLI, Python core, and planned ACP component versions. |
project | Show active project and recent projects. |
project set PATH | Set the active project folder. |
project clear | Clear the active project folder. |
project choose | Prompt for a project folder. |
ls [PATH] | List a project directory, including hidden entries; no model. |
browse [PATH], files [PATH] | Interactive folder navigation and read-only file viewing. |
open [FILE] | Scrollable text viewer; no path opens the browser. |
cat FILE | Print a bounded project text preview; works without a model. |
check | Show Python, platform, ProtoLink readiness, active provider status, and agent manifest. |
agents | Show the runtime kernel, RunContract, stateful Architect, stateless workers, optional Tester/Scout/MCP state, and tool isolation. |
agents profile [auto|small|medium|large|api] | Show or set the prompt profile used by Architect, Explorer, and Coder. |
agents small, agents medium, agents large, agents api | Shorthand for setting the deck prompt profile. |
agents scout [on|off] | Show, enable, or disable optional Scout. Changes apply to the next run. |
eval profiles [--plan|--live] [--profile MODE] [--task ID] [--limit N] [--json] | Run the built-in prompt-profile quality eval harness. |
eval tasks | List built-in quality eval tasks. |
eval harness [--json] | Run offline native engine-contract cases with scripted actions; no live model. |
context | Show Context Loom status for the active project. |
context QUERY | Build a source-cited Context Pack without running a model. |
context window [16k|auto] | Show, set, or clear the Ollama context window override. |
context history | Inspect saved ProtoLink Architect conversation state. |
context compact [recent|tokens|summary] [limit] | Compact saved ProtoLink histories and trim the Rust session index. |
context reset | Clear ProtoLink histories for the project session and trim Rust UI turns to zero. |
context on | Enable persistent project conversation memory. |
context off | Use task-local ProtoLink sessions until memory is turned on again. |
index refresh | Run an incremental Context Loom SQLite index refresh. |
sessions | Show saved project sessions and recent turns. |
help | Show static CLI help. |
help "question" | Ask the isolated Guide agent about ProtoAgent usage. |
Fullscreen Slash Commands
Slash commands are handled inside cli/src/terminal_ui.rs.
| Command | Meaning |
|---|---|
/quit, /exit | Leave the TUI. |
/clear | Clear the visible transcript. |
/ls [PATH] | List one project directory, including hidden files. |
/browse [PATH], /files [PATH] | Navigate folders, filter entries and open text files. |
/open [FILE] | Open the read-only viewer; no path opens the browser. Use /project to choose a workspace. |
/cat FILE | Display a bounded text preview directly in the transcript. Quote paths with spaces. |
/dashboard, /dash, /status | Pin the dashboard panel. |
/models | Pin the model inventory panel and refresh model status. |
/models choose, /models set, /models select | Open model selection. |
/model, /provider | Open provider/model selection. |
/key [provider] | Store an API key through a masked modal. |
/agents | Pin the Agents panel; shows required roles, prompt profile, all optional-worker ON/OFF states and their toggle commands. |
/agents profile [auto|small|medium|large|api] | Show or set the deck prompt profile. |
/agents small, /agents medium, /agents large, /agents api | Shorthand for changing prompt profile. |
/agents scout [on|off] | Show or change optional Scout for subsequent runs. |
/context, /loom | Show Context Loom status. |
/context QUERY | Preview a Context Pack. |
/context window [16k|auto] | Show or change context window settings. |
/context history | Inspect saved ProtoLink histories. |
/context compact [recent|tokens|summary] [limit] | Compact saved model-facing histories. |
/context reset | Reset saved ProtoLink histories for the active project session. |
/context on | Enable persistent conversation memory. |
/context off | Use task-local memory. |
/context memory | Show current memory mode. |
/index refresh | Refresh Context Loom index. |
/sessions, /session | Show saved sessions. |
/sessions choose, /session resume | Reopen a saved session's workspace. |
/session rename NAME | Rename the current saved UI session. |
/timeline, /flow | Show the structured path of the latest agent run. |
/trace | Show the latest normalized ProtoLink trace. |
/diff | Reopen the latest proposed diff or approval preview in the styled review modal. |
/diff raw | Print a truncated raw diff into the transcript. |
/config | Pin provider config panel. |
/debug [on|off] | Show the current debug display mode, reveal response metadata with a /trace hint, or hide it. Defaults off for each TUI session. |
/version, /versions | Show CLI, Python core, and planned ACP component versions. |
/project | Choose the active project. |
/project PATH | Open a project directly. |
/project clear | Clear the active project. |
/help, /menu | Show help panel and Guide availability. |
/help QUESTION | Stream a Guide answer using the active model and bundled command reference, without needing a project. Esc/Ctrl-C cancels. |
/check | Refresh runtime diagnostics. |
/last | Replay the last response in the current TUI process. |
/run TASK | Run a task from a slash command. |
Non-Slash Input
Any non-empty input that does not start with / runs as a task. The TUI
requires an active project before dispatching the request.
explain the runtime cancellation path
Use @ to insert tagged file context:
explain @core/protoagent_core/runtime.py and @cli/src/progress.rs
Tagged context is loaded before Context Loom and is treated as bounded read-only evidence unless the user explicitly asks for modifications.
Compaction Syntax
/context compact defaults to token compaction. Supported forms:
| Form | Effect |
|---|---|
/context compact | Compact each agent history to the default token budget. |
/context compact tokens 4000 | Keep each agent history under roughly 4000 estimated tokens. |
/context compact recent 8 | Keep a recent-message boundary. |
/context compact summary 6 | Use ProtoLink summary strategy preserving recent messages. |
/context compact 3 | Legacy shorthand: keep about three recent UI turns in the Rust ledger and use recent-history compaction. |
Exit And Cancellation
| Key | Context | Effect |
|---|---|---|
| Esc | TUI idle | Opens the exit confirmation modal. |
| Ctrl-C | TUI idle | Exits the TUI. |
| Esc | Task running | Writes a cancellation request for the Python bridge. |
| Ctrl-C | Task running | Same as Esc: requests cancellation. |
| Ctrl-D | Input empty | Exits the TUI. |
Task cancellation is best-effort and uses ProtoLink's task control path. If a task is already terminal, the runtime reports that cancellation arrived too late.
Coding evaluation
proto-cli eval coding prints a planned comparison by default. Add --live to
run disposable coding exercises with the current model and an independent oracle:
proto-cli eval coding --plan --json
proto-cli eval coding --live --profile small --task empty-average --json
Each exercise runs both the normal deck and a single-agent baseline. Live mode approves only fixture edits and the exact fixture check; generated code runs on the host. See Quality Evals for scoring and limits.
Optional workers and MCP setup
| Shell command | TUI equivalent | Purpose |
|---|---|---|
proto-cli agents tester on/off | /agents tester on/off | Test design on by default; off removes the model worker without skipping required checks. |
proto-cli agents mcp on/off | /agents mcp on/off | Model-free broker, off by default. |
proto-cli mcp | /mcp | Status/setup guidance without connecting. |
proto-cli mcp add NAME FILE.json | /mcp add NAME FILE.json | Import a named server and exact tool allowlist; does not connect or enable. |
proto-cli mcp test NAME | /mcp test NAME | Explicit connection/discovery, never server tool invocation. |
proto-cli mcp tools NAME TOOL | /mcp tools NAME TOOL | Inspect one original input schema. |
proto-cli mcp on/off | /mcp on/off | Same toggle as agents mcp. |
proto-cli mcp remove NAME | /mcp remove NAME | Remove one saved server. |
Use on or off as separate commands, not the literal string on/off.
Changes are user-wide and apply to the next run. Architect, Explorer, Coder and
Verifier cannot be disabled. Quote paths containing spaces. See MCP Broker
for config examples, authentication and runtime approval/effect boundaries.