Command-line reference

The built artifact is also a command-line tool. It runs one noninteractive turn, continues or resumes a session, and has the management verbs that scripts and editor connections use. On a release install the command is mercury; on a source build it is node dist/mercury.mjs, and the two spellings take the same flags and verbs.

Session flags

mercury run "<prompt>": Runs one noninteractive turn.
--project <dir>: Selects the project folder when placed before the command word (mercury --project <dir> run "<prompt>"). Passing mercury run --project <dir> exits 2 with the remedy mercury --project <dir> run ….
-c: Continues the most recent conversation.
-r: Resumes a conversation by id, title or picker.
-w: Runs the session inside a managed worktree. --worktree [name] cuts one by name, and a name of the form #<n> or a pull-request link cuts it from that pull request's head; --multiplex runs it inside a tmux session of its own.
--lean: The minimal session with Bash, Read, Edit and Write.
--model <id> and --effort <level>: Set the model and the effort for the launch, ahead of the saved defaults. An unusable --model id is refused at the start of a run before any session is created or saved, so a later --continue in that folder starts on the default model instead of inheriting the bad id. --backup-model <id> places a backup model at the head of engine.backups for the launch.
--max-time <time>: Sets a wall-clock deadline for mercury run (seconds, or spans such as 90s, 10m, 1h); once the time is up, mercury run --max-time cuts a reply or tool still running when the limit passes and ends with status time_limit.
--title <name>: Titles the first session the launch opens.
--mode <mode>: Selects the permission posture. --sovereign runs without permission prompts, and --allow-sovereign makes that posture available for a later switch. Permission policy and deny rules still apply.
--allowed-tools "<rule>": Pre-authorises a rule for the run, such as Bash(git push *).
--format text|json|rows: Selects the output of a noninteractive turn.
--partial: With --format rows, adds the streaming delta rows.
--input rows: Reads one input object per line from stdin; it requires --format rows.
--advise: Enables the advisor for this headless run. /config → Advisor in the run's config home must also be on, and /submodels selects its model.

node dist/mercury.mjs --help lists every flag with its default. This page names the flags the README and AGENTS.md describe.

Boot flags

A prompt argument, --continue or --resume: Goes straight to the chat instead of the home screen.
--chat: Opens only the home screen and chat, without the Session Concourse.
--concourse-off: Saves that choice for every later boot. --concourse-on, or /config, turns the concourse back on.
--version: Prints the version line.
--help: Lists every flag.
MERCURY_SPLASH=off: Skips the enter screen that an interactive boot shows before the main bundle loads.

Output formats

text: Prints the answer; a failed turn's reason goes to stderr.
json: Prints the last outcome row as one JSON object.
rows: Writes one JSON object per line: session (which includes tools_withheld when a deny rule withholds a tool by its bare name), then a turn and its text, reasoning, tool_call, tool_result and step rows, ending in outcome. Waits, tool progress from a running shell, PowerShell, MCP or Eval call, background tasks, compactions, mode changes, rate limits and notices have their own rows. Every row carries seq, timestamp and session_id.

