# CLI and TUI reference
## Command line
```bash
mermaid # Start fresh session
mermaid --continue # Resume the most recent session in this directory
mermaid --resume # Pick a past session from a searchable list
mermaid --model ollama/qwen3-coder:30b # Ollama local (any installed model — `mermaid list`)
mermaid --model anthropic/<model> # Anthropic (requires ANTHROPIC_API_KEY)
mermaid --model gemini/<model> # Gemini (requires GOOGLE_API_KEY)
mermaid --model openai/<model> # OpenAI (requires OPENAI_API_KEY)
mermaid --model groq/<model> # Groq (requires GROQ_API_KEY)
mermaid --model grok/grok-4.6 # Grok (xAI) (requires XAI_API_KEY; alias xai/<model>)
mermaid --model nvidia/z-ai/glm-5.2 # NVIDIA NIM (requires NVIDIA_API_KEY)
mermaid --model cloudflare/@cf/zai-org/glm-5.2 # Cloudflare Workers AI (CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID)
mermaid --reasoning high # Override default reasoning depth
mermaid --path /path/to/project # Run against a specific project directory
mermaid --record /tmp/session.jsonl # Record reducer events for replay/debugging
mermaid --replay /tmp/session.jsonl # Reconstruct a recorded session (headless, deterministic)
mermaid --append-system-prompt "Prefer small diffs" # Add one-off runtime instructions
mermaid --append-system-prompt-file ./rules.md # ...or append them from a file
mermaid --system-prompt "You are terse." # Replace the default prompt for one run
mermaid --system-prompt-file ./prompt.md # ...or replace it from a file
mermaid --output-style concise # Use an output style for one run (session-scoped)
mermaid -c safety.mode=full_access # Override any config key for this run (repeatable, TOML values)
mermaid --profile ci # Apply the [profiles.ci] overlay from your user config
mermaid -v # Verbose logging
mermaid list # List available models across providers
mermaid doctor # First-run readiness check
mermaid status # Lower-level Ollama, MCP, and provider config
mermaid update # Update to the latest release (or use brew/scoop)
mermaid self-test # Fast deterministic Mermaid self-test
mermaid init # Create default config file
mermaid cloud-setup # Configure Ollama Cloud API key
mermaid run "fix the tests" # Non-interactive mode
mermaid run "explain main.rs" -f json # JSON output (single typed object)
mermaid run "explain main.rs" -f ndjson # Streaming NDJSON events (SDK/scripting)
mermaid run "summarize this repo" --output-schema schema.json -f json
# Structured output: the agentic loop runs
# normally, then one formatting turn reshapes
# the answer to your JSON Schema (validated
# client-side; result carries structured_output).
# Native constrained output on OpenAI-compatible
# providers, Gemini, Ollama, and Anthropic
# (output_config.format on current models).
mermaid --resume <id> run "and now the tests" # Continue a saved session headless (id from
# ndjson session_started/result, json result,
# or the `session:` line on stderr)
mermaid --continue run "keep going" # Resume this directory's most recent session
mermaid --no-network run "audit the code" # Deny web tools everywhere; shell network on Linux/macOS/Windows
mermaid --confine-fs run "tidy the tests" # Confine shell writes to the project, temp dir (and /dev)
mermaid --sandbox run "refactor this" # Both at once (see docs/sandbox.md)
mermaid add <name> # Add an MCP server (e.g., context7, git)
mermaid remove <name> # Remove a configured MCP server
mermaid mcp # List configured MCP servers
```
`mermaid tasks`, `mermaid processes`, `mermaid plugin`, and the other durable-runtime verbs are
documented in [runtime.md](runtime.md).
## Keyboard shortcuts
| Key | Action |
|-----|--------|
| Enter | Send message (or queue while the model is generating) |
| Esc | Stop generation / dismiss command palette or attachment focus |
| Esc Esc | (idle) Rewind: fork the session at an earlier message — original preserved, composer pre-filled |
| Ctrl+C | Quit (auto-saves the session) |
| Ctrl+D | Quit when the input box is empty (auto-saves the session) |
| Ctrl+B | While tools are running, send the foreground command to the background (it keeps running as a `/processes` entry) |
| Alt+T | Cycle reasoning level: `None → Minimal → Low → Medium → High → XHigh → Max → None` |
| Shift+Tab | Cycle safety mode: `read_only → ask → auto → full_access → read_only` (session-scoped) |
| Ctrl+V | Paste image or text from clipboard (a copied image *file* pastes as the image) |
| Ctrl+O | Compose the prompt in `$VISUAL`/`$EDITOR` (TUI suspends, resumes on save-quit) |
| Ctrl+Click | Open image from chat history |
| Drag | Select chat text (highlights; does not copy) |
| Ctrl+Shift+C | Copy the selected chat text to the clipboard |
| Shift+Drag | Native terminal selection (bypasses Mermaid's mouse capture — useful for selecting across the whole window, including the input box and status bar) |
| `/` | Open slash-command palette (filter-as-you-type); closes itself when nothing matches |
| `@` | Open the fuzzy file picker (at the start of a word); type to filter, Tab/Enter inserts `@path`, Esc dismisses |
| Tab | In palette: complete highlighted command name |
| Up/Down | Navigate input history; palette and conversation-list navigation |
| Mouse Wheel | Scroll chat |
### Message queuing and mid-run steering
Type while the agent works. Queued messages are delivered at the next tool boundary within the
run, so the model course-corrects mid-task, or at run end when no boundary follows.
### Image paste
Ctrl+V attaches images for vision models on X11, Wayland, macOS, and Windows. All three
clipboard shapes work on every backend: a raster copy (screenshot tools, "Copy image"), an
encoded blob with no raster form (GIMP, Figma — `PNG` with no `CF_BITMAP`), and a file reference
from a file manager's Copy (Explorer / Finder / Nautilus). File-reference pastes accept
png/jpeg/gif/webp/bmp/tiff up to 32 MB.
The paste reads the clipboard through the platform's own helper:
| Platform | Helper |
| --- | --- |
| Linux / X11 | `xclip` |
| Linux / Wayland | `wl-clipboard` (`wl-paste`) |
| macOS | `pngpaste` / `osascript` |
| Windows | PowerShell |
```bash
sudo apt install xclip # X11
sudo apt install wl-clipboard # Wayland
```
### @-mentions
Type `@` in the composer to fuzzy-pick a project file (gitignore-aware); the path lands in your
prompt as text the agent reads with its tools.
## Slash commands
Type `/` to open the command palette (shows all commands with live filter); type `/<name>` to invoke directly. `/help` shows the same commands grouped in the TUI.
A line is a command only when its first word names one. Anything else that happens to start with a slash is an ordinary message: paths (`/etc/hosts`, `/home/you/pkg.deb can you make this run on fedora`), a doubled slash (`//`), a typo, or a leading space before the slash. While you type one, the palette closes, Up/Down/Tab/Esc keep their normal meanings, and Enter sends the line exactly as written. While the line is still a bare word, a dim `No commands match "/tmp"` sits above the composer to explain why nothing is filtering; it disappears once a space follows, since a sentence needs no caption.
Everyday:
- `/doctor` — show current model, safety, prompt, instruction, and tool readiness
- `/clear`, `/save [name]`, `/load [id]`, `/list` — manage the conversation
- `/cancel [id]` — cancel the active turn or a durable task
- `/handoff [id]`, `/report [id]` — write a current-context report or inspect a task report
- `/theme [dark|light]` — switch the color theme (persisted); `NO_COLOR` disables colors entirely
- `/todos` — show or edit the task checklist the agent keeps for the current run
- `/scratchpad` — show the session's scratch directory and what is in it
- `/editor` — compose the prompt in `$VISUAL`/`$EDITOR` (Ctrl+O keeps the current draft)
- `/help` (`/h`), `/quit` (`/q`)
Model and context:
- `/model` — open the model picker: every model this machine can reach, local Ollama models grouped first, the active one marked, type to filter (↑↓ navigate · Enter switch · Esc cancel). Rows drop the provider their group heading already names — `mistralai/mistral-large-2-instruct` under `nvidia` — and the footer shows the highlighted row's full id, the string `/model <name>` and `--model` take. `/model <name>` switches directly; either way an Ollama model auto-pulls if needed
- `/reasoning <level>` — set reasoning: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`
- `/visible-reasoning [on|off|toggle]` — show or hide reasoning blocks in the transcript
- `/usage`, `/context`, `/compact [instructions]`
- `/model-info <model>`
- `/output-style [name] [--project]` — show or set the output style (voice/format preset: `default`, `proactive`, `concise`, `explanatory`, `learning`, or a custom style file). Persists to your user config, or to the project config with `--project`; applies to the next message, subagents keep the stock prompt
Durable memory:
- `/memory` (alias `/memories`) — list the durable facts Mermaid has saved across sessions
- `/remember <fact>` — save a fact to durable memory
- `/forget <name>` — delete a saved memory by name
- `/consolidate-memory` (aliases `/memory-consolidate`, `/prune-memory`) — merge duplicates and prune stale memories
Safety and recovery:
- `/safety [read_only|ask|auto|full_access]` (alias `/permission`) — show or set the session safety mode; Shift+Tab cycles it
- `/approvals`, `/approve <id>`, `/deny <id>`
- `/checkpoint <path...>`, `/checkpoints`, `/restore <id>`
Integrations:
- `/plugins`, `/cloud-setup`
Advanced runtime:
- `/tasks`, `/task <id>`, `/pause <id>`, `/resume <id>`
- `/agents` — list background subagents, or kill one
- `/processes`, `/logs <id>`, `/stop <id>`, `/restart <id>`, `/open <target>`, `/ports`
Reasoning choices persist per-model: set `/reasoning high` on one model and `/reasoning low` on another, and each is remembered independently across sessions.