mercator-cli

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:

• Existing Mercator-authorized Tempo Wallet access key.
• Existing Mercator local disk wallet.
• 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.