@moltbankhq/cli

Canonical Moltbank CLI (JSON-first) for Moltbank.

Legacy plugin runtime mode is removed. Use CLI commands and/or the local MCP stdio bridge.

Install

npm install -g @moltbankhq/cli@<version>

Plain npm install @moltbankhq/cli installs the package locally in the current directory, but it does not put moltbank on your interactive shell PATH.

You can also run it without a global install:

npx @moltbankhq/cli login

Or from a local install:

npm exec --package @moltbankhq/cli -- moltbank login

What it does

This CLI provides:

• Human-run OAuth login with local credential storage (~/.moltbank/agents/default/credentials.json by default)
• Agent-safe split OAuth flow (auth begin + auth poll) with local pending session state
• JSON-first operational commands for reliable agent parsing
• Direct MCP JSON-RPC tool calls over Streamable HTTP (/api/mcp)
• Local MCP stdio bridge (moltbank mcp stdio) with a narrow initial toolset
• Local diagnostics via moltbank doctor

Setup

After installing, run one of these auth flows:

Human terminal flow:

moltbank login

Agent/chat-driven flow:

moltbank auth begin --json
# user approves in browser
moltbank auth poll --json

Then verify readiness:

moltbank auth status --json
moltbank doctor --json

Trusted Update-Required Errors

When Moltbank-controlled MCP responses require an update, the CLI preserves the structured error contract in JSON mode instead of collapsing to a generic error.

Example:

{
  "ok": false,
  "error": {
    "code": "CLI_UPDATE_REQUIRED",
    "component": "cli",
    "message": "Your Moltbank CLI is out of date.",
    "officialUpdateCommand": "npm install -g @moltbankhq/[email protected]",
    "currentVersion": "0.1.1",
    "requiredVersion": "0.1.2",
    "retryableAfterUpdate": true
  }
}

Supported trusted update codes:

• CLI_UPDATE_REQUIRED
• VERSION_MISMATCH

The CLI never auto-runs update commands. It only surfaces the official command provided by Moltbank.

CLI Commands

