Mirror CLI reference

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. This page covers the interactive CLI and its settings.

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.

Start Mirror CLI

Start it from the directory where you want to work:

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:

mirror --api reflection --model Beam-501B-A23B

Mirror uses a Reflection API key in this order:

--api-key, if provided. Prefer the environment variable to keep the key out of shell history.
REFLECTION_API_KEY in your environment.
A saved key in ~/.mirror/reflection_api_key.
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.

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

Type / to browse commands.
Use the arrow keys to choose one.
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 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 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:

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

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

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 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:

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.

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:

[
  {
    "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:

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:

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:

~/.mirror/AGENTS.md or ~/.mirror/CLAUDE.md for global guidance.
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:

---
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:

{
  "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:

{
  "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 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. `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.

Report a bug

Run /feedback to open the GitHub feedback form.
Sign in to GitHub and choose a report type.
Include your operating system, installed wheel version, reproduction steps, and the error message.
Review the public issue and remove API keys or private code before submitting it.

/feedback does not attach session data or diagnostics automatically.

Get started

Coding agents

Mirror CLI

Guides

Resources

Start Mirror CLI

Send prompts and interrupt turns

Slash commands

Conversations and workspaces

Settings and tools

Keyboard shortcuts

Resume or branch a conversation

Work on parallel tasks

Choose a model and reasoning effort

Model picker configuration

Other providers

Tool approvals

Project instructions and skills

Instructions

Skills

MCP servers

Extensions

Launch options

Local files and diagnostics

Report a bug

​Start Mirror CLI

​Send prompts and interrupt turns

​Slash commands

​Conversations and workspaces

​Settings and tools

​Keyboard shortcuts

​Resume or branch a conversation

​Work on parallel tasks

​Choose a model and reasoning effort

​Model picker configuration

​Other providers

​Tool approvals

​Project instructions and skills

​Instructions

​Skills

​MCP servers

​Extensions

​Launch options

​Local files and diagnostics

​Report a bug

Start Mirror CLI

Send prompts and interrupt turns

Slash commands

Conversations and workspaces

Settings and tools

Keyboard shortcuts

Resume or branch a conversation

Work on parallel tasks

Choose a model and reasoning effort

Model picker configuration

Other providers

Tool approvals

Project instructions and skills

Instructions

Skills

MCP servers

Extensions

Launch options

Local files and diagnostics

Report a bug