CLI Reference

merlin [OPTIONS] [TASK]
merlin [SUBCOMMAND]

Positional

Argument	Description
`<task>`	Task to execute. Omit to drop into the interactive REPL

Options

Flag	Description
`--protocol-version`	Print the wire-protocol integer and exit (bridges use this for compatibility checks).
`-p, --provider <name>`	Force a specific provider from `[merlin.providers.*]`.
`-y, --yes`	Auto-approve dangerous tool calls unless a `--deny` rule applies.
`--allow <PATTERNS>`	Comma-separated glob allow-list when auto-approving.
`--deny <PATTERNS>`	Comma-separated glob deny-list that always blocks.
`--project <PATH>`	Resolve and run with project config rooted at `<PATH>`.
`--tier read\|tool\|code`	Choose the cheapest provider meeting the capability tier.
`--no-verify`	Skip the verify gate for this run.
`--listen`	Listen for AlgoChat messages and auto-respond (`--listen` mode).
`--resume [ID]`	Resume the most recent session, or a specific session by ID.
`--sessions`	Print recent sessions and exit.
`--no-session`	Run without creating/updating a session record.
`--non-interactive`	Single-shot mode with no REPL and automatic denial of unsafe calls.
`--plain`	Force the legacy line-oriented REPL instead of the default terminal UI.
`--cursor-style bar\|block\|underscore`	Cursor shape for the terminal UI.
`--cursor-color <COLOR>`	Cursor color for the terminal UI (`#RRGGBB`, `cyan`, `green`, `yellow`, `magenta`, `red`, `white`, or `gray`).
`--timeout <secs>`	Hard timeout for non-interactive mode (default: 600s).
`--output text\|json\|ndjson`	Output format for machine callers.
`--system-prompt <TEXT>`	Override/augment the system prompt for this run.
`--system-prompt-file <PATH>`	Read extra prompt text from a file.
`--bind <ADDR>`	Override server bind address (`agent-team` feature).
`--agent <NAME>`	Run with a named persona (`autonomous` feature).
`--daemon`	Run the autonomous daemon loop (`autonomous` feature).
`--serve`	Start the agent-team HTTP server (`agent-team` feature).
`-h, --help`	Print help and exit.
`-V, --version`	Print version and exit.

Subcommands

`init`

Initialize Merlin in the current project. Creates fledge.toml when needed, installs/registers plugins, checks provider keys, and applies SQL migrations from migrations/.

`update`

Refresh Merlin runtime pieces without creating fledge.toml. Installs or registers plugins and applies SQL migrations from migrations/ when present.

`health`

Run connectivity and readiness checks for all configured providers.

`setup`

Start the first-run wizard to pick provider strategy and store keys.

`demo`

Open a guided onboarding task flow.

`bench`

Run benchmark suites across configured providers.

`doctor`

Show runtime/install health (MERLIN_RUNTIME_ROOT, bundled plugin availability, managed CLI status, key source summary).

`keys`

Manage API keys from the OS keychain.

Subcommand	Description
`keys set <NAME>`	Store an API key in keychain (hidden input).
`keys list`	List known keys and resolution source.
`keys remove <NAME>`	Delete one keychain entry.

`metrics`

Report provider and tool latency metrics with optional filters.

`spend`

Show provider spend over a timeframe (--since, --json).

`telemetry`

Inspect or control opt-in anonymous telemetry (status, enable, disable, export, purge).

`audit`

Show destructive-op history (--limit, --plugin, --session, --include-internal).

`wipe`

Two-phase confirm flow for deleting local Merlin state.

`redact-history`

Retroactively apply redaction rules with token-confirmed workflow (--confirm <token>).

`feedback`

Open a prefilled issue template for bug reports / feature requests. |

`whatsnew`

Print release-note sections since last check.

`server token`

Print bearer token for the local agent-team API (agent-team feature).

Examples

# One-shot task
merlin "add error handling to the parser"

# Interactive terminal UI
merlin

# Legacy plain REPL
merlin --plain

# Provider and tier selection
merlin --provider ollama-qwen-coder --tier code "update auth module"
merlin --non-interactive --output json "run quick benchmark"

# Onboarding/check commands
# `merlin setup` is experimental during the app-first alpha; prefer desktop onboarding.
merlin update
merlin doctor

# Key workflow
merlin keys set OPENROUTER_API_KEY
merlin keys list

Exit Codes

Code	Meaning
`0`	Task completed successfully or skipped verify (`success` / `skipped`).
`1`	Non-fatal runtime error or verify failure details.
`2`	Hard timeout or provider contract error.
`3`	User cancelled request / non-interactive timeout.
`4`	Configuration/setup error before task start.

Output

Merlin streams human-facing progress on stderr. In machine mode (--output json/ndjson), tool and completion output is emitted on stdout.