MercurALPHA
Sign inCreate a free account

CLI agent: forward localhost with npm

The Mercur CLI is a device agent you install from npm. It forwards the same public HTTPS, WebSocket, or TCP endpoints as the macOS desktop app, from a terminal, a CI job, or a headless server.

Create the endpoint in the console first. The CLI authenticates, lists endpoints, and starts or stops forwarding. It does not create endpoints, open a request inspector, or run HTTP log-only mode.

Open the console

When to use the CLI vs the macOS app

  • macOS app — tray agent on a Mac, console-driven start/stop, log-only mode, request inspector in the product.
  • npm CLI (@mercur_dev/cli) — any OS with Node.js 20+, CI, and scripts. HTTP start forwards and writes a request log by default.

One device holds an endpoint at a time. The CLI and the desktop app cannot both claim the same endpoint.

Install

Requires Node.js 20 or later from nodejs.org.

Run
npm install -g @mercur_dev/cli

Confirm the binary:

Run
mercur --help

npx works without a global install:

Run
npx @mercur_dev/cli --help

Create a CLI token

  1. Sign in at the console.
  2. Open Settings → Account → CLI tokens.
  3. Name the token (for example Laptop or CI) and create it.
  4. Copy the secret immediately. It is shown once and starts with mcrcli_.

Open CLI tokens

Do not paste a workspace API key (mcr_…) or the Agent Auth Token. Those are different credentials.

Authenticate

Run
mercur auth

Paste the mcrcli_… secret when prompted, or pass it in one shot:

Run
mercur auth mcrcli_…

The token is written to a mode 0600 file: ~/.config/mercur/config.json on macOS and Linux, or %APPDATA%\mercur\config.json on Windows.

List endpoints

Run
mercur list

You see every endpoint across workspaces you belong to: id, protocol, local port, state, public URL, and workspace name. Copy the endpoint id for start and stop.

If the table is empty, create an endpoint in the console first.

Start forwarding

Run something on the endpoint's local port, then:

Run
mercur start ep-abc123

The process stays in the foreground and prints the public URL mapped to localhost. Leave that terminal open. HTTP tunnels write a request log by default; inspect it in the console. Turn capture off without stopping the tunnel:

Run
mercur start ep-abc123 --no-log

--no-log applies only to HTTP. WebSocket and raw TCP always proxy without a request log.

One CLI process handles one endpoint. Open a second terminal to run a second tunnel.

Plan limits apply exactly as they do in the console. If the protocol is not on your plan, the CLI prints the API error and a link to upgrade.

Stop a tunnel

Stop with Ctrl+C in the start terminal, or from another terminal on the same machine:

Run
mercur stop ep-abc123

stop only releases a claim this machine started. If the desktop app or another host holds the endpoint, stop it there.

CI and environment variables

Keep start in the foreground. The tunnel lives only while that process is running.

| Variable | Meaning | | --- | --- | | MERCUR_TOKEN | CLI token. Overrides the file. Prefer this in CI so the secret never hits disk. | | MERCUR_API_URL | Console origin. Default https://console.mercur.sh. |

Run
export MERCUR_TOKEN=mcrcli_…
mercur start --no-log ep-abc123

Create a token named for the workflow and revoke it when the job is retired. CI examples use --no-log so webhook payloads are not stored in request history.

What the CLI does not do

  • Create, edit, or delete endpoints — use the console.
  • HTTP log-only mode (capture without forwarding) — use the console or the macOS app.
  • Steal an endpoint another device already holds.

Revoking a CLI token stops tunnels started with that token. The desktop agent is unaffected.

Troubleshooting

No CLI token found — create a token in Settings and run mercur auth, or set MERCUR_TOKEN.

That does not look like a CLI token — CLI tokens start with mcrcli_.

Unauthorized — wrong token, revoked token, or the wrong console. A token from a local console will not work against production. Set MERCUR_API_URL if you are not using production.

Already running / occupied — another mercur start on this machine, the desktop app, or a different host holds the endpoint.

Nothing reaches localhost — confirm the process printed Forwarding … -> localhost and that something is listening on the endpoint's local port from the console, not a CLI flag.

Relay errors such as 503 No agent for client are the same as for the desktop app. See troubleshooting.

Related