Command-line reference

The built artifact is also a command-line tool. It runs one noninteractive turn, continues or resumes a session, and carries 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

-p "<prompt>": Runs one noninteractive turn.
-c: Continues the most recent conversation.
-r: Resumes a conversation by id, title or picker.
-w: Runs the session inside a managed worktree.
--bare: The minimal mode.
--output-format text|json|stream-json: Selects the output of a noninteractive turn.

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 Boot face.
--chat: The plain world, the Boot face and a chat with no concourse.
--concourse-off: Saves that choice for every later boot. --concourse-on, or /config, turns the concourse back on.
--init, --init-only and --maintenance: Start Mercury with the Setup hook event, whose trigger is init or maintenance.
--version: Prints the version line.
--help: Lists every flag.

Output formats

text: Text output.
json: Prints the result envelope alone.
stream-json: Carries every event of the run, from the init row to the result envelope, with no other option asked for.

Run a noninteractive turn

To run a noninteractive turn, follow these steps:

Run mercury -p "<prompt>" with the prompt.

Mercury runs the turn without opening the interactive interface.

Read a run as an event stream

To read a run as an event stream, follow these steps:

Run mercury -p "<prompt>" --output-format stream-json.

The output carries every event of the run and ends with the result envelope.

Management verbs

mercury health: The health certificate; doctor is an alias. --json prints it whole, --deep runs the deep inventory and --fix runs the guided fixes.
mercury auth login|status|logout|token: Signs in, shows the status, signs out, or mints a long-lived token.
mercury mcp: Manages MCP servers with add, add-json, list, get, remove and serve.
mercury extensions: Installs extensions and manages their sources with list, sources, add, remove, check, install, approve, enable, disable, update, uninstall, block, unblock, validate and init.
mercury agents: Prints the agent inventory.
mercury daemon: The background daemon that hosts sessions.
mercury acp --stdio: The editor bridge over the Agent Client Protocol.
mercury editor <action>: Manages the IDE side of the editor integration.
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 themis lock|verify|approve: THEMIS integrity tooling. lock enrols the trust-relevant configuration files, verify is the read-only sweep that exits 1 on any problem, and approve re-stamps both baselines at the current content.
mercury show <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. An install made by Homebrew or npm is updated with that channel's own command, and mercury update run inside either says so and changes nothing.
--allow-unsigned: On install and update, accepts an unsigned payload only, never an unknown key, a malformed signing block or tampered bytes.

Inspect the artifact's help

To inspect the artifact's help, follow these steps:

Run node dist/mercury.mjs --help from a built source copy.

The artifact lists every headless verb 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.

Slash commands, Sessions, Install and update, Health check, Editor bridges