# Commands and interfaces
[Feature docs index](README.md) · [Repository README](../../README.md)
## Purpose
Use startup flags, one-shot print mode, classic interactive shell commands, and Mission Control command entry points.
## Details
Startup flags:
```sh
magi-code # start a new interactive session
magi-code --no-session # interactive shell without session persistence
magi-code --continue # continue the most recent session, or create one if none exists
magi-code --resume <SESSION_ID> # resume a specific session
magi-code --provider local-provider # override provider
magi-code --model gpt-5.5 # override model
magi-code --api-key <KEY> # process-local API-key override; do not use for openai-codex OAuth
magi-code --version # print the installed magi-code version and exit
magi-code --color <auto|always|never> # ANSI color: flag > settings.no_color > NO_COLOR > auto TTY
magi-code --print "Prompt" # one-shot prompt with plain streamed output
magi-code "Prompt" # same one-shot behavior using a trailing prompt
magi-code --tui # opt-in Mission Control TUI; requires TTY stdin/stdout
```
Use `magi-code --print "Prompt"` or `magi-code "Prompt"` for scripts, logs, pipes, or command substitution. Print mode writes plain streamed assistant output by default, but `--color=always` forces ANSI color even when stdout is not a TTY and `--color=never` suppresses it.
`--resume` validates session IDs as usage input (exit 2). Missing, unreadable, unsafe, or bounded-read sessions fail before provider execution with a runtime diagnostic (exit 1) that omits paths and persisted content. `--continue` resumes latest eligible session or creates one when none exists. `--no-session` cannot be combined with either attachment flag.
Session maintenance: `magi-code sessions repair-permissions` repairs only recognized existing legacy session objects. Default mode prompts on TTY; `--yes` applies non-interactively; `--dry-run` previews count without mutation. `--yes` and `--dry-run` conflict. `MC_HOME` is resolved before inspection; unsafe layouts fail closed.
Provider-callable built-in tools include `read`, `write`, `hash_edit`, `fffind`, `ffgrep`, `list_files`, `repo_map`, `bash`/`shell`, `browser`, `view_image`, `parallel_subagents`, `web_search`, `code_search`, and opt-in LSP `diagnostics` / `references`. LSP tools appear only when LSP support is enabled and configured; see [LSP diagnostics](lsp-diagnostics.md).
Top-level prompt context tags expand after submission in `--print`, classic shell, and Mission Control before provider request construction and context-budget checks. Supported tags are exact standalone `#tree` for bounded `tree` output and `#git-status` for bounded `git status` output. Commands run from the active working directory through the existing guarded bash execution path; failures such as missing `tree` or a non-Git directory are included as bounded context blocks. Unknown tags, issue references such as `#40`, Markdown headings, and embedded forms such as `abc#tree` remain ordinary prompt text.
Classic interactive shell output uses terminal styling only when stdout is a TTY unless `--color=always` forces ANSI color. Color precedence is `--color` > `settings.no_color` > `NO_COLOR` > auto TTY detection. `NO_COLOR` disables ANSI color only; Unicode marks and line editor stay gated by stdin/stdout TTY, not color settings.
Exit codes: `0` success/help, `1` runtime/provider/tool/general failure, `2` usage/config/launch-validation failure.
Interactive slash commands:
| Command | Behavior |
| --- | --- |
| `/help` | Open the Mission Control help overlay; classic shell reports that it is TUI-only. |
| `/login` | List login providers in classic shell; open a login provider modal in Mission Control. |
| `/login openai-codex` | Start OpenAI Codex OAuth. |
| `/login custom-provider` | Configure a custom OpenAI-compatible provider. |
| `/logout` | List logout-capable providers in classic shell; open a logout provider modal in Mission Control. |
| `/logout openai-codex` | Remove local OpenAI Codex auth after confirmation/cancel handling. |
| `/logout <custom-provider-id>` | Remove local custom provider metadata from settings after confirmation. |
| `/compact [custom instructions]` | Run manual session compaction for the active persisted session. Older turns stay in JSONL history; future provider requests use the generated summary boundary plus later turns. Fails locally with no checkpoint when sessions are disabled, no active session exists, provider/auth/config fails, or the compaction request exceeds context budget. Mission Control rejects it while another provider run is active. |
| `/new` | Create and switch to a new session. |
| `/changes` | Show sanitized, read-only file changes from this session that can be rewound. Lists write/hash_edit tool snapshots by user turn and marks excluded, oversized, missing-blob, secret-path, and other non-rewindable entries without file bytes or diffs. Bash side effects are non-rewindable and not snapshotted. |
| `/rewind [--to <turn>] [--dry-run]` | Preview or apply filesystem restore from the latest rewindable turn back through `<turn>`. No-arg interactive shell prompts for a turn; Mission Control opens a picker modal across rewindable target turns. Mutation requires confirmation: shell defaults `y/N` to No, TUI requires Enter in the preview modal. `--dry-run` never mutates. Secret paths, denied paths, oversized files, missing blobs, and hash conflicts are skipped/reported as non-rewindable or unavailable. |
| `/prune-sessions [days]` | Delete old local top-level session JSONL files. With no argument it prunes sessions older than 30 days; with one positive integer such as `/prune-sessions 7` it uses that many days. The active session is never deleted, Mission Control rejects pruning while a prompt/tool run is active, and partial deletion continues while reporting bounded per-session categories such as `permission_denied` or `not_found`. |
| `/setmodel <provider>/<model-name>` | Validate against discovered or cached provider catalog, switch active provider/model, and persist settings. |
| `/setmodel` | Print provider-qualified usage in classic shell; open the TUI model picker in Mission Control. [Alt-M] opens the same picker from the prompt border when no prompt is running. Disabled models stay visible with `[disabled]` and cannot be selected. CLI `--model` bypasses disabled model settings. |
| `/models` | Open Mission Control model enable/disable modal; `[Tab]` switches Global/Project settings scope; classic shell reports that it is TUI-only. |
| `/usage` | Open Mission Control provider usage/quota modal backed by `quota-axi --json`; missing `quota-axi` shows install instructions; classic shell reports that it is TUI-only. |
| `/sessions` | Open a two-column Mission Control session switcher with selected-session preview; classic shell reports that it is TUI-only. |
| `/skills` | Open Mission Control skill enable/disable modal; `[Tab]` switches Global/Project settings scope; classic shell reports that it is TUI-only. |
| `/tools` | Open Mission Control tool enable/disable modal; `[Tab]` switches Global/Project settings scope; classic shell reports that it is TUI-only. |
| `/subagents` | Open Mission Control subagent profile enable/disable modal; `[Tab]` switches Global/Project settings scope; classic shell reports that it is TUI-only. |
| `/mcp` | Open the Mission Control MCP server enable/disable modal; classic shell reports that it is TUI-only. Changes persist to settings and take effect next run/session. |
| `/system-prompt` | Open a read-only Mission Control modal showing the computed system prompt. |
| `/quit` | Exit the shell or TUI. |
`/compact` is maintenance command, not chat input. It uses the active provider/model unless `settings.json` contains both non-blank `compaction.provider` and `compaction.model`, loads summary instructions from bundled `prompts/compact.md` or `~/.magi-code/prompts/compact.md`, runs without tools/tool definitions, and preserves historical tool call/result replay inside the compaction request. `/new` starts a fresh session; `/compact` keeps current session file and appends one checkpoint event.
`/changes` and `/rewind` are local maintenance commands, not chat input. They never route to the provider and do not require provider auth. Rewind covers agent file-tool writes/edits captured in the current session only; it is not whole-worktree rollback. Restore is hash-gated to avoid clobbering later user edits. Created files are moved with `trash` when available; if safe trashing is unavailable the operation is skipped. File bytes, diffs, blob hashes, denied paths, and secret-looking paths are never printed.
`/prune-sessions [days]` is destructive local cleanup, not chat input. It scans only regular top-level `*.jsonl` session files under `~/.magi-code/sessions`, computes age from latest valid event timestamp with file mtime fallback, deletes files strictly older than the retention window, skips the active session, and reports deleted/skipped/failed counts. Deleted session files cannot be resumed through `magi-code`. Matching checkpoint ledgers and unreferenced blobs are pruned with deleted sessions; blobs referenced by other session ledgers are kept.
`/help`, `/sessions`, `/skills`, `/tools`, `/subagents`, `/models`, `/usage`, `/mcp`, and `/system-prompt` are Mission Control-only modal commands. `/help` opens the same help overlay as `F1`.
`/sessions` opens an expanded switcher. Large terminals show a session list on the left and selected-session preview on the right. Preview shows first and most recent conversational user/assistant messages when found within bounded reads; metadata, hook, diagnostic, and tool-only events are ignored and preview text is sanitized/redacted before display. While modal is open, `Tab`/terminal-delivered `Shift-Tab` moves focus between list and preview, `Up`/`Down` moves list or scrolls preview by focus, mouse wheel scrolls hovered column, `Enter` switches, and `Esc` closes without switching.
`/skills`, `/tools`, `/subagents`, and `/models` open keyboard-only toggle modals in Mission Control. Rows show enabled checkboxes. `[Tab]` switches active settings scope between Global (`MC_HOME/settings.json` or `~/.magi-code/settings.json`) and Project (exact cwd `<cwd>/.magi-code/settings.json`; no parent search). `Enter` writes only active scope, creating project settings on first mutation. Project disabled lists replace global disabled lists for that cwd, so an explicit empty project list can re-enable globally disabled entries. `Esc` closes. `/models` stores canonical `provider/model` strings under `models.disabled`; disabled models remain visible in `/setmodel` with `[disabled]`, but `/setmodel` rejects selection. Current active model is not auto-switched if later disabled. CLI `--model provider/model` remains explicit override.
`/mcp` opens a keyboard-only MCP server toggle modal in Mission Control. Rows show configured server name, stdio/http type, and enabled checkbox. `Up`/`Down` moves, `Enter` toggles and saves `mcp_servers.<name>.enabled` in `settings.json`, and `Esc` closes. Changes do not reconnect live MCP managers; they apply next run/session.
`/usage` runs `quota-axi --json` off the UI thread, parses schema v2 usage JSON, and shows providers/windows with percentage remaining gauge bars. Providers with no displayable quota window are omitted. Missing CLI shows `npm install -g quota-axi` instructions. `Esc`/`q` closes; `Up`/`Down`, `PgUp`/`PgDn`, `Home`, and `End` scroll.
Unknown slash commands return a clear error and are recorded as diagnostics when a session is active.
---
[Back to feature docs](README.md) · [Back to repository README](../../README.md)