The outcome carries schema, turn_id, status, steps (counting only the main agent's model calls, while crewmate calls appear as their own step rows tagged with parent_call_id), wall_ms, usage, models and denials, with answer on completion and error on failure. A mercury run ends on the model's final answer and leaves no note, so its stream carries no close row. The status is completed, blocked, refused, failed, interrupted, turn_limit, budget_limit, time_limit, schema_unmet or loop_stopped. A completed run exits 0, other outcomes exit 1, and a usage error exits 2. SIGINT and SIGTERM exit 130 and 143 after the interrupted turn's outcome is flushed. With --format rows, exit waits for a piped reader to drain while the pipe is open and exits 1 with a diagnostic line on stderr if the reader closes the pipe early. A refused tool call is listed in denials; if an unanswered permission ask is followed by a later tool call in the same turn that succeeds, the turn recovers and finishes completed (exit 0) with a warning notice, and when no later tool call succeeds it finishes blocked (exit 1). An unanswered AskUserQuestion in a headless run finishes blocked (exit 1) the same way, with the question itself quoted in error on the outcome row; the outcome is read from the run's recorded asks instead of the words of the answer, so a question written only in the answer text finishes completed.

Run a noninteractive turn

Run mercury run "<prompt>" to execute a single turn without opening the interactive interface. When the run's input closes, its watches and every background shell end with the run, and the cost totals are saved at close and carried into a resume; a process that must stay up after the run exits (such as a server another command checks once the run has ended) is a Service started with lifecycle: "project" (keyed by the session's project whatever the shell's working directory), which outlives the session that started it, and its start result says so. Child processes of a headless session run with GIT_TERMINAL_PROMPT=0, PAGER=cat and GIT_PAGER=cat unless you set them (while an interactive session's shell is untouched). A run has no host to answer permission asks: its permission rules and mode decide what can run, and a call that still needs approval is denied; bare env and printenv are read-only in a headless Default-mode run and need no approval (env <command> still asks as a command), and a headless run told "remember: <fact>" stores a regular fact while "pin this: <rule>" or "make this a rule: <rule>" stores a pinned rule on your words and ends completed.

Starting a chat boot from a shell with no terminal (stdin is not a TTY) exits 2 immediately with the mercury run -- "<prompt>" spelling, and a single unknown word with stdin piped is refused as an unknown command with mercury run -- "<word>" instead of starting a model turn.

After three identical failing tool calls in a row (same tool and canonical JSON arguments, including permission or hook refusals), a headless turn or crewmate stops once the round settles with status: "loop_stopped", naming the tool, the call's field names and value shapes (never the values) and the error; the second consecutive identical failure warns the model with the error text first, and interactive foreground sessions receive reminders only. This stop counts only repeated failures. A background main session receives a crewmate's report through the crew's live store, and the report starts a turn when the session is waiting between turns.

A mistyped slash command exits 1. Screen-only commands such as mercury run /usage need the interactive screen. They report that requirement on stderr and exit with status 1. Use them from an interactive Mercury session (or run mercury usage for the headless usage command).

Read a run as an event stream

Run mercury run "<prompt>" --format rows to stream every event of the run as newline-delimited JSON, ending with the outcome row. A crewmate moved to the background streams its messages as rows tagged with the call that launched it. --partial adds block_start, text_delta, reasoning_delta, tool_input_delta and retracted rows; the settled text or tool row is the complete value.

Feed a run from stdin

Run mercury run - with the prompt piped in, or mercury run --input rows --format rows with one JSON object per line.

mercury run - reads the whole prompt from stdin (on Windows, piping a prompt from PowerShell such as "prompt" | mercury run - forwards pipeline input through the PowerShell shim and version launcher to the runtime). Beside a prompt argument, piped text is read until stdin closes or has been silent for one second and appended as delimited context. With --input rows, the input types are prompt with content (and an optional per-turn JSON Schema in schema), shell with command, note with to and content, and outside-report with sender and content; an outside report is never an instruction and carries no authority over the session's task or permissions. Each accepts an optional id, and prompt and shell rows also accept priority (now, next or later). A rejected input shape or invalid per-turn schema produces a notice with the code input_refused on that row alone without ending the session, and malformed JSON ends the run.

Run the headless image

The Dockerfile at the repository root builds a Linux x64 image for CI and servers. Its entry point is mercury and its default verb is run, so the image runs one prompt against a mounted tree and exits with the run's code:

docker build -t mercury .
docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" -v "$PWD":/work mercury run "Summarise this repository." --format text
docker run --rm mercury --version

