| 1 | # Reasonix CLI Reference |
| 2 | |
| 3 | <a href="../README.md">README</a> |
| 4 | · |
| 5 | <a href="./CLI.zh-CN.md">简体中文</a> |
| 6 | · |
| 7 | <a href="./GUIDE.md">Guide</a> |
| 8 | |
| 9 | This reference covers interactive sessions, one-shot automation, session |
| 10 | resume, permission flags, and the most useful in-session commands. For provider |
| 11 | configuration, plugins, and sandbox policy, see the [Guide](./GUIDE.md). |
| 12 | |
| 13 | ## Start a session |
| 14 | |
| 15 | ```sh |
| 16 | reasonix |
| 17 | reasonix --model deepseek-pro |
| 18 | reasonix --effort high |
| 19 | reasonix --dir /path/to/project |
| 20 | ``` |
| 21 | |
| 22 | Ordinary requests always enter the executor. There is no automatic simple / |
| 23 | light / full task mode to pick. The dedicated planner runs only for an |
| 24 | explicit Plan, an approval boundary, or Goal start. |
| 25 | |
| 26 | Running `reasonix` without a subcommand starts the interactive terminal UI. If |
| 27 | the selected connection has no credential, the local connection picker opens |
| 28 | instead of sending a request. History and local commands remain available while |
| 29 | authentication is incomplete. |
| 30 | |
| 31 | | Flag | Purpose | |
| 32 | | --- | --- | |
| 33 | | `--model NAME` | Select a configured provider or `provider/model` reference. | |
| 34 | | `--effort LEVEL` | Override reasoning effort for this session. | |
| 35 | | `--max-steps N` | Set a one-off maximum tool-call round budget; `0` uses automatic execution. | |
| 36 | | `--dir PATH` | Change the workspace root before loading config and tools. | |
| 37 | | `--add-dir PATH` | Add another writable tool directory; repeat for multiple directories. | |
| 38 | | `-c`, `--continue` | Resume the most recent session. | |
| 39 | | `-r`, `--resume [QUERY]` | Open the session picker, or resume a matching session. | |
| 40 | | `--copy` | Continue in a writable copy of the resumed session. | |
| 41 | | `--allowed-tools RULES` | Add session-only permission allow rules. Repeatable; `--allowedTools` is an alias. | |
| 42 | | `--permission-mode MODE` | Start with a specific permission posture. | |
| 43 | | `--dangerously-skip-permissions` | Deprecated compatibility flag; migrates conservatively to `workspace-write`. Use `--permission-mode danger-full-access` for YOLO. | |
| 44 | |
| 45 | Flags may appear before or after the prompt where applicable. |
| 46 | |
| 47 | ## Update the native CLI |
| 48 | |
| 49 | ```sh |
| 50 | reasonix upgrade # install the latest official release |
| 51 | reasonix upgrade --check # report the target without installing |
| 52 | reasonix upgrade --force # reinstall the current official release |
| 53 | ``` |
| 54 | |
| 55 | The updater selects only strict `vX.Y.Z` non-prerelease GitHub Releases. During |
| 56 | the 1.x compatibility period, old channel arguments and `--channel` are still |
| 57 | accepted, but resolve to the same official release and print a deprecation |
| 58 | notice. Legacy `[cli].update_channel` values are ignored and removed the next |
| 59 | time Reasonix saves the configuration. The `reasonix update` alias behaves the |
| 60 | same way. |
| 61 | |
| 62 | ## Configure providers |
| 63 | |
| 64 | ```sh |
| 65 | reasonix setup # manage the user-global config |
| 66 | reasonix setup --local # manage ./reasonix.toml |
| 67 | reasonix setup /path/to/config.toml |
| 68 | ``` |
| 69 | |
| 70 | In an interactive terminal, `reasonix setup` is a staged provider manager. It |
| 71 | lists configured providers and lets you: |
| 72 | |
| 73 | - add OpenAI-compatible or Anthropic-compatible providers; |
| 74 | - edit endpoints and model lists; |
| 75 | - update API keys or test the connection and refresh models; |
| 76 | - choose the default model; and |
| 77 | - remove providers. |
| 78 | |
| 79 | Choose **Save and exit** to review and confirm the pending operations. Canceling |
| 80 | discards them. Setup reloads the latest config while saving: unrelated desktop |
| 81 | or CLI changes are retained, while an overlapping change is reported as a |
| 82 | conflict instead of being overwritten. |
| 83 | |
| 84 | Provider definitions contain only the `api_key_env` variable name. Key values |
| 85 | are stored in the shared Reasonix home `.env`, even with `--local`. Adding, |
| 86 | replacing, or explicitly clearing a key creates a fresh private credential slot |
| 87 | and atomically switches only the selected connection to it. Existing fixed |
| 88 | variables remain readable and migrate only when that connection is edited. |
| 89 | |
| 90 | Inside the TUI, `/setup` opens the same connection flow and `/auth` is an alias. |
| 91 | The key field is masked; press `Ctrl+T` to test the draft connection, Enter to |
| 92 | save, or Escape to cancel. `/?` is an alias for `/help`. Authentication that is |
| 93 | not ready never turns ordinary input into a provider request. |
| 94 | |
| 95 | ```sh |
| 96 | reasonix doctor credentials |
| 97 | reasonix doctor credentials --json |
| 98 | reasonix doctor credentials --probe |
| 99 | reasonix doctor credentials --repair --dry-run |
| 100 | reasonix doctor credentials --repair |
| 101 | ``` |
| 102 | |
| 103 | The default diagnostic is read-only. `--probe` tests temporary create and |
| 104 | atomic rename without replacing `.env`. Repair is limited to a current-user- |
| 105 | owned regular file inside Reasonix home; it does not take ownership, remove deny |
| 106 | rules, grant `Everyone`, follow links/reparse points, or kill a file holder. |
| 107 | |
| 108 | ### Configure fee display currency |
| 109 | |
| 110 | Use the user-global command to inspect or select the display currency: |
| 111 | |
| 112 | ```sh |
| 113 | reasonix config currency # show the saved and resolved currency |
| 114 | reasonix config currency auto # wallet hint, then original price currency |
| 115 | reasonix config currency CNY |
| 116 | reasonix config currency USD |
| 117 | ``` |
| 118 | |
| 119 | `auto` remains unresolved in configuration. With one valid wallet currency it |
| 120 | can become a runtime session hint; otherwise CLI uses the original currency or |
| 121 | sorted currency buckets. Language and host locale never select a price table. |
| 122 | The preference is user-global and cannot be overridden by project |
| 123 | `reasonix.toml`; `--local` is therefore not supported. Custom prices are preserved. |
| 124 | |
| 125 | In an interactive session, `/currency` shows the saved and resolved values, and |
| 126 | `/currency auto|CNY|USD` changes the preference and refreshes the current |
| 127 | runtime without discarding the conversation. |
| 128 | |
| 129 | ### Configure automatic compaction |
| 130 | |
| 131 | The desktop app and CLI share the user-global automatic compaction threshold. |
| 132 | Inspect the effective percentage and its source, set the global default, or add |
| 133 | a project override: |
| 134 | |
| 135 | ```sh |
| 136 | reasonix config compact-ratio # show effective value and source |
| 137 | reasonix config compact-ratio 75 # set the user-global default |
| 138 | reasonix config compact-ratio --local 75 # override in ./reasonix.toml |
| 139 | ``` |
| 140 | |
| 141 | The editable range is 30–85%, with 80% as the built-in default. Lower values |
| 142 | compact earlier, may increase summary calls and cost, and may reduce |
| 143 | prompt-prefix cache reuse; higher values retain more context before compaction. |
| 144 | Below the threshold, complete tool results may |
| 145 | increase ordinary request cost; at pressure they are durably pruned before the |
| 146 | cache-aligned summary runs. Project `reasonix.toml` takes precedence over |
| 147 | the user config. Changes apply to new CLI sessions; an already-running session |
| 148 | keeps the threshold it loaded at startup. |
| 149 | |
| 150 | ## One-shot and automation |
| 151 | |
| 152 | Use `-p` / `--print` when a script needs only the final answer: |
| 153 | |
| 154 | ```sh |
| 155 | reasonix -p "summarize this repository" |
| 156 | reasonix -p "summarize this repository" --output-format json |
| 157 | reasonix run "implement the TODOs in main.go" |
| 158 | reasonix run --auto "implement the TODOs in main.go" |
| 159 | echo "explain this code" | reasonix run |
| 160 | ``` |
| 161 | |
| 162 | `reasonix run` keeps the normal streamed terminal presentation unless `-p` or a |
| 163 | structured output format is selected. It also accepts `--model`, |
| 164 | `--max-steps`, `--effort`, `--dir`, `--add-dir`, |
| 165 | `--continue`, `--resume QUERY`, `--copy`, `--allowed-tools`, `--permission-mode`, |
| 166 | and `--auto` / `-y` (legacy aliases for `--permission-mode workspace-write`). |
| 167 | |
| 168 | ### Benchmark arms |
| 169 | |
| 170 | `--ablate` switches whole subsystems off so a benchmark can attribute a change |
| 171 | in success rate to one of them. It accepts a comma-separated list of `evidence`, |
| 172 | `planner`, `subagent`, `retrieval` and `compaction`, plus `none` (the default, |
| 173 | everything on) and `all`. Sub-agents inherit the parent's arm, and the arm name |
| 174 | is written to the `--metrics` file so a recorded run is self-describing. |
| 175 | |
| 176 | ```sh |
| 177 | reasonix run --ablate evidence,planner --metrics run.json "fix the failing test" |
| 178 | ``` |
| 179 | |
| 180 | This is a measurement tool, not a tuning knob: switching a subsystem off makes |
| 181 | Reasonix worse at the work it was added for. |
| 182 | |
| 183 | ### Trajectory recording |
| 184 | |
| 185 | `--trajectory PATH` appends the run's full event stream — tool dispatches and |
| 186 | results with absolute start/end times, reasoning, retries, readiness and |
| 187 | recovery decisions — as one timestamped, sequenced JSONL record per event, so |
| 188 | a run can be replayed and its time attributed offline (tool execution vs. the |
| 189 | model thinking between calls). Records reuse the shared `eventwire` JSON |
| 190 | contract under an `event` key, wrapped in `schema_version`, `seq`, and `ts` |
| 191 | (unix ms). Every completed line survives a killed run. Unlike `--events-jsonl`, |
| 192 | the file contains prompts, tool arguments, and reasoning: treat it with the |
| 193 | same care as a session transcript. |
| 194 | |
| 195 | ```sh |
| 196 | reasonix run --metrics run.json --trajectory run.trajectory.jsonl "fix the failing test" |
| 197 | ``` |
| 198 | |
| 199 | ### Turn phases |
| 200 | |
| 201 | While a turn runs, the host publishes a content-free phase so a frontend can |
| 202 | say what the turn is doing. The CLI shows it on the spinner line; the desktop |
| 203 | app shows it in the composer. |
| 204 | |
| 205 | These phases describe execution timing, not verification evidence. Desktop |
| 206 | check-result cards follow actual running verification tools, not phase names. |
| 207 | |
| 208 | | Phase | Emitted when | `capability_phases` bucket | |
| 209 | | --- | --- | --- | |
| 210 | | `working` | the turn starts, after each tool batch returns, after model generation | `ProviderWaitMs` | |
| 211 | | `checking` | a tool batch is about to execute | `ToolExecMs` | |
| 212 | | `verifying` | an actual verification tool runs | `ToolExecMs` | |
| 213 | |
| 214 | A phase is billed to its bucket when the next phase opens, so the durations in |
| 215 | `--metrics` split a turn into model wait versus tool execution without replaying |
| 216 | the run. Spans under a millisecond are dropped, and a turn that ends through an |
| 217 | error or a pause rather than an answer does not bill its last span, so the |
| 218 | buckets read as a lower bound rather than a full partition of the turn. |
| 219 | |
| 220 | An approval prompt raised inside a tool batch bills to `ToolExecMs`: the batch |
| 221 | stays open from `checking` until the next `working`, and no user-wait phase is |
| 222 | emitted. `ReviewMs`, `SubagentWaitMs`, `UserWaitMs` and `CompactMs` stay zero |
| 223 | because nothing opens those phases inside a turn — `reviewing` is published only |
| 224 | at run exit, after the turn's phase clock has already closed. |
| 225 | |
| 226 | ### Output formats |
| 227 | |
| 228 | | Format | Behavior | |
| 229 | | --- | --- | |
| 230 | | `text` | Human-readable text. With `-p`, prints only the final answer. | |
| 231 | | `json` | Emits one final result object. | |
| 232 | | `stream-json` | Emits one shared `eventwire` JSON object per line, followed by the final result object. | |
| 233 | |
| 234 | ```sh |
| 235 | reasonix -p "list the risky changes" --output-format text |
| 236 | reasonix -p "summarize the diff" --output-format json |
| 237 | reasonix run "run the tests" --output-format stream-json |
| 238 | ``` |
| 239 | |
| 240 | The final structured object has this shape: |
| 241 | |
| 242 | ```json |
| 243 | { |
| 244 | "type": "result", |
| 245 | "subtype": "success", |
| 246 | "is_error": false, |
| 247 | "duration_ms": 123, |
| 248 | "num_turns": 1, |
| 249 | "result": "...", |
| 250 | "result_from_reasoning": false, |
| 251 | "session_id": "...", |
| 252 | "total_cost": 0, |
| 253 | "currency": "USD", |
| 254 | "total_cost_usd": 0, |
| 255 | "usage": { |
| 256 | "input_tokens": 0, |
| 257 | "output_tokens": 0, |
| 258 | "cache_read_input_tokens": 0, |
| 259 | "cache_creation_input_tokens": 0 |
| 260 | } |
| 261 | } |
| 262 | ``` |
| 263 | |
| 264 | `result_from_reasoning` is present, and `true`, when the turn finished with an |
| 265 | empty visible message and `result` therefore carries the turn's reasoning |
| 266 | instead. A thinking model may answer entirely in the reasoning channel; without |
| 267 | the field a caller cannot tell that text apart from a visible answer, and |
| 268 | without the fallback `result` would be `""` and `-p` would print nothing. It is |
| 269 | omitted whenever the model emitted visible text, which is the ordinary case. |
| 270 | |
| 271 | `total_cost` is present only when a single `selected` display amount exists (ISO |
| 272 | code in `currency`). Prefer the structured `cost_quote` field when present: it |
| 273 | carries the original estimate, `original_totals`, occurrence-time valuations |
| 274 | (`official_table` for dual-region public prices), `cost_complete`, |
| 275 | `display_complete`, `display_status`, and `billing_mode` (`payg` or `subscription_equivalent` for |
| 276 | pay-as-you-go equivalent estimates such as MiMo Token Plan). |
| 277 | |
| 278 | `total_cost_usd` remains a numeric compatibility alias when `total_cost` exists |
| 279 | and does **not** imply USD. Mixed original currencies no longer fail the run: |
| 280 | `cost_complete` remains true when usage/pricing facts are known, |
| 281 | `display_complete` is false, and `original_costs`/`original_totals` list per-ISO |
| 282 | totals so clients never invent a cross-currency sum. |
| 283 | |
| 284 | Global display preference is `[billing].display_currency` (`auto|CNY|USD`); |
| 285 | legacy `[desktop].currency` still migrates. Provider list prices use each |
| 286 | entry's frozen `billing_currency` and are never rewritten by display switches. |
| 287 | Diagnose with `reasonix doctor billing`. |
| 288 | |
| 289 | Execution failures use `subtype: "error_during_execution"` and |
| 290 | `is_error: true`. Structured modes keep runtime errors in JSON instead of also |
| 291 | printing a duplicate human-readable error. Authentication failures also include |
| 292 | optional `error_code`, `authentication_status`, and `recovery_actions` fields. |
| 293 | The same fields appear on the final `run_done` record from `--events-jsonl`. |
| 294 | For example, a missing key reports `missing_credential` and actions such as |
| 295 | `configure_credentials`, `select_model`, and `diagnose_credentials`; no model |
| 296 | request is made. |
| 297 | |
| 298 | The completion validator has been removed. A clean model stop without tool |
| 299 | calls ends the turn directly; a response with tools continues through the tool |
| 300 | loop, and a truly empty response is retried at the frozen-request boundary. |
| 301 | Legacy `completion_validation`, `completion_evaluator_model`, and |
| 302 | `REASONIX_COMPLETION_VALIDATION_MODE` settings remain readable but are ignored |
| 303 | and are no longer emitted by the config renderer. Explicit budgets, tool-safety and protocol recovery boundaries remain active. |
| 304 | Goal completion is a model declaration; no host quality gate or independent |
| 305 | Goal evaluator runs. See [migration details](EXECUTION_MODEL_SIMPLIFICATION.md). |
| 306 | |
| 307 | ### Redacted machine interfaces |
| 308 | |
| 309 | Use the dedicated event flag when an automation needs lifecycle telemetry but |
| 310 | must not receive prompts, reasoning, tool arguments, tool output, or approval |
| 311 | text: |
| 312 | |
| 313 | ```sh |
| 314 | reasonix run --events-jsonl "run the focused tests" |
| 315 | ``` |
| 316 | |
| 317 | Every line has `schema_version`, `sequence`, and `kind`; the final line is |
| 318 | `kind: "run_done"`. `--events-jsonl` is intentionally separate from the richer |
| 319 | `--output-format stream-json` contract and cannot be combined with |
| 320 | `--output-format`. |
| 321 | |
| 322 | The following read-only commands expose persisted state without transcript, |
| 323 | label, command, output, path, PID, or host-name content. Here, read-only means |
| 324 | the commands do not mutate transcript, runtime, recovery, or query state. The |
| 325 | first redacted-machine invocation may initialize a private identity key in the |
| 326 | Reasonix user-state directory: |
| 327 | |
| 328 | ```sh |
| 329 | reasonix session list --json [--dir SESSION_DIR | --project-root PATH] |
| 330 | reasonix session show <machine-session-id> --json [--dir SESSION_DIR | --project-root PATH] |
| 331 | reasonix session status <machine-session-id> --json [--dir SESSION_DIR | --project-root PATH] |
| 332 | reasonix session recovery [<machine-session-id>] --json [--dir SESSION_DIR | --project-root PATH] |
| 333 | reasonix task list --json [--dir SESSION_DIR | --project-root PATH] [--session MACHINE_SESSION_ID] |
| 334 | reasonix task show <task-id> --json [--dir SESSION_DIR | --project-root PATH] [--session MACHINE_SESSION_ID] |
| 335 | reasonix task monitor list --json [--dir PROJECT_DIR] |
| 336 | reasonix task monitor status <task-id> --json [--dir PROJECT_DIR] |
| 337 | reasonix task monitor events <task-id> --json|--jsonl [--dir PROJECT_DIR] [--after N] [--follow] |
| 338 | reasonix hook list --json [--project-root PATH] [--home-dir PATH] |
| 339 | reasonix hook status --json [--project-root PATH] [--home-dir PATH] |
| 340 | ``` |
| 341 | |
| 342 | For `session` and `task`, `--dir` explicitly selects the session storage |
| 343 | directory, while `--project-root` resolves the selected project's session |
| 344 | store. The two options cannot be combined. Without either option, Reasonix |
| 345 | selects the current project's session store. |
| 346 | For `hook`, `--dir` is an alias for `--project-root`. |
| 347 | `hook list` reports `active` or `invalid`; `invalid` means the |
| 348 | configured event cannot execute because its event, command/context source, or |
| 349 | tool-event matcher is unusable. Matchers on non-tool events are ignored. |
| 350 | |
| 351 | Machine session IDs are keyed opaque hashes, not transcript file names. They |
| 352 | remain stable for the same session and Reasonix user-state directory, while a |
| 353 | different installation key produces unrelated IDs and prevents offline guesses |
| 354 | from timestamps or model labels. Preserve the private identity key when moving |
| 355 | the Reasonix state directory if automation depends on existing machine IDs. |
| 356 | Task `finished_at` is empty while a task is running, and |
| 357 | `artifact_complete=true` is emitted only for a terminal task whose persisted |
| 358 | artifact exists. A `running` record without a live session lease is reported as |
| 359 | `interrupted`; opening that session also repairs the persisted lifecycle state. |
| 360 | |
| 361 | Schema compatibility rules for version 1: |
| 362 | |
| 363 | - consumers must ignore unknown fields; |
| 364 | - fields are not removed or retyped within the same schema version; |
| 365 | - empty collections are encoded as `[]`; |
| 366 | - argument errors exit with status `2`, state/query errors with status `1`; |
| 367 | - machine-command errors are JSON objects with a stable `error.code`. |
| 368 | |
| 369 | ## Resume sessions |
| 370 | |
| 371 | ```sh |
| 372 | reasonix --continue |
| 373 | reasonix --resume |
| 374 | reasonix --resume provider-config |
| 375 | reasonix --resume <session-id> |
| 376 | reasonix --resume provider-config --copy |
| 377 | ``` |
| 378 | |
| 379 | - `--continue` resumes the newest saved session immediately. |
| 380 | - Bare `--resume` opens the searchable picker in an interactive terminal. |
| 381 | - `--resume QUERY` accepts an exact session ID or path, or a unique title or |
| 382 | preview substring. Missing and ambiguous matches fail with a descriptive |
| 383 | error. |
| 384 | - `--resume=true` and `--resume=false` remain accepted for compatibility. |
| 385 | - `--copy` leaves the original transcript untouched and continues in a new |
| 386 | writable session. Use it when another Reasonix process owns the original. |
| 387 | |
| 388 | For one-shot runs, `reasonix run --resume QUERY "task"` accepts a session file |
| 389 | path, a session ID, or an opaque machine session ID from `--events-jsonl` / |
| 390 | `reasonix session show --json`. Session leases prevent the desktop app and CLI |
| 391 | from writing the same transcript concurrently. |
| 392 | |
| 393 | ## Permissions |
| 394 | |
| 395 | ```sh |
| 396 | reasonix --permission-mode read-only |
| 397 | reasonix --permission-mode workspace-write |
| 398 | reasonix --permission-mode danger-full-access |
| 399 | reasonix -p "run the focused tests" --allowed-tools "Bash(go test ./...)" |
| 400 | ``` |
| 401 | |
| 402 | | Preset | Behavior | |
| 403 | | --- | --- | |
| 404 | | `read-only` | Read the workspace; writes and external side effects require a scoped authorization. | |
| 405 | | `workspace-write` | Write inside the workspace and private session temporary directory. This is the default. | |
| 406 | | `danger-full-access` | Run as the current OS user without Reasonix filesystem or network sandboxing. Explicit host deny rules still apply before launch. | |
| 407 | |
| 408 | Inline scripts, pipes, substitutions, and shell `-c` forms follow the same |
| 409 | preset and sandbox boundary as other commands. Syntax alone never creates an |
| 410 | approval request. |
| 411 | |
| 412 | `--allowed-tools` is a session permission override, not a provider tool-schema |
| 413 | filter. Rules may be comma- or space-separated, and the flag is repeatable. |
| 414 | Configured deny rules always win over command-line allow rules. |
| 415 | |
| 416 | In non-interactive runs (`reasonix run` / `-p`) there is no prompt to answer. |
| 417 | `read-only` therefore fails closed for writes and side effects unless a narrow |
| 418 | authorization was supplied at startup. `workspace-write` runs normal builds, |
| 419 | tests, pipes, and inline scripts inside the OS sandbox. `danger-full-access` |
| 420 | must be explicit and still cannot bypass configured deny rules. |
| 421 | |
| 422 | ## Additional directories |
| 423 | |
| 424 | ```sh |
| 425 | reasonix --add-dir ../shared |
| 426 | reasonix -p "update both projects" \ |
| 427 | --add-dir ../frontend \ |
| 428 | --add-dir ../backend |
| 429 | ``` |
| 430 | |
| 431 | Relative paths resolve from the workspace root and must already exist as |
| 432 | directories. Reasonix resolves symlinks, removes duplicates, and extends the |
| 433 | file-writer and sandboxed Bash write boundaries for the session. These additions |
| 434 | are runtime-only and are not written to configuration. |
| 435 | |
| 436 | ## Interactive controls |
| 437 | |
| 438 | The `/model`, `/provider`, and `/resume` commands use searchable pickers. |
| 439 | Approval prompts use the same row-selection behavior while retaining their |
| 440 | single-key shortcuts. |
| 441 | |
| 442 | | Key | Action | |
| 443 | | --- | --- | |
| 444 | | `Up` / `Down`, `Ctrl+P` / `Ctrl+N` | Move through picker or approval rows. | |
| 445 | | `j` / `k` | Move while the search is empty; after search input starts, enter `j` / `k` as query text. | |
| 446 | | Type | Filter a searchable picker. | |
| 447 | | `Enter` | Select the highlighted row. | |
| 448 | | `Esc` | Cancel the current picker or approval. | |
| 449 | | `y` / `a` / `n`, number keys | Allow once, allow the displayed scope for this session, or deny. | |
| 450 | | `Shift+Tab` | Cycle Read only → Workspace write → YOLO → Plan. | |
| 451 | | `Ctrl+Y` | Toggle YOLO; the runtime permission preset is `danger-full-access`. | |
| 452 | |
| 453 | The responsive footer keeps interaction state on the left and, when space |
| 454 | allows, places model and effort on the right. Its second row shows |
| 455 | available repository and session telemetry such as cache hit rate, context use, |
| 456 | compaction headroom, background jobs, and balance. `ready` means the composer is |
| 457 | idle; that slot changes when a picker, approval, image paste, shell mode, or |
| 458 | other interaction needs attention. Narrow terminals move or compact complete |
| 459 | groups instead of cutting labels in half. Visible labels follow `/language`. |
| 460 | |
| 461 | Use `/theme auto|light|dark` to select the terminal background mode, or choose a |
| 462 | named accent from `/theme`. Both composer borders, the insertion cursor, |
| 463 | selection, scrollbar, and footer use the active CLI theme. See |
| 464 | [Keyboard shortcuts](./GUIDE.md#keyboard-shortcuts) for transcript navigation, |
| 465 | multiline input, rewind, and clipboard controls. |
| 466 | |
| 467 | Clipboard actions are deliberately split by content type. Local transcript |
| 468 | and composer selections use the native system clipboard and report success only |
| 469 | after that write completes; SSH falls back to an explicitly labelled OSC 52 |
| 470 | request. Text paste remains the terminal's bracketed-paste action (`Cmd+V` on |
| 471 | macOS and the terminal's configured shortcut elsewhere). While Reasonix owns the |
| 472 | mouse in a local session, right-click with no selection reads clipboard text |
| 473 | through the same paste path; right-click with a selection copies it. Over SSH, |
| 474 | use the terminal paste shortcut because the remote process cannot read the local |
| 475 | clipboard; `/mouse` restores the terminal's native right-click menu. Image paste |
| 476 | is application-owned: use `Ctrl+V` on macOS/Linux, `Alt+V` on Windows, or |
| 477 | `/paste-image`; the footer shows `Pasting image…` until the attachment token is |
| 478 | ready. Where the terminal forwards that shortcut instead of pasting itself, a |
| 479 | clipboard holding no image falls back to a text paste, so the key never swallows |
| 480 | plain text. |
| 481 | |
| 482 | ## In-session commands |
| 483 | |
| 484 | Type `/help` in an interactive session for the complete command list. Slash |
| 485 | completion, help, dispatch, and aliases are generated from the same registry, so |
| 486 | the displayed list matches the commands the TUI accepts. |
| 487 | |
| 488 | | Command | Purpose | |
| 489 | | --- | --- | |
| 490 | | `/continue-checks [guidance]` | Resume the immediately preceding paused task-completion check while preserving its verified tool evidence. The command is one-shot and refuses stale cards after another user turn. | |
| 491 | | `/model` | Search configured models and switch the active model. | |
| 492 | | `/provider` | Choose a provider, then choose one of its configured models. | |
| 493 | | `/resume` | Search recent sessions and switch to one. | |
| 494 | | `/takeover` | Take over the last refused session (or a listed entry) from the resident serve: this CLI becomes the writer and remote viewers become read-only spectators until they reclaim. After a desktop reclaim it re-takes the remembered session directly; a session no runtime holds any more is simply resumed. | |
| 495 | | `/status` | Show model, effort, cache, Git, background jobs, and balance details. | |
| 496 | | `/theme [auto\|light\|dark\|style]` | View or change the CLI background mode and accent palette. | |
| 497 | | `/currency [auto\|CNY\|USD]` | View or change the user-global fee display currency and refresh the runtime. | |
| 498 | | `/paste-image` | Read a clipboard image and insert an editable attachment token. | |
| 499 | | `/mouse` | Toggle in-app mouse selection, scrollbar, and wheel handling; SSH sessions start with capture off so the terminal's native selection works. | |
| 500 | | `/effort` | View or change reasoning effort. | |
| 501 | | `/output-style` | Select an answer style. | |
| 502 | | `/verbose` | Toggle expanded reasoning display. | |
| 503 | | `/sandbox` | Inspect sandbox status. | |
| 504 | | `/goal [objective]` | Start a continuous goal, or inspect its runtime statistics. | |
| 505 | | `/goal status` | Show the active goal plus turns, requests, tokens, work time, and the last continuation reason. | |
| 506 | | `/goal pause` | Pause the running goal (keeps todos, Delivery checkpoint, and runtime history). | |
| 507 | | `/goal resume` | Resume a manually paused or genuinely blocked goal without changing a numeric quota. | |
| 508 | | `/goal clear` | End goal mode permanently. | |
| 509 | | `/docs [question]` | Show the embedded corpus identity, or search it locally and ask the configured AI to answer from version-matched evidence. | |
| 510 | | `/reasonix:docs [question]` | Preferred built-in fallback when an existing custom command or compatible plugin/skill alias owns `/docs`; if this spelling is also owned, the menu selects the next free `reasonix:`-qualified name without displacing it. | |
| 511 | | `/mcp`, `/skills`, `/hooks` | Inspect and manage extensions. | |
| 512 | | `/remember <note>` | Append a standing note to the project instruction document; `# <note>` is a shortcut. | |
| 513 | | `/memory [subcommand]` | Inspect instructions, memory provenance, recall, revisions, and recovery. | |
| 514 | | `/rewind` | Restore conversation and/or code to an earlier turn. | |
| 515 | | `/tree`, `/branch`, `/switch` | Inspect or navigate conversation branches. | |
| 516 | | `/reload` | Reload the agent runtime (extensions, tools, skills, commands, hooks, providers) while keeping the session. Queued once while a turn runs, then fail-atomic: a failed rebuild keeps the current runtime. | |
| 517 | |
| 518 | Switching model or effort rebuilds the runtime while preserving the |
| 519 | active conversation, session-scoped permission overrides, additional directory |
| 520 | access, and session ownership. `/reload` uses the same fail-atomic rebuild. |
| 521 | Execution modes no longer exist: planning, verification, and review strength |
| 522 | follow task risk per turn. |
| 523 | |
| 524 | `/preset`, `/work-mode`, and `/profile` remain hidden compatibility commands. |
| 525 | Recognized legacy values are accepted, report that the setting is retired, and |
| 526 | leave the session on standard execution; unknown values still return an error. |
| 527 | |
| 528 | ## Session catalog diagnostics |
| 529 | |
| 530 | The desktop session catalog is a disposable SQLite query projection; transcript |
| 531 | JSONL and sidecars remain authoritative. Inspect it read-only or replace only |
| 532 | the projection: |
| 533 | |
| 534 | ```sh |
| 535 | reasonix doctor sessions [--json] |
| 536 | reasonix sessions reindex [--json] |
| 537 | reasonix sessions reindex --dir /path/to/sessions --dir /another/path |
| 538 | ``` |
| 539 | |
| 540 | Without `--dir`, reindex includes global sessions and all projects saved by the |
| 541 | desktop app. See [Session Catalog and Desktop Startup](./SESSION_CATALOG.md) for |
| 542 | failure, migration, and data-safety guarantees. |
| 543 | |
| 544 | History search uses a separate disposable projection: |
| 545 | |
| 546 | ```sh |
| 547 | reasonix doctor catalogs [--json] |
| 548 | reasonix catalogs reindex history [--dir PATH ...] [--json] |
| 549 | ``` |
| 550 | |
| 551 | See [History Search Catalog](./HISTORY_SEARCH_CATALOG.md). |
| 552 | Usage statistics use a separate disposable rollup projection: |
| 553 | reasonix catalogs reindex usage [--json] |
| 554 | See [Usage Catalog](./USAGE_CATALOG.md). |
| 555 | |
| 556 | Inspect or rebuild the disposable task projection independently: |
| 557 | |
| 558 | ```sh |
| 559 | reasonix doctor catalogs [--json] |
| 560 | reasonix catalogs reindex tasks [--project PATH ...] [--json] |
| 561 | ``` |
| 562 | |
| 563 | See [Task Catalog](./TASK_CATALOG.md) for the authoritative FileStore boundary, |
| 564 | cross-project routing, and rebuild behavior. |
| 565 | |
| 566 | ### Memory diagnostics and recovery |
| 567 | |
| 568 | Bare `/memory` shows all active project/global facts without hiding same-name |
| 569 | entries. Facts include their stable ID, revision, scope, type, freshness, and |
| 570 | description. Slash completion offers the available subcommands, active IDs and |
| 571 | names, and owned archive paths. |
| 572 | |
| 573 | | Command | Purpose | |
| 574 | | --- | --- | |
| 575 | | `/memory instructions` | Show resolved instruction precedence, directories, imports, and diagnostics. | |
| 576 | | `/memory recall` | Explain the latest automatic recall query, hits, scores, reasons, freshness, and budget. | |
| 577 | | `/memory revisions <id-or-name>` | Show the active revision and immutable history. | |
| 578 | | `/memory restore <id-or-name> <revision>` | Restore old content as a new monotonic revision. | |
| 579 | | `/memory archived` | List archived facts and their owned paths. | |
| 580 | | `/memory recover <archive-path>` | Recover an archive as a new revision without overwriting active data. | |
| 581 | |
| 582 | These commands run against the active session controller. When the session |
| 583 | lives on a remote host (`reasonix remote connect` / a desktop remote web |
| 584 | window), they use the remote memory catalog and never fall back to local |
| 585 | desktop memory. See [Context Engine v2](./SESSION_MEMORY_RETRIEVAL.md) for |
| 586 | authority, automatic recall, write confirmation, and migration behavior. |
| 587 |