CLI Reference

merlin [OPTIONS] [TASK]
merlin [SUBCOMMAND]

Positional

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

Options

Flag	Description
`-p, --provider <name>`	Provider to use (overrides `default_provider`)
`--no-verify`	Disable the verify gate for this run
`-y, --yes`	Auto-approve dangerous tool calls (advisory)
`--listen`	Listen for AlgoChat messages and auto-respond
`--resume [ID]`	Resume the most recent session, or a specific session by ID
`--sessions`	List past sessions
`--no-session`	Don’t create or save a session
`-h, --help`	Print help
`-V, --version`	Print version

Subcommands

`init`

Initialize Merlin in the current project:

Build all plugins under plugins/ in release mode.
Copy each plugin’s plugin.toml to the fledge data directory.
Symlink plugin binaries into the fledge bin shim directory.
Append new plugins to plugins.toml registry.
Best-effort start localnet and generate AlgoChat keys.

`health`

Run health checks on all configured providers — creates each provider, sends a test prompt, and reports latency and tool support.

`bench`

Run benchmarks across providers. Options:

Flag	Description
`--suite <name>`	Run only this suite (default: all)
`-p, --provider <name>`	Run against a specific provider (default: all)
`--history`	Show accumulated historical results

`keys`

Manage API keys in the OS keychain. Without a subcommand, lists all known keys and their source (env, keychain, or not set).

Subcommand	Description
`keys set <NAME>`	Store an API key in the OS keychain (hidden input)
`keys remove <NAME>`	Remove an API key from the OS keychain

Examples

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

# Use a specific provider for one run
merlin --provider local "explain this function"

# Skip verification (prototyping)
merlin --no-verify "experiment with a new approach"

# Interactive REPL
merlin

# Auto-respond on AlgoChat
merlin --listen

Exit Codes

Code	Meaning
`0`	Task completed successfully (or cancelled)
`1`	Task errored — provider failure, exhausted retries, missing config

Output

Merlin writes all human-readable output to stderr. This means piping merlin "<task>" to a file captures only what the task explicitly produces (currently nothing — Merlin is purely side-effecting). The streaming progress lives on stderr to keep machine-readable output clean for future use cases.