The image carries the bundle, its Node runtime, the vendored search, shell, debugger, language and image tools, git and the certificate store, and a key is its one way in: the container has no enter screen and no sign-in flow. It runs as the non-root user mercury with its config home inside the container, and /work is its working directory. A provider key arrives as an environment variable in the spellings the product reads everywhere; with no key the run refuses in one line and exits 1. docker run -i … mercury run - reads the prompt from stdin, and --user 0 runs as root with the one sovereign notice.

Host a session

mercury runner serves a session to a host over stdio as JSON-RPC 2.0, one message per line (see SDK for mercury-cli-sdk and Automation for runnable TypeScript and Python examples of mercury run --format rows and mercury runner). A runner your script or the SDK drives is a headless session, where an unanswered ask expires on its clock and a turn that ends on an unanswered question ends blocked; the sessions the Mercury screen hosts through the same door are oculus (Sessions), and the door and its frames are the same for both. The host sends initialize first, naming itself (protocol, host), declaring the capabilities holds_asks, elicitation and partial_rows, and optionally passing a session-default schema and file_checkpoints: true on the initialize params (capturing per-turn pre-edit file backups for session/rewind with mode: "code" and single-file session/file_restore with action: "restore" or action: "undo"), and waits for the answer before sending work. queue/add takes the same prompt, shell or note object as the row input (including per-turn schema on prompt rows); output arrives in row notifications. session/facts reads the session's state (including file_checkpoints: { capture, source, restorable, files, undo }); session/set_mode changes the permission mode at once, during a turn included; session/set_model, session/set_effort and session/set_spawn_switch change the model, effort and delegation switches, answering at: "now" when idle or at: "turn_end" while a turn runs (followed by session/applied when the turn ends). A reply carries result or error and no method, while a request from the runner carries method. turn/interrupt stops a turn, session/leave writes the handoff note when idle, and closing stdin ends the session. Permission asks arrive as permission/request (kind: "tool", the one kind of ask), and the host answers with outcome: "allow" or outcome: "deny". An unknown method answers -32601, invalid parameters -32602, a request before initialization -32002, a rule refusal -32010, and a malformed line -32700; three consecutive malformed lines end the runner.

Mercury as an MCP server

mercury mcp-server lets another agent submit outside reports, read session rows and search project memory. It uses Mercury's SDK and configured model accounts. Model calls spend the same account usage as other Mercury sessions. Start it from a project folder already trusted in Mercury.

See Mercury as an MCP server.

Train a model on your sessions

mercury tune turns your project's sessions into a training book, can add reasoning to its assistant turns, trains a LoRA adapter on a rented GPU, and installs the merged model into your Bank for /localsetup.

See Train a model on your sessions.

Management verbs

