Mercury CLI
Documentation

Start

Install and update

Mercury installs release archives into a directory for the current user and supplies a mercury command. Updates activate a verified payload while retaining the previous release.

A release installation requires git. Its archive carries its own Node runtime and ripgrep. Archives are supplied for Apple silicon and Intel Macs, Linux x64 and Windows x64. No archive is supplied for Linux arm64 or Windows arm64, and the installer says so and points at building from source. On Windows arm64 the x64 build runs under emulation. Building a copy is covered by the repository's source-build guide.

Install with curl

To install with curl, follow these steps:

  1. Run the channel command:

    curl -fsSL https://mercury-cli.ai/install | sh     # macOS and Linux x64

The script downloads the newest archive for macOS or Linux x64 and runs its installer.

Install with PowerShell

To install with PowerShell, follow these steps:

  1. Run the channel command:

    irm https://mercury-cli.ai/install.ps1 | iex        # Windows x64, in PowerShell 7

The script downloads the newest Windows x64 archive and runs its installer.

Install with Homebrew

To install with Homebrew, follow these steps:

  1. Run the channel command:

    brew install Whq02/mercury/mercury                 # Homebrew: macOS and Linux x64

Homebrew installs the release pinned by its formula.

Install with npm

To install with npm, follow these steps:

  1. Run the channel command:

    npm install -g mercury-tech-cli                    # npm; `bun install -g mercury-tech-cli` is the same package

The npm launcher downloads the release named by its package.

Install with mise

To install with mise, follow these steps:

  1. Run the channel command:

    mise use -g npm:mercury-tech-cli                   # mise, through the npm package

mise installs Mercury through the npm package.

The curl and PowerShell scripts check the archive against the release's SHA256SUMS.txt. Homebrew and npm packages can trail the newest release until they are republished. All channels install without administrator access, and running an installation command again is safe.

Installation locations

  • Release payloads: ~/.mercury/versions/<version>, or %USERPROFILE%\.mercury\versions on Windows, holds one complete release payload per version under the config home.
  • Command directory: ~/.local/bin on macOS and Linux, or %LOCALAPPDATA%\Mercury\bin on Windows, holds the command. The installer adds that directory to PATH once.
  • Active release: <config-home>/versions/current.txt names the active payload, and previous.txt names the previous one. Updates and rollbacks switch the pointer file by atomic rename.
  • Deployed source copy: <config-home>/runtime/dist holds a deployed source build, with its launcher at <config-home>/bin/mercury.

Configuration and sessions live in the config home outside the versioned payload directory. Installation, update, rollback and uninstall leave them in place.

Adopt an extracted release archive

To adopt an extracted release archive, follow these steps:

  1. Run mercury install through that archive's own launcher.
  2. Open a new terminal.
  3. Run mercury --version.

The archive becomes the managed installation and the command prints its version.

The installation options are:

  • --dry-run: Previews the adoption, names the runtime the payload carries and names the change it would make to PATH.
  • --uninstall: Removes managed binaries only and says what it preserved.
  • --force: Replaces a foreign command at the stable path and keeps it as a .bak file. Without the flag, a foreign command is refused.
  • --json: Prints the result as JSON.

Update a managed installation

To update a managed installation, follow these steps:

  1. Run mercury update. mercury upgrade is the same command.

Run inside a Homebrew or npm installation, mercury update names the package manager that updates that installation instead.

Mercury downloads the release, verifies its checksum and signature, stages it beside the active version and switches the active pointer. A failed smoke check after the switch restores the previous pointer.

The updater reads the public release list anonymously and consults a signed-in GitHub CLI, gh, only when that request is refused. A checksum match and a signature under the Mercury release key are required before activation. --allow-unsigned accepts an unsigned payload only, never an unknown key, a malformed signing block or tampered bytes, and the result and the local receipt name the exception.

Update a Homebrew installation

To update a Homebrew installation, follow these steps:

  1. Run brew upgrade Whq02/mercury/mercury.

Homebrew updates its Mercury installation.

Update an npm installation

To update an npm installation, follow these steps:

  1. Run npm update -g mercury-tech-cli.

npm updates its Mercury package.

Update a mise installation

To update a mise installation, follow these steps:

  1. Run mise upgrade npm:mercury-tech-cli.

mise updates the npm package it installed.

Update controls

  • mercury update --check: Reports the newest release against the version running.
  • mercury update --status: Names where this Mercury came from and the runtime in use.
  • mercury update --rollback: Restores the previous managed release.
  • Update notice: Once a day, an interactive boot reads the release list and shows one expiring line when a newer release exists. MERCURY_UPDATE_NOTICE=0 disables it.

Inside a Homebrew or npm installation, a bare mercury update and --rollback decline before the release list is read and name the command that updates that installation. --check and --status still answer. If another mercury appears earlier on PATH, the last lines of an update and the doctor's Command on PATH row report the mismatch and its remedy.

Quickstart, Health check, Command-line reference