| Command | Description | |---------|-------------| | moltbank login | Start blocking OAuth device login and save local credentials (human convenience alias of auth login) | | moltbank auth login | Start blocking OAuth device login and save local credentials (human-style wrapper) | | moltbank auth begin --json | Start a pending OAuth session and return URL/code immediately | | moltbank auth poll --json | Poll current/specified pending OAuth session once | | moltbank auth pending --json | List pending OAuth sessions from local state | | moltbank auth cancel --session-id <id> --json | Cancel a pending OAuth session | | moltbank auth status --json | Check local auth readiness | | moltbank agent setup --name "agent-alpha" --json | Provision one local agent profile (OAuth + local x402 signer) | | moltbank agent list --json | List local agent profiles under ~/.moltbank/agents/* | | moltbank agent remove --name "agent-alpha" --json | Remove local agent profile files (does not revoke backend token) | | moltbank tools list --json | List canonical Moltbank tool names/aliases from manifest | | moltbank schema --json | Discover all command contracts and global flags | | moltbank schema <command> --json | Discover one command contract (for example schema auth begin --json) | | moltbank whoami --json | Show active organization and local agent identity (agentId, agentLabel) | | moltbank doctor --json | Validate local credentials + backend MCP reachability | | moltbank balance --org "Acme" --json | Read balances via direct MCP call | | moltbank approvals list --json | List pending approvals | | moltbank propose-transaction --org "Acme" --account "Main" --amount 500 --recipient-address "0x..." --json | Propose a payment to an external contact on Base | | moltbank x402 auto-pay --org "Acme" --account "Main" --url "https://..." --method GET --json | Run full x402 flow (signer, registration, inspect, funding, pay, receipt). If transfer budget is missing/inactive, auto-creates a budget approval proposal and returns its link. If LI.FI gas route is not pre-authorized, returns gas top-up approval proposals. | | moltbank x402 discover --query-x402 weather --limit 5 --json | Discover payable x402 Bazaar endpoints (--query also works as an alias) | | moltbank x402 signer init --json | Generate/reuse local x402 signer key for active organization | | moltbank x402 wallet register --wallet-address "0x..." --json | Register the bot-owned Base wallet for x402 budget pre-authorization | | moltbank x402 inspect --url "https://..." --json | Inspect x402 payment requirements | | moltbank x402 pay --url "https://..." --method GET --json | Execute x402 payment with local signer | | moltbank mcp call --tool <name> --arg k=v --body '{"key":"value"}' --json | Call an MCP tool directly (debug/fallback path) | | moltbank mcp stdio | Start local MCP stdio server for structured agent tool usage |

Initial tools exposed by mcp stdio:

• moltbank_auth_begin
• moltbank_auth_poll
• moltbank_auth_pending
• moltbank_auth_cancel
• moltbank_get_balance
• moltbank_list_pending_approvals
• moltbank_propose_transaction
• moltbank_doctor
• moltbank_whoami
• moltbank_x402_init_signer
• moltbank_register_x402_wallet
• moltbank_x402_auto_pay
• moltbank_discover_x402_bazaar
• moltbank_x402_inspect
• moltbank_x402_pay
• moltbank_call_mcp_tool_debug (debug fallback)

CLI Schema Discovery

Top-level discovery:

moltbank schema --json

Command-level discovery:

moltbank schema balance --json
moltbank schema auth begin --json
moltbank schema propose-transaction --json
moltbank schema x402 pay --json

Discovery Guard For Writes

For JSON/agent workflows, write commands enforce discovery-before-execution:

1. moltbank schema --json
2. moltbank schema <write-command> --json
3. execute the write command

Example:

moltbank schema propose-transaction --json
moltbank propose-transaction --org "Acme Corp" --account "Main" --amount 500 --recipient-address "0x..." --json

Configuration

Core flags:

export MOLTBANK_CREDENTIALS_PATH=~/.moltbank/agents/default/credentials.json
moltbank auth begin --app-base-url https://app.moltbank.bot --json

Preview/dev override (explicit and Moltbank-scoped):

export MOLTBANK_CUSTOM_API_URL="https://preview.app.moltbank.bot"
moltbank login

When a non-production URL is used, the CLI prints a security warning to stderr.

Multi-agent profiles

Default profile path:

~/.moltbank/agents/default/credentials.json

If you upgrade from a legacy single-profile install (~/.moltbank/credentials.json), the CLI auto-migrates local state into ~/.moltbank/agents/default/ on startup.

Create a second local profile:

moltbank agent setup --name "agent-beta" --json

Run separate MCP bridges per agent by setting MOLTBANK_CREDENTIALS_PATH per process.

To avoid accidental default-profile usage, most commands now require MOLTBANK_CREDENTIALS_PATH to be set in the terminal session.

Local web app development (from your web app repo):

# .env (web app repo)
APP_BASE_URL="http://localhost:3000"

# terminal using the CLI
export MOLTBANK_CUSTOM_API_URL="http://localhost:3000"
moltbank login
moltbank doctor --json

Host-based skill source used by the web app:

• localhost/127.0.0.1 (development): local skill files via local proxy.
• preview.app.moltbank.bot: moltbank-skill preview branch.
• production hosts: moltbank-skill main branch.

Environment Variables

| Variable | Description | |----------|-------------| | MOLTBANK_CUSTOM_API_URL | Optional non-production API URL override for explicit preview/dev testing | | MOLTBANK_CREDENTIALS_PATH | Credentials file path used by the current terminal session (required for most commands) | | MOLTBANK_ENFORCE_DISCOVERY | Override schema-discovery enforcement (true/false). When enabled, write commands require prior schema discovery. Defaults to matching --json mode. | | MOLTBANK_ALLOW_PRIVATE_X402_URLS | DEV ONLY — do not set in production. Disables the x402 SSRF guard so x402 inspect / x402 pay / x402 auto-pay can target localhost, 127.0.0.1, RFC1918/private IPs, and reserved hostnames (*.localhost, *.local, *.home.arpa, cloud-metadata endpoints). Without this flag, those targets are rejected before any network I/O. Accepted values: 1 / true / yes. Anything else leaves the guard enabled. Use only when running a trusted x402 server on your own machine for development. |

Capabilities

The Moltbank skill gives your agent access to:

• Treasury management — balances, transfers, account operations
• Per-agent spending limits — transaction, daily, and weekly caps
• Approval workflows — human-in-the-loop for spend above thresholds
• x402 payments — agent-to-agent payments via the x402 protocol
• Audit trails — full visibility into which agent spent what, when, and why

Requirements

• Node.js 22+

Links

• Moltbank
• Documentation
• GitHub

License

MIT