Mercur
Try it free

CLI agent: forward localhost with npm

The Mercur CLI is a device agent you install from npm. HTTP works without an account:

Run
npx @mercur_dev/cli http 3000

That forwards public HTTPS to localhost:3000 and prints a share URL for logs. Guest tunnels idle out 24 hours after you stop.

WebSocket and TCP, and a stable workspace URL, need a workspace-scoped CLI token. Create the endpoint in the console first — authenticated http / ws / tcp reuse a stopped endpoint; they do not auto-create. start <id> --port is the advanced, explicit path.

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 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 http 3000
Run
npx @mercur_dev/cli --help

Guest HTTP

No token. A guest id is stored in config.json (mode 0600) and reused until the 24h idle lease expires.

Run
mercur http 3000

--no-log turns off request capture. The share link still lets anyone send traffic to your tunnel.

Workspace token (advanced)

  1. Sign in at the console.
  2. Open Settings → Account → CLI tokens.
  3. Pick the workspace (auto-selected if you have one), name the token, 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. Tokens minted before workspace scoping no longer work — create a new one.

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.

One-command tunnels

With a token, the CLI searches that one workspace for the oldest stopped, unoccupied endpoint of the protocol, binds the port, and starts proxy:

Run
mercur http 3000
Run
mercur ws 4000
Run
mercur tcp 5432

If none is free, the CLI prints why (log-only inspector, failed, already running on this machine, occupied elsewhere, or plan) and a console link. It does not create an endpoint.

List endpoints

Run
mercur list

You see endpoints in this token’s workspace: id, protocol (tcp for raw TCP), 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 a specific endpoint

Run something on the local port you will forward to, then:

Run
mercur start ep-abc123 --port 3000

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 --port 3000 --no-log

--no-log applies only to HTTP. WebSocket traffic is inspected on the Connections tab, not as HTTP request rows. TCP has no session inspector.

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 tunnel 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. Without a token, stop uses the saved guest session.

CI and environment variables

Keep the tunnel command 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 http 3000 --no-log

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

  • Auto-create endpoints for authenticated users — 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 — HTTP still works: npx @mercur_dev/cli http 3000. For a workspace, 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 / workspace-scoped token — mint a new token in Settings (pick a workspace). 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 http 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 port you passed.

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

Related