Skip to content

cli-reference.md

Latest commit

 

History

History
118 lines (91 loc) · 6.67 KB

cli-reference.md

File metadata and controls

118 lines (91 loc) · 6.67 KB
Raw

CLI Reference

Every slash command, grouped the same way /help groups them inside Tuffy. See src/cli/commands.py for the implementation.

Chat

Command What it does
/new Start a fresh conversation. Long-term memory is untouched.
/clear Reset the in-window conversation history. Long-term memory is untouched — same effect as /new. Use /purge to actually wipe memory.
/image <path> Attach an image file to your next message (requires a vision-capable model).
`/mode [text voice]`

Models

/models is an arrow-key picker, not a listing: it shows every registered model as one row — id, name, provider, capabilities — and Up/Down + Enter loads the highlighted one. Esc (or Ctrl-C) backs out, leaving the session on the model it was already using.

Command What it does
/models Pick the active model with ↑/↓ and Enter. Loads the new model before unloading the old one, so a failed load leaves you on the working model.
/models default Same picker, and the chosen model is also persisted as the startup default (.tuffy/settings.json, gitignored) so it loads automatically next time Tuffy starts.
/models info Same picker, then print that model's full card: capabilities, context length, license, source, and (for API models) endpoint and API-key state.

Picking an API model while offline switches the session online automatically — see Network below. Each subcommand also accepts an id directly (/models <id>, /models info <id>, /models default <id>), which is what the picker falls back to when stdin is not a terminal (piped input, scripts).

Network

Online/offline is chosen at startup and changeable any time. It is a single word that controls four separate things, which is why /network info exists to print all of them at once.

Command What it does
/network Show the current mode.
/network online Allow API models, web tools, and the memory embedder's first-run download.
/network offline Restrict the session to local models (switching away from an API model to the local fallback if one is active), hide and refuse the network tools, and block the embedder download.
/network info Full report: current and persisted mode, active model and provider, API-key state, which tools the mode hides, the memory embedder's download/load state and cache path, and which TTS engine voice mode will use.

What the mode decides:

  • Models — offline permits local (llama_cpp) models only. Picking an API model while offline turns the session online rather than refusing the switch; if that model then fails to load, the mode reverts to offline. Going offline while an API model is active falls back to the local FALLBACK_MODEL.
  • Tools — web_search and translate are removed from the system prompt and refuse to run offline (OFFLINE_UNAVAILABLE_TOOLS in src/tools/research.py).
  • Memory — the semantic-recall embedder may only download while online. Offline with nothing cached, memory retrieval falls back to SQLite FTS5 keyword search. See src/embedder.py.
  • Voice — offline uses local Piper TTS; online uses Maya Research's cloud TTS, falling back to Piper if MAYA_API_KEY is missing or unreachable. Switching mode mid-session re-resolves the engine immediately. See configure-voice.md.

The choice is persisted (.tuffy/settings.json) and pre-selected at the next startup prompt.

Memory

Command What it does
/memory Show a summary of long-term memory: store stats, facts about you, recent session summaries, lessons learned, knowledge-graph clusters.
/memory search <query> Search past conversations and stored facts (same recall the recall tool uses).
/memory facts <key> Show the full version history of one fact key.
/memory quarantine Show recently rejected/quarantined auto-extractions (e.g. self-referential or identity-shaped values remember/reflection tried to store).
/memory forget <key> Forget a fact key — a non-destructive tombstone, not a hard delete.
/purge Wipe the long-term memory database: archives the current tuffy.db to data/memory/backups/ and opens a fresh one. Also resets the conversation history.

Inspect

Command What it does
/status Show the active model, vision support, turn count, estimated context usage (vs. the model's max), recent turn health, and rate limits (API models).
/tools List every tool the agent can call, grouped by domain (native and MCP). Descriptions are shown to their first sentence; the model always gets the full text.
/skills List installed skills. Drop a new one in ./.tuffy/skills/<name>/ and restart to add more.
/mcp List connected MCP servers and the tools each one registered.
/mcp add <github-url> [name] Resolve a GitHub repo to an MCP server config, save it, and connect immediately.
/mcp remove <name> Disconnect a server and remove it from config.

Session

Command What it does
/help Show the categorized command list.
/exit, /quit Save session memory and terminate.

Output conventions

Every command prints through the same layout helpers in src/cli/display.py (print_heading, print_rows, print_fields), so padding and color mean the same thing everywhere: blue bold headings, green for identifiers you can type and for success, yellow for warnings and unavailable states, dim for labels and secondary detail. Name and label columns are padded to one width across a whole command's output, not per block.

Adding a new command

See src/cli/README.md — write a cmd_<name> function, add a branch to handle_command(), add a row to _HELP_SECTIONS (under the group whose subject it acts on), and print through the display.py helpers above. No other file needs to change.

Debugging: TUFFY_DEBUG_CONTEXT

Set TUFFY_DEBUG_CONTEXT=<path> before starting Tuffy to append the exact system prompt and full message history sent to the model, for every turn, to that file:

TUFFY_DEBUG_CONTEXT=/tmp/tuffy-debug.log uv run main.py

This is a ground-truth trace of what the model actually saw — useful for diagnosing memory/context bugs (a stale or garbled fact, retrieval returning the wrong thing, history growing unexpectedly large) that aren't visible from the rendered chat transcript alone. No-op (zero file I/O) when unset. See _dump_debug_context in src/cli/turn.py.