Mercury CLI
Documentation

Trust and health

Health check

The health check certifies the install: the runtime, the settings and the release channel are checked live and rolled into one verdict. It runs interactively as /health, with /doctor as its alias, and headless as mercury health or mercury doctor. The Boot face's Doctor / Health Check row opens the same certificate. Configured MCP servers are validated without being started.

The report is read-only against Mercury: it consults gate helpers, snapshots, small local artifacts and operating-system metrics. It never runs a session, never mutates state and never echoes a credential; its only write is the last-certificate summary.

Certificate verdicts

Every check carries a mandatory evidence string naming the artifact, probe or value consulted, and fixes are ranked worst-first.

  • certified: No check reads fail, warn, stale or unknown.
  • caution: At least one check reads warn, stale or unknown, and none reads fail.
  • fault: At least one check reads fail.

A check's status is one of ok, warn, fail, stale, unknown, off or info. No evidence means the check reads unknown, never a silent pass; evidence that predates what it certifies reads stale. off and info are neutral and never raise the verdict.

Run a health check

To run a health check, follow these steps:

  1. Run mercury health.

Mercury prints the certificate: the verdict, the sections with their checks and evidence, and the ranked fixes.

Open the interactive certificate

To open the interactive certificate, follow these steps:

  1. Enter /health in a session.

The health panel shows the install's certificate and the fixes it offers.

Inspection options

  • --json: Prints the certificate as one JSON document.
  • --deep: Runs the deep inventory in addition to the fast checks.
  • --only <id>: Limits the plain report, --json or --fix to one check.
  • doctor: The command-line alias of health.

A piped or redirected run is not the host's interactive terminal, so the terminal-profile row reads as environmental and never raises the verdict.

Notable checks

  • Tools withheld: In TOOL CAPABILITY, names every built-in tool kept out of the model's catalogue because a machine dependency is absent, such as a debug adapter for Debug or the desktop driver for Computer, with the reason and the remedy.
  • Env overrides: In SETTINGS & FLAGS, lists the registered flags set in the environment, with Mercury's own stamps and the boot's saved defaults named apart from your overrides. A retired setting still set turns the row to warn, and the fix says to unset it.
  • Store isolation: In CREW & DAEMONS, reports a config-home record written by another tool with its evidence line. Its remedy archives the foreign records into a dated directory inside the home, reversibly.
  • Box lock: In RUNTIME, names the box lock's coordination directory from MERCURY_BOX_LOCK_DIR, the slots held and by whom, and the tickets waiting.

Fix reported problems

To fix reported problems, follow these steps:

  1. Run mercury health --fix.

Mercury applies the safe remedies and re-probes each one, and the outcome shown is that verification, never the remedy's self-report.

A destructive remedy needs --yes on the command line. In the interactive panel a fix goes through a consent card, and a destructive remedy renders its warning. A remedy is offered only for fail, warn and stale; ok, info, off and unknown rows never expose apply. Every applied fix writes an evolution-ledger row.

The doctor JSON

mercury doctor --json prints the certificate as one JSON document carrying verdict, ranAt, version, durationMs and depth; head, the repository state at issue time; nodeRuntime, the runtime contract with its verdict; sections[], each with its checks and their evidence, evidenceAt and status; and readiness[], the capability-readiness rows for tools, MCP servers, lanes, engines, extensions and skills.

Artifacts and switches

The doctor state root is <project>/.mercury/, and MERCURY_DOCTOR_STATE_DIR overrides it.

  • doctor/last-cert.json: The summary written after each certificate. The certificate chip in the session chrome folds it in, and a summary older than a day reads stale.
  • doctor/last-preflight.json: The boot preflight's summary. The preflight runs a cheap subset of /health after the interface mounts and notifies only on a fault; it is not a certificate.
  • gate/verdict.json: Written by the local verification pool. The PROOFS section reads it as evidence and reports it stale when it predates the current HEAD.
  • MERCURY_DOCTOR_CERT=0: Restores a plain install-diagnostics screen with no certificate and no artifact writes.
  • MERCURY_DOCTOR_FIX=0: Makes /health diagnose-only.
  • MERCURY_BOOT_PREFLIGHT=0: Skips the boot preflight.

Install and update, Reporting a problem, Workspace trust and permissions, Command-line reference