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

# Mirror CLI reference

> Commands, shortcuts, sessions, worktrees, and configuration for Mirror CLI

Mirror CLI is Reflection's coding agent for the terminal. Ask it to explore a codebase, edit files, or run commands and tests. Each workspace has its own conversation and agent.

For installation and a first coding task, start with the [coding agent quickstart](/coding-agents-quickstart#mirror). This page covers the interactive CLI and its settings.

<Note>
  Mirror CLI is in early beta. Commands and behavior may change as we fix bugs and polish the release. Run `/help` to see the commands available in your installation, including those added by enabled extensions.
</Note>

## Start Mirror CLI

Start it from the directory where you want to work:

```bash theme={null}
cd /path/to/project
mirror
```

The first time, Mirror shows a **Using Mirror** notice. In each new directory, it asks `Continue and trust this folder? [y/N]` before it starts; type `y` and press `Enter` to continue.

A fresh installation uses Reflection and `Beam-501B-A23B`. If you previously selected another provider or model, run `/model reflection` after Mirror starts; Mirror remembers the selection. To use Reflection for one launch without changing the saved selection:

```bash theme={null}
mirror --api reflection --model Beam-501B-A23B
```

Mirror uses a Reflection API key in this order:

1. `--api-key`, if provided. Prefer the environment variable to keep the key out of shell history.
2. `REFLECTION_API_KEY` in your environment.
3. A saved key in `~/.mirror/reflection_api_key`.
4. The **Connect to Reflection** prompt, if no key is available. Input is masked with one `*` per character, and Mirror saves the key for later sessions without checking it.

`/logout` removes the saved key and, if `REFLECTION_API_KEY` isn't set, reopens the **Connect to Reflection** prompt so you can replace a wrong key. It doesn't affect `REFLECTION_API_KEY`.

See [API-key setup](/coding-agents-quickstart#mirror).

* Run `mirror --help` for launch options.
* Enter your task after Mirror starts. The interactive CLI does not accept a prompt as a positional argument.

## Send prompts and interrupt turns

| Action | How |
| - | - |
| Send a prompt | Press `Enter`. |
| Insert a newline | Use `Ctrl+J`. `Shift+Enter` and `Ctrl+Enter` also work in terminals that support their extended key sequences. |
| Send another instruction during a turn | Type and submit it while the agent works. Pending instructions appear in the input area. |
| Interrupt a turn | Press `Escape` to stop the active turn and stay in the session. If a menu is open, `Escape` closes it first. At a tool-approval prompt, `Escape` interrupts the whole turn, not just the prompt. |
| Read tool calls and file edits | Look in the transcript. |
| Change transcript detail | Use `/view` or `Ctrl+T` to cycle through `transcript`, `compact`, and `extra-compact`. |
| Clear terminal scrollback | Run `/clear`. Mirror redraws the conversation and keeps its history. |
| Exit Mirror | Use `Ctrl+C`, `Ctrl+D`, or `/quit`. |

## Slash commands

1. Type `/` to browse commands.
2. Use the arrow keys to choose one.
3. Press `Enter` to select it.

Some commands need the current turn to finish before they can run.

### Conversations and workspaces

| Command | What it does |
| - | - |
| `/help` | List currently available commands and aliases. |
| `/status` | Show the model, reasoning effort, conversation ID, working directory, and turn status. |
| `/login` | Check your Reflection credentials, or open the **Connect to Reflection** prompt if none are available. |
| `/logout` | Remove the saved Reflection API key. If no other Reflection key is available, Mirror opens the **Connect to Reflection** prompt. Doesn't affect `REFLECTION_API_KEY`. |
| `/new` | Start a new conversation in the selected workspace. |
| `/resume [id-or-prefix]` | Open the conversation picker, or resume a conversation by its full ID or a unique ID prefix. |
| `/rewind` | Choose an earlier user turn and branch the conversation after confirmation. File changes remain in place. |
| `/workspaces` | Search and switch between workspace tabs. |
| `/worktree [name]` | Create a separate checkout from the latest `origin/main` and start an independent agent there. |
| `/rename <alias>` | Give the current worktree tab an alias. This does not rename the Git branch. |
| `/drop` | Remove the selected managed checkout and close its agent. Read [removing a workspace](/mirror-workspaces#remove-a-workspace) first. |

### Settings and tools

Model, credential, context, editor, connection, memory, and feedback commands come from bundled extensions. They are available while the corresponding extension is enabled.

| Command | What it does |
| - | - |
| `/model [model-or-provider]` | Open the model/provider picker, or select a model ID or supported provider. |
| `/reasoning [effort]` | Open the reasoning picker, or set an effort level. |
| `/permissions` | Choose automatic or manual tool approval. |
| `/extensions` | Enable or disable discovered extensions. |
| `/context` | Show estimated tokens for the latest system prompt and tools, grouped by source. Excludes conversation history. |
| `/editor` | Choose a text file under the working directory and open it in your editor. |
| `/connect [service]` | Open the service picker and sign in to a service, or connect a [custom MCP server](#mcp-servers) by name. |
| `/connections` | Show connected services and their status. |
| `/disconnect [service]` | Disconnect a service. For a custom server, this deletes its definition and saved credentials. |
| `/memory [on\|off\|status\|import]` | Turn memory on or off, show whether it's on, or import memories saved by Claude Code or Codex. Memory is off by default. |
| `/feedback` | Open the GitHub feedback form in your browser. |
| `/view [mode]` | Cycle transcript detail, or select `transcript`, `compact`, or `extra-compact`. |
| `/clear` | Clear terminal scrollback and redraw without deleting the conversation. |
| `/quit`, `/exit` | Exit Mirror. |

## Keyboard shortcuts

These are the default bindings. Menus and approval prompts use some keys for their own navigation, but `Escape` at an approval prompt interrupts the whole turn.

| Key | Action |
| - | - |
| `Enter` | Send a prompt or accept the selected menu item. |
| `Ctrl+J` | Insert a newline outside a menu. |
| `Escape` | Dismiss a menu, or interrupt the active turn, including at a tool-approval prompt. |
| `Tab` / `Shift+Tab` | Select the next or previous workspace outside a menu. |
| `Ctrl+1` through `Ctrl+9` | Select a numbered workspace, if your terminal supports these sequences. |
| `Ctrl+R` | Search prompt history. |
| `Ctrl+Z` / `Ctrl+Y` | Undo or redo edits in the prompt composer. |
| `Ctrl+T` | Cycle transcript detail. |
| `Ctrl+L` | Redraw the transcript. |
| `Ctrl+P` | Open the editor file picker, when the editor extension is enabled. |
| `F2` | Toggle automatic and manual tool approval. |
| `1` / `2` | Approve or reject the current tool-approval request. `Enter` approves unless you select another option. |
| `Ctrl+O` | Detach running tool calls so the agent can continue while they finish. |
| `Ctrl+C` / `Ctrl+D` | Exit Mirror. |

User shortcut overrides live in `~/.mirror/keybindings.json`. Project directories do not supply shortcut overrides.

## Resume or branch a conversation

| Start command | Conversation |
| - | - |
| `mirror` | Create a new conversation. |
| `mirror --continue` | Resume the most recent conversation for each worktree as its agent starts. Create one if none exists. |
| `mirror --conversation-id <conversation-id>` | Resume a specific conversation. |

Inside Mirror, use `/resume` to open the searchable picker:

* Type to filter the list.
* Press `Tab` to cycle between the current directory, the repository, and all directories.
* Pass a full ID or unique prefix to `/resume` to select a conversation directly. A prefix must identify exactly one conversation.
* Resuming from a different directory asks for confirmation. Files and the working directory may differ from the earlier session.

To branch from an earlier turn with `/rewind`:

1. Choose an earlier user turn.
2. Edit its prompt.
3. Confirm the new conversation branch. The original conversation keeps its later turns.

<Warning>
  Rewinding changes conversation history only. It does not restore or undo files the agent edited.
</Warning>

## Work on parallel tasks

Use `/worktree [name]` to create a separate checkout, then `/workspaces` to select it. Each workspace has its own agent and conversation.

See [workspaces](/mirror-workspaces) for creation, switching, status indicators, saved settings, parallel-task examples, and removing completed checkouts.

## Choose a model and reasoning effort

* Use `/model` to choose a provider or model.
* Mirror remembers a model selected with `/model`. A model or provider set with launch flags applies to that launch only.
* Each workspace remembers its model and reasoning effort.
* Run `/status` to check the model and reasoning effort. The status bar below the prompt shows the approval mode, model, and reasoning effort.

To choose settings at launch:

```bash theme={null}
mirror --api reflection --model Beam-501B-A23B --reasoning-effort high
```

* **Launch default:** `xhigh`. A workspace's saved reasoning effort takes precedence over the default and `--reasoning-effort`. Use `/reasoning` after launch to change it.
* **Effort levels:** The `/reasoning` picker offers `provider default`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. `--reasoning-effort` and `/reasoning <effort>` also accept `none`.
* **Supported levels:** These depend on the provider and model. With `Beam-501B-A23B`, use `low` through `max`; requests with `minimal` fail with `400`. See [Reasoning](/reasoning).

### Model picker configuration

`~/.mirror/models.json` contains a JSON array of model entries:

* **Required fields:** `id` and `label`.
* **Optional fields:** `description`, `api`, and `base_url`.

For example:

```json theme={null}
[
  {
    "id": "Beam-501B-A23B",
    "label": "Beam",
    "api": "reflection"
  },
  {
    "id": "your-model-name",
    "label": "Local model",
    "api": "openai-chat-completions",
    "base_url": "http://127.0.0.1:8000/v1"
  }
]
```

* Set `MIRROR_MODELS_CONFIG` to select a different file.
* Explicit `--api` and `--base-url` flags override values from the selected entry.
* Keep API keys in the provider's environment variable rather than this file.

### Other providers

Exporting a key does not select its provider. Choose the matching `--api` value or use `/model`.

| Provider | `--api` value | Credentials |
| - | - | - |
| Reflection | `reflection` | `REFLECTION_API_KEY` or the saved Reflection key. |
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY`. |
| OpenAI Responses | `openai-responses` | `OPENAI_API_KEY`. |
| Anthropic Messages | `anthropic-messages` | `ANTHROPIC_API_KEY`. |
| ChatGPT plan access | `openai-codex-responses` | An existing Codex ChatGPT sign-in. |
| An OpenAI-compatible Chat Completions endpoint | `openai-chat-completions` | `OPENROUTER_API_KEY` or `--api-key` if the endpoint requires authentication. |

For a custom endpoint, supply its model ID and base URL:

```bash theme={null}
mirror --api openai-chat-completions \
  --base-url http://127.0.0.1:8000/v1 \
  --model your-model-name
```

* Custom endpoints can work without an API key.
* `--api reflection` uses Reflection's endpoint and does not accept an alternative base URL.

## Tool approvals

Mirror's default is manual approval: it asks before running tools that require approval, and the status bar shows `manual`. To approve tool calls automatically:

```bash theme={null}
mirror --approval-mode auto
```

* **Saved mode:** Use `/permissions` or `F2` after launch to switch between automatic and manual approval. Mirror remembers the choice, including one made with `--approval-mode`, for every directory in `~/.mirror/config.json`.
* **Calls needing review:** Manual mode asks before tools marked as requiring approval. By default, these include shell commands, even read-only ones such as `ls` or `cat`, file writes and edits, and connected-service tools.
* **Approve or reject:** Press `1` or `Enter` to approve, and `2` to reject. Use the arrow keys to choose another option.
* **Interrupt:** `Escape` at an approval prompt interrupts the whole turn.
* **Local permissions:** Tools, external extensions, and local MCP servers execute with your account's permissions. Approval mode controls review and does not create an operating-system sandbox.

## Project instructions and skills

### Instructions

Put project guidance in `AGENTS.md` or `CLAUDE.md`. When both exist in a directory, Mirror uses `AGENTS.md`.

Mirror loads instructions from:

1. `~/.mirror/AGENTS.md` or `~/.mirror/CLAUDE.md` for global guidance.
2. Directories along the path from the repository root to your working directory.

* Outside a repository, it loads global instructions and those in the current directory.
* Run `/context` to inspect the sources used for the latest model request.

### Skills

A skill is a directory containing a `SKILL.md` file with YAML metadata and task instructions. For example, `.agents/skills/review-tests/SKILL.md`:

```markdown theme={null}
---
name: review-tests
description: Review test coverage and identify missing cases.
---

# Review tests

Read the changed code and its tests. Identify missing edge cases
and explain which test would cover each one.
```

| Skill location | Scope |
| - | - |
| `~/.mirror/skills/` | Global skills. |
| `.agents/skills/` and `.claude/skills/` | Skills along the path from the repository root to the current directory. |

A closer skill with the same name replaces an earlier one.

* Type `$` in the composer to browse skills.
* Include a whitespace-separated mention such as `$review-tests` in your prompt to request one.
* The model can also load a skill when its description matches the task.

## MCP servers

MCP connects Mirror to additional tools and services:

* `/connect` opens a picker of services: Datadog, Linear, Notion, and Slack, which you sign in to, and **Add a custom server…**, which shows how to define your own.
* `/connections` shows connected services. If it says the Mirror server is unavailable, it lists the services connected on your machine, which work without it.
* `/disconnect` disconnects a service.

Custom server rules:

* Save each server in `~/.mirror/mcp/<server-name>.json`, then run `/connect <server-name>`. Names use letters, numbers, `-`, and `_`.
* Custom servers stay on your machine.
* Set `MIRROR_MCP_DIR` to use another directory. Project-local definitions are not loaded.
* Each file describes one server, without an `mcpServers` wrapper.
* Provide exactly one of `url` or `command`.

For an HTTP server that uses a bearer credential:

```json theme={null}
{
  "url": "https://mcp.example.com/mcp",
  "auth": {
    "type": "bearer",
    "tokenEnvVar": "MY_MCP_KEY"
  }
}
```

* Export `MY_MCP_KEY` in the shell that launches Mirror.
* Authenticated HTTP servers need HTTPS, except for loopback addresses.

For a trusted local stdio server:

```json theme={null}
{
  "command": "/path/to/mcp-server",
  "args": ["--stdio"],
  "env": {
    "API_KEY": "MY_MCP_KEY"
  }
}
```

* In `env`, each right-hand value names an existing environment variable, not a literal credential. This example passes Mirror's `MY_MCP_KEY` value to the server as `API_KEY`.
* Optional `enabledTools` limits exposed tools: omit it for all tools, or use `[]` for none.
* After editing a definition, run `/connect <server-name>` to load it again. Mirror also loads definitions when it starts.
* Tool names use `mcp__<server-name>__<tool-name>`.

## Extensions

Use `/extensions` to enable or disable commands, tools, and widgets. Mirror includes bundled features and can load external Python extensions.

See [extensions](/mirror-extensions) for discovery and trust, bundled features, a working reminder widget, and the extension API.

## Launch options

These options apply to the interactive CLI. `--model` and `--api` apply to that launch only; `/model` changes the saved selection. `--approval-mode` is remembered for later launches. `/status` and the status bar show the active values.

| Option | Purpose |
| - | - |
| `--model <id>` | Select a model ID. |
| `--api <provider>` | Select a provider/protocol from the [provider table](#other-providers). `openai-chat-completions-non-streaming` is also supported. |
| `--base-url <url>` | Select a custom endpoint for a compatible provider. |
| `--api-key <key>` | Supply a provider API key. Prefer an environment variable to avoid putting a key in shell history. |
| `--reasoning-effort <level>` | Set reasoning effort; launch default `xhigh`. |
| `--compaction-model <id>` | Choose the model used to summarize history. Defaults to the conversation model. |
| `--max-iterations <count>` | Limit model/tool-loop iterations; default unlimited. |
| `--context-window <tokens>` | Override the context length used for budgeting and compaction. Otherwise Mirror uses provider metadata when available, or a built-in limit. |
| `--compaction-threshold <tokens>` | Set the prompt-token count that triggers history compaction. Otherwise Mirror derives it from the context window. |
| `--max-tokens <tokens>` | Set the soft completion-token ceiling; default `64000`. Mirror may reduce it to fit the context budget. |
| `--continue` | Resume recent conversations as worktree agents start. |
| `--conversation-id <id>` | Resume one conversation. Cannot be combined with `--continue`. |
| `--allow-foreign-workspace` | Allow a launch-time resume from another directory without its confirmation prompt. |
| `--database <path>` | Select the agent conversation database. Does not move the CLI metadata database. |
| `--approval-mode auto` / `--approval-mode approve` | Select automatic or manual review; remembered for later launches. Default `approve`. |
| `--scrollback-limit <lines>` | Limit transcript lines painted on redraw; default `1000`, or `0` for no limit. Older history stays stored. |
| `--flush-scrollback` / `--no-flush-scrollback` | Clear saved terminal scrollback on screen replacement; disabled by default. |
| `--trust-extensions` | Enable newly discovered external extensions without a startup prompt. Existing disabled choices stay disabled. |
| `-h`, `--help` | Show installed launch options and exit. |

## Local files and diagnostics

| Location | Contents |
| - | - |
| `~/.mirror/state.db` | Agent conversation state. Override with `--database` or `MIRROR_STATE_DB`. |
| `~/.mirror/cli.db` | Prompt history and workspace preferences. Override with `MIRROR_CLI_DB`. |
| `~/.mirror/models.json` | Model picker entries. |
| `~/.mirror/last_model.json` | Last complete model/provider selection. |
| `~/.mirror/config.json` | Approval mode, trusted directories, and extension settings. |
| `~/.mirror/keybindings.json` | Shortcut overrides. |
| `~/.mirror/reflection_api_key` | Saved Reflection API key. |
| `~/.mirror/mcp/` | Custom MCP server definitions. |
| `~/.mirror/mcp/credentials/` | MCP authentication data. |
| `~/.mirror/memory/` | The memory store, when memory is on. |
| `~/.mirror/logs/<conversation-id>/` | Session diagnostics, including worker stderr. |
| `~/.mirror/worktrees/` | Mirror-managed checkouts. |

* **Database paths:** The agent and CLI databases must use different paths.
* **Conversation state:** Keep it when troubleshooting a failed launch. Changing the executable does not reset these files.
* **Model requests:** They include conversation context, relevant file contents, and tool results.
* **Shared diagnostics:** Logs can contain sensitive information. Review them and remove API keys or private code before sharing.

For authentication, model, or rate-limit errors, see [troubleshooting](/coding-agents-quickstart#troubleshooting).

## Report a bug

1. Run `/feedback` to open the [GitHub feedback form](https://github.com/reflection-oss/mirror-beta/issues/new/choose).
2. Sign in to GitHub and choose a report type.
3. Include your operating system, installed wheel version, reproduction steps, and the error message.
4. Review the public issue and remove API keys or private code before submitting it.

`/feedback` does not attach session data or diagnostics automatically.