mercator-cli

Install and diagnose the Mercator remote MCP server and a session-capable payment wallet across supported agent clients.

curl -fsSL https://mercator.tempoxyz.dev/install.sh | sh
mercator doctor

The installer places the CLI under ~/.local, links mercator into ~/.local/bin, and launches the same interactive setup flow. Pass CLI arguments after sh -s --, for example:

curl -fsSL https://mercator.tempoxyz.dev/install.sh | sh -s -- --client codex

Setup flow

flowchart LR
    DETECT["Detect supported clients"] --> CONFIGURE["Install Mercator MCP entry"]
    CONFIGURE --> GUIDANCE["Update managed guidance"]
    GUIDANCE --> WALLET{"Ready payment runtime?"}
    WALLET -->|Yes| VERIFY["Run readiness checks"]
    WALLET -->|No| ONBOARD["Create local wallet or connect Tempo Wallet"]
    ONBOARD --> VERIFY

Supported clients:

• Codex
• Claude Code
• Gemini CLI
• Cursor
• VS Code
• Windsurf
• Cline
• Continue
• OpenClaw
• Hermes

Selection options:

| Option | Behavior | | --- | --- | | No subcommand | Run interactive setup | | Picker | Show detected clients; select several entries or all | | --client <name> | Configure one named client; repeatable | | --all | Configure every supported client non-interactively | | --dry-run | Preview configuration changes | | --force | Recreate Mercator registrations and refresh managed guidance | | --no-agents | Skip Codex AGENTS.md guidance | | --remove-agents | Remove installed Codex guidance |

Setup guarantees:

• Reuses matching existing configuration safely.
• Shows a rotating adamsky/globe with live setup progress.
• Keeps the globe active while the interactive client picker is open.
• --force never removes or recreates wallets, keys, accounts, balances, sessions, or shared MPP plugins.
• Wallet and native payment checks remain read-only during forced setup.

Example:

mercator setup --client codex --force

Codex guidance

Codex setup maintains a bounded block in the active global AGENTS.md:

• Explains when to use Mercator.
• Requires quote and budget approval before paid execution.
• Excludes local files and repository work.
• Preserves content outside mercator:begin and mercator:end HTML comments.
• Leaves an existing AGENTS.override.md untouched and reports when it shadows the guidance.
• Applies new guidance to the next Codex session.

Mercator always manages persistent AGENTS.md; use --no-agents to skip installation or --remove-agents to remove the managed block.

Payment runtime selection

Setup chooses the first ready option:

1. Existing Mercator-authorized Tempo Wallet access key.
2. Existing Mercator local disk wallet.
3. Accounts SDK onboarding: connect Tempo Wallet when selected, otherwise create a local wallet.

| Runtime | Paid-request path | Session behavior | | --- | --- | --- | | Local disk wallet | mercator submit | Uses Mercator-owned Accounts SDK storage | | Tempo Wallet | mercator submit | Uses a scoped access key authorized through Accounts | | OpenClaw | Native mpp_fetch | Uses official openclaw-mpp integration | | Hermes | Native mpp_fetch | Uses official hermes-mpp integration |

Mercator requires neither the Tempo Wallet CLI nor the MPPX CLI. An unfunded wallet opens the Mercator card onramp with its address selected.

OpenClaw and Hermes setup:

• Installs or verifies the official openclaw-mpp or hermes-mpp integration.
• Preserves existing Hermes allowed origins before adding Mercator.

Wallet onboarding

Run wallet setup separately:

mercator wallet
mercator wallet --wallet tempo
mercator wallet --wallet local
mercator wallet fund

Tempo Wallet authorization opens the Accounts SDK device flow and stores only its Mercator access key locally. Local-wallet private material and connected-wallet access keys share the Accounts SDK filesystem store at ~/.mercator/wallet.json, secured with user-only file permissions.

mercator wallet fund opens Mercator's card onramp with the connected wallet address selected. If no wallet is connected, it prints the exact mercator wallet --wallet ... setup command instead.

Paid job submission

flowchart LR
    MCP["MCP: discover + quote"] --> REST["POST /v1/jobs"]
    REST --> PAYMENT["Mercator wallet"]
    PAYMENT --> POLL["MCP or REST: poll result"]

Recommended path:

• Use MCP for discovery, quoting, and result polling.
• Use the bounded mercator submit handoff returned by create_job.
• The REST endpoint offers both tempo/session and tempo/charge.
• Some MCP harnesses cannot answer the payment-required protocol error from create_job.
• Use mpp_fetch in OpenClaw or Hermes.
• Other clients use the same Mercator wallet created during setup.

Diagnostics

doctor performs read-only checks:

• MCP transport.
• Six-tool contract.
• Free service discovery.
• Unsigned Mercator session challenge.
• Local wallet session capability.

Funding is reported separately from session capability. Paid execution remains not_verified.

Uninstall

mercator uninstall --client codex
mercator uninstall --client openclaw --client hermes
mercator uninstall --dry-run
mercator uninstall

Uninstall behavior:

• Removes only the mercator MCP entry and installer-managed Codex guidance.
• Preserves other MCP servers and user instructions.
• Preserves wallets, keys, balances, sessions, and shared MPP plugins.
• --dry-run previews removal.
• VS Code removal covers the default user profile; use MCP: Open User Configuration for other profiles.

Command discovery

mercator clients
mercator --help
mercator --llms

The CLI uses Incur for validated options, generated help, machine-readable manifests, structured errors, shell completions, and agent integrations.