> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matterai.so/llms.txt
> Use this file to discover all available pages before exploring further.

# OrbCode CLI Usage

> Slash commands, keyboard shortcuts, approvals, headless mode, and the TUI

# Usage

The directory you launch OrbCode from becomes the **workspace directory**: the default target for file operations and commands, and the file listing the model sees in its environment details.

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/orbcode-cli/configuration">
    settings.json, env vars, custom models, sessions
  </Card>

  <Card title="MCP servers" icon="plug" href="/orbcode-cli/mcp">
    Connect external tools through the Model Context Protocol
  </Card>

  <Card title="Skills & memory" icon="book" href="/orbcode-cli/skills">
    Reusable instruction sets and AGENTS.md project memory
  </Card>

  <Card title="Hooks" icon="link" href="/orbcode-cli/hooks">
    Block, auto-approve, rewrite, or inject context
  </Card>
</CardGroup>

## CLI reference (entry point)

```
orbcode                       start an interactive session in the current directory
orbcode "<prompt>"            start an interactive session with an initial prompt
orbcode login                 sign in to MatterAI (browser device flow)
orbcode logout                remove the saved token (alias: `/logout`)
orbcode -p "<prompt>"         run a single prompt non-interactively
orbcode -p "…" --yolo         non-interactive with edits/commands auto-approved
orbcode --model <id>          use a specific model for this run (also -m)
orbcode --resume <id>         resume a previous session by id (also -r)
orbcode --version             print version
orbcode --help                show help
```

### Flags

| flag                   | effect                                                                          |
| ---------------------- | ------------------------------------------------------------------------------- |
| `-p "<prompt>"`        | run a single prompt non-interactively, print only the final response            |
| `--yolo`               | non-interactive with edits/commands auto-approved (dangerous ones still prompt) |
| `--model <id>` / `-m`  | use a specific model for this run                                               |
| `--resume <id>` / `-r` | resume a previous session by id                                                 |
| `--version`            | print version                                                                   |
| `--help`               | show help                                                                       |

The TUI always takes over the full terminal screen on launch (prior shell output stays in scrollback). OrbCode needs a real TTY (raw mode) and won't accept piped stdin in interactive mode — use `-p` for non-interactive runs.

## Slash commands

Slash commands are entered at the input prompt (start with `/`). Most have aliases or fuzzy matching: typing `/mod` + `enter` runs the highlighted match.

| command         | action                                                                                                |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| `/help`         | list commands                                                                                         |
| `/model`        | scrollable model picker (`/model pro` / `/model mini` / full id selects directly)                     |
| `/clear`        | clear the screen only, like the terminal's `clear` — the conversation and context continue            |
| `/new`          | start a fresh conversation/session with a clean slate                                                 |
| `/resume`       | pick a previous session for this directory and continue it (screen is cleared, conversation replayed) |
| `/analytics`    | open the MatterAI analytics dashboard (`app.matterai.so/orbital`) in the browser                      |
| `/compact`      | summarize the conversation and replace history with the summary                                       |
| `/tasks`        | print the current task list                                                                           |
| `/status`       | version, model, account, gateway, context usage, cost, approval modes                                 |
| `/usage`        | fetch plan usage from `/axoncode/profile` (plan, tiered windows, reset date)                          |
| `/init`         | analyze the codebase and write a concise `.orb/AGENTS.md` for cold-start                              |
| `/link`         | manage linked repositories (other repos checked for impact on this one)                               |
| `/migrate`      | import MCP server configs from Claude Code / Claude Desktop                                           |
| `/mcp`          | manage MCP servers — enable, disable, reconnect, view status & tool counts                            |
| `/plugins`      | browse the plugin marketplace and manage installed plugins (alias: `/plugin`, `/skills`)              |
| `/create-skill` | create a repo-local skill under `.orb/skills/` from a plain-language description                      |
| `/weekly-reset` | reset your weekly usage tier (Pro+, once per monthly billing cycle)                                   |
| `/commit`       | check pending changes and create detailed commits                                                     |
| `/code-review`  | expert review of pending changes: performance, security, bugs, tests                                  |
| `/login`        | start the browser sign-in flow                                                                        |
| `/logout`       | remove the saved token                                                                                |
| `/version`      | print the CLI version                                                                                 |
| `/exit`         | quit (alias: `Ctrl+C`)                                                                                |

Every menu in the CLI (slash commands, `@`-files, model picker, session picker, followups) is navigable with `↑`/`↓` and selectable with `enter`.

## Keyboard shortcuts

| key                 | action                                                                 |
| ------------------- | ---------------------------------------------------------------------- |
| `Esc`               | interrupt the running turn (or cancel login polling / close a menu)    |
| `Ctrl+C`            | quit                                                                   |
| `Ctrl+O`            | toggle thinking display for the whole transcript (past turns included) |
| `Shift+Tab`         | cycle approval mode: ask → accept edits → auto-approve                 |
| `↑` / `↓`           | input history, or navigate any open menu                               |
| `←` / `→`           | move the cursor in the input                                           |
| `Ctrl+A` / `Ctrl+E` | start / end of line                                                    |
| `Ctrl+U`            | clear the input line                                                   |
| `@`                 | open the file-fuzzy-search menu                                        |
| `enter`             | submit the prompt / select a menu item                                 |
| `tab`               | insert the highlighted `@`-match into the prompt                       |

A trailing newline in a paste submits; multi-line pastes are sent as one input.

## Input affordances

* **`@-references`** — type `@` in the input to fuzzy-search workspace files. `↑`/`↓` to choose, `enter`/`tab` inserts the top/selected match into the prompt.
* **Multi-char paste** — pasting multiple lines puts them all in the input; a trailing newline submits.
* **Slash autocomplete** — a menu appears whenever the line starts with `/`, narrowable by typing more characters.
* **History** — `↑`/`↓` walks the per-session history (across sessions, persisted in the session file).

## Approvals & safety

Read-only tools (`read_file` / `list_files` / `search_files` / `web_*` / `update_todo_list`) run without prompting. Mutating tools prompt first:

* **File edits** (`file_edit`, `multi_file_edit`, `file_write`) — prompt shows the target and a diff; `y` allow once, `n` deny, `a` allow for the rest of the session.
* **Commands** (`execute_command`) — prompt shows the exact command line. The model classifies commands with an `isDangerous` flag; dangerous commands (deletes, force-pushes, system changes) can **never** be auto-approved — no `a` option, and `--yolo` / session-approval don't apply.

A denial is reported back to the model as "The user denied this operation." so it can adjust course rather than fail.

<Note>
  Use `Shift+Tab` at runtime to cycle the approval mode: **ask** → **accept
  edits on** → **auto-approve**. The session defaults can also be set in
  `settings.json` via `autoApproveEdits` and `autoApproveSafeCommands`
  (dangerous commands still always prompt).
</Note>