mercury health: The health certificate. --json prints it whole, --deep runs the deep inventory, --fix runs the guided fixes with --yes for the destructive ones, and --only <id> limits any form to one check.
mercury health processes: Lists Mercury's own local processes as JSON, each classed as running, stale, cannot end or not Mercury's. --end-stale ends the stale ones it lists, one process at a time, after re-reading each one's identity.
mercury usage: Prints the compact figures line the /usage screen shows. mercury usage --json prints the full reading as JSON: each signed-in provider's windows with used percentage and reset time, the figures and credits it stated (each with its source and age), and the session spend per model, sampling each signed-in provider's reader once as on open. On a config home with only a local model, it waits for local discovery and prints the local model and server (local/<model> on Ollama … · 0 subscriptions signed in). mercury usage --history (--days <N>, --project, --json) reports input tokens, output tokens, cache-hit rate, estimated USD and unpriced turns across saved local transcripts grouped by UTC day, model and project without contacting providers (see Automation).
mercury auth login [<family>]|list|status [<family>]|logout [<family>]|mint: Signs in (login [<family>]), lists all 22 provider families and their sign-in state (list), checks whether an account is signed in (status [<family>], exiting 0 when the active or named provider is signed in), signs out (logout [<family>]), or mints a long-lived Anthropic token (mint). When a stored key or sign-in has been refused by the service, mercury auth list, mercury auth status, mercury auth status <family> and /logins read the same refusal record and print the same status, timestamp, service message and reconnect command.
mercury models [--json]: Prints the models the signed-in accounts reach (the same facts as mercury://models).
mercury sessions list (also bare mercury sessions): Lists this project's saved sessions, newest first (breaking ties on the transcript's recorded time): the id, when it was last written, its size, live when the daemon hosts it now, and its title or first prompt; --all reads every project and --limit <n> bounds the list. The id is what mercury --resume <id> reopens and mercury sessions delete <id> removes.
mercury sessions delete <id>: Deletes one saved session (its transcript and sidecar records) after a confirmation prompt (--yes skips the prompt for scripts), while refusing a session the daemon currently hosts or an unknown id.
mercury host [status|start|stop|restart|logs|uninstall|add|recipes]: Runs and manages this computer or a saved SSH computer as a persistent model server for every session sharing the config home (compat/box-<name>/<model>), picking an Ollama or GGUF recipe that fits its memory, checking a local SHA256SUMS weight bank or confirming a download, and running the engine as a user login service (launchd on macOS, systemd --user on Linux, or Windows Scheduled Task on Windows); see Providers and sign-in.
mercury lsp list and mercury lsp install <server>: Lists the language-server catalogue with each server's installed binary path or absent install remedy (using Windows tools such as winget, scoop, rustup and cs on Windows), or shows one server's install remedy, asks (--yes for scripts) and runs it (on Windows, .cmd and .bat shims such as npm.cmd resolve through PATHEXT and run via cmd.exe /d /s /v:off /c).
mercury mcp: Manages MCP servers with add, import, list, get, remove, trust-reset and serve. In an untrusted folder, mercury mcp list and mercury mcp get <name> both skip project MCP servers and state the trust reason; in a trusted folder they skip a project server until you approve it, as a run does.
mercury extensions: Installs extensions and manages their sources with list, sources, add, remove, refresh, install, trust, enable, disable, update, uninstall, fence, unfence, inspect and scaffold.
mercury roster: Prints the agent inventory.
mercury daemon: The background daemon that hosts sessions. Its verbs are run, status, stop and restart; status names the build the daemon runs, stop takes no flags and reaps every in-flight worker with the daemon, and a stop or restart issued from inside a hosted session is refused and told to run from a plain shell.
mercury acp: Serves an editor over the Agent Client Protocol, with a runner child for each session. mercury acp --login opens Mercury's sign-in screen in a terminal; choose a provider and return to the editor when sign-in finishes. See Editor bridges.
mercury bridge install|status|uninstall: Installs, checks or removes the VS Code extension.
mercury godot run|check|capture|frames|profile|tour|jobs|cancel|result: The engine job service for the Godot project in the working directory: suites on Mercury's own headless workers from a frozen copy, the compile gate, captures, frame statistics and settled profiles, the queue, a cancel, and a record by id.
mercury image <image>: Renders an image to the terminal.
mercury install: Installs a release archive and puts the user-local bin folder on PATH once.
mercury update: Keeps an install made by the install one-liners or by mercury install current in place; upgrade is an alias. --check, --status and --rollback inspect or reverse it, and the previous version stays on disk. Versions older than that are removed when an update completes, and the update names them. It is the one update command on every channel: inside a Homebrew installation it asks once and runs brew upgrade Whq02/mercury/mercury on y, --yes skipping the question, and an npm installation is updated in place. --json prints the result as JSON.
--allow-unsigned: On install and update, accepts an unsigned payload and still rejects an unknown key, a malformed signing block or tampered bytes.

Inspect the artifact's help

Run node dist/mercury.mjs --help from a built source copy, or mercury --help on a release install, to list every headless command and flag.

Configuration and sessions live in the config home, ~/.mercury or the directory MERCURY_CONFIG_DIR names, and the build never writes there. The repository's build-and-run guide describes building and running a source copy.

SDK · Automation · Slash commands · Sessions · Install and update · Health check · Editor bridges