Hooks can override any of this — see [Hooks: PreToolUse](/orbcode-cli/hooks#pretooluse) for `permissionDecision: allow | deny | ask` and `updatedInput`.

## Headless mode

```bash theme={null}
orbcode -p "explain the build pipeline in this repo"
orbcode -p "fix the lint errors" --yolo
```

* Prints **only the final content** to stdout (the completion result, or the last assistant message) — no tool activity, no intermediate text.
* Errors go to stderr.
* Without `--yolo`, edit/command approvals are auto-denied (read-only analysis).
* Followup questions are auto-answered with "proceed with best judgment".
* Project hooks still run, but untrusted project hooks are skipped (set `MATTERAI_TRUST_PROJECT_HOOKS=1` to auto-trust them).

## The TUI

* **Streaming responses** rendered as markdown (headers, lists, code fences, inline code, links) via a lightweight ANSI renderer.
* **Thinking** — reasoning streams live under `✦ Thinking…` and collapses to `✦ Thought for Ns` when done. `Ctrl+O` toggles expanded thinking.
* **Tool rows** — each tool call shows a formatted name, a one-line summary, live "running" state, then `✓`/`✗` with a short result preview.
* **Edit diffs** — file-modifying tools render a real diff with a stats header and red/green backgrounds, both in the approval prompt and the finished tool row.
* **Tasks** — the model maintains a checklist via `update_todo_list`, rendered as a compact Tasks panel.
* **@-references** — type `@` in the input to fuzzy-search workspace files.
* **Status bar** — approval mode, busy state, model name, context token usage, and session cost.
* **Spinner tips** — after an operation runs for 2s, a random slash-command tip appears under the `Thinking` / `Working` spinner.
* **Figma auto-fetch** — paste a `figma.com` URL into a prompt and the agent pre-fetches the design's node tree, components, styles, and rendered images before the first completion, so it has visual + structural context from step 0.
* **Completion card** — `attempt_completion` renders a bordered "✔ Task completed" card with the result.

## MCP servers

OrbCode connects to external tools via the **Model Context Protocol** (MCP). MCP servers expose tools that appear alongside the native tools as `mcp__<server>__<tool>` and can be called by the model like any other tool.

The `/mcp` command opens an interactive manager at any time: ↑/↓ to select a server, **enter** or **2** to toggle enable/disable, **r** or **3** to reconnect, **a** or **1** to authenticate a `needs-auth` OAuth server, **esc** to close. Each server shows a live status icon (`✓ connected`, `△ needs-auth`, `✗ failed`, `○ disabled`, `⋯ connecting`) plus a tool count when connected.

You can also manage servers from the command line with `orbcode mcp add/remove/list`. See the [MCP servers page](/orbcode-cli/mcp) for the three configuration scopes, server types, and OAuth options.

## Skills

Skills are reusable instruction sets the model can load on demand. A skill is a directory containing a `SKILL.md` file with optional YAML frontmatter and a markdown body of specialized instructions.

Place a directory under `~/.orbcode/skills/` (user, applies everywhere) or `.orbcode/skills/` (project, checked into the repo). The skill catalog (names + descriptions + when-to-use) is injected into the system prompt; when a task matches a skill's `when_to_use` condition, the model calls the `use_skill` tool to load the full instructions into context. Project skills override user skills on name collisions. See the [Skills & memory page](/orbcode-cli/skills) for the full reference.

## AGENTS.md memory

AGENTS.md files provide project- and user-level instructions that are injected into every system prompt — build commands, code style, architecture notes, conventions. This is OrbCode's equivalent of Claude Code's `CLAUDE.md`, using the open `AGENTS.md` filename so it works across tools.

Files are loaded in this order (lowest precedence first): user memory (`~/.orbcode/AGENTS.md`), project memory (`AGENTS.md` and `.orb/AGENTS.md` in the cwd and parents), and local memory (`AGENTS.local.md`, private per-machine). Use `/init` to have OrbCode generate or refine a starter `AGENTS.md` by analyzing the codebase. See the [Skills & memory page](/orbcode-cli/skills) for the discovery order and `@include` directives.

## `/init` — generate `.orb/AGENTS.md`

`/init` investigates the project (layout, key config files, a few representative sources) and writes a concise **`.orb/AGENTS.md`** at the repo root, capped at \~150 lines so it stays cheap to include in every future prompt. The generated file covers:

1. What the project does (1-2 lines) and its main tech stack.
2. Project structure — the key directories/files and what each is responsible for.
3. Architecture — how the main pieces fit together (entry points, data/control flow).
4. Business-logic mapping — the rules and invariants the model needs to honor.
5. Code patterns and conventions — the idioms the codebase already uses.

The prompt also tells the agent to **refine an existing `AGENTS.md`** rather than overwriting it, and to fold in any existing AI assistant rules (`CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`).

The `.orb/` folder is shared with the [Orbital IDE extension](/changelog/orbital-changelog) — the same `AGENTS.md` is read by both, so a single source of truth covers your terminal and your editor.

## `/link` — linked repositories

`/link` opens an interactive manager for **linked repositories**: other repos on your machine whose `AGENTS.md` should be considered when you're working in this one, so a change here is checked for impact on (or propagated to) them.

Each link is just a folder path — absolute, `~/path`, or relative to the project. Links are persisted per-project in **`.orb/links.json`** in the current repo:

```json theme={null}
{
  "links": [
    { "path": "/Users/me/projects/shared-lib" },
    { "path": "~/projects/design-system" }
  ]
}
```

At session start, OrbCode walks the links, reads each linked repo's `AGENTS.md` (from `.orb/`, `.orbital/`, or `.orbcode/`), and pulls them in **ahead of time** into the agent's environment details — the model sees them as part of the workspace before it starts working.

`.orb/links.json` is **shared with the Orbital IDE extension** — links written by the IDE are honored by the CLI and vice versa, so the two tools stay in sync without a manual merge. Use `/link` (or the IDE's `/link`) to add or remove entries interactively.

## Tools

Active in the CLI (schemas byte-identical to the extension's native tools):

| tool                       | executor notes                                                                                                               |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `read_file`                | line-numbered output, 1000-line cap, offset/limit                                                                            |
| `file_edit`                | single replacement; unique-match enforcement; `replace_all`; empty `old_string` = whole file                                 |
| `multi_file_edit`          | batched edits grouped per file, per-edit OK/FAILED results                                                                   |
| `file_write`               | creates parent dirs, full-content writes                                                                                     |
| `list_files`               | optional recursive, ignores `node_modules`/`.git`/`build` dirs, 800-entry cap                                                |
| `search_files`             | regex search with glob `file_pattern`, 300-match cap, binary skip                                                            |
| `execute_command`          | user's shell, 120s timeout, 30k output cap, optional cwd                                                                     |
| `web_search` / `web_fetch` | proxied through the MatterAI backend with your token                                                                         |
| `update_todo_list`         | drives the TUI todo panel                                                                                                    |
| `use_skill`                | loads a skill's full instructions by name or by an explicit skill directory / `SKILL.md` path                                |
| `figma_fetch`              | fetches a Figma design's node tree, components, styles, and rendered image URLs (authenticated through the MatterAI backend) |
| `ask_followup_question`    | interactive menu in the TUI                                                                                                  |
| `attempt_completion`       | ends the turn with a completion card                                                                                         |
| `mcp__<server>__<tool>`    | any tool exposed by a connected MCP server (see [MCP servers](#mcp-servers))                                                 |

For hook matchers, use these tool names verbatim (e.g. `"execute_command"`, `"file_edit|file_write|multi_file_edit"`).

## Sessions

* Stored in `~/.orbcode/sessions/<id>.json`.
* Power `/resume` (in-session picker) and `--resume <id>` / `-r` (from the CLI).
* Record the conversation, tool results, task title, and cost.
* The backend-generated task title is fetched once per task and shows in the status bar, the session file, and the terminal window title (`<title> (orbcode)`).

## Troubleshooting

| Problem                     | Fix                                                                                                                          |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Keyboard input does nothing | OrbCode needs a real TTY (raw mode); use `-p` for non-interactive runs.                                                      |
| `Esc` doesn't stop a turn   | `Esc` interrupts the in-flight request via `AbortController`; one turn may still complete and surface a `<system_reminder>`. |
| Slash command doesn't run   | Make sure the line starts with `/`; partial matches (e.g. `/mod`) run the highlighted match — press `enter`.                 |
| `-p` returns empty          | Without `--yolo`, approvals are auto-denied; with `--yolo`, the final response is whatever the last assistant turn produced. |
| Sessions list is empty      | `/resume` only shows sessions whose working directory matches the current one.                                               |