@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 auth begin --name "agent-alpha" --json

Or from a local install:

npm exec --package @moltbankhq/cli -- moltbank auth begin --name "agent-alpha" --json

What it does

This CLI provides:

• Resumable OAuth activation with local credential storage (~/.moltbank/agents/default/credentials.json by default)
• Agent-safe split OAuth flow (auth begin + auth poll) with pending signer state and idempotent backend wallet registration
• 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:

Agent/chat-driven flow:

moltbank auth begin --name "agent-alpha" --json
# user approves in browser
MOLTBANK_CREDENTIALS_PATH="..." moltbank auth poll --session-id "..." --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 auth begin --name "agent-alpha" --json | Start a pending OAuth session, pre-stage local EVM + Solana signer addresses, and return URL/code immediately | | moltbank auth poll --session-id <id> --json | Finalize auth, create/reuse missing local signers, and register backend EVM + Solana wallets using the default activation audit intent | | 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 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 auth begin --name "agent-alpha" --json

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 auth begin --name "agent-beta" --json
# user approves in browser
MOLTBANK_CREDENTIALS_PATH="..." moltbank auth poll --session-id "..." --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 auth begin --name "agent-alpha" --json
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.

Local Development

Working on the CLI itself, or on a mod under packages/*-mod/, requires pointing the CLI at a local backend, a local mods directory, and a test-mode credentials home — all explicit, all overridable. Here's what each env var is for and why you can't skip any one of them.

Quickstart (full local stack)

# 1. Clone + install dependencies
npm install

# 2. Symlink local mods into a dev mods directory
npm run dev:link-mods

# 3. Set the dev env vars in your shell session
export MOLTBANK_CUSTOM_API_URL="http://localhost:3000"
export MOLTBANK_MODS_DIR="$(pwd)/.moltbank-dev/mods"
export MOLTBANK_LOCAL_TEST_MODE=1
export MOLTBANK_CREDENTIALS_PATH="$HOME/.moltbank-test/agents/<your-test-agent>/credentials.json"

# 4. Sanity-check
moltbank doctor --json
moltbank mod list --json

What each piece does

The setup glues together four orthogonal concerns. Each env var has exactly one job; failure modes are documented so you can debug if any one is missing:

1. Which backend the CLI talks to

export MOLTBANK_CUSTOM_API_URL="http://localhost:3000"

Default is https://app.moltbank.bot (production). The mod registry URL is derived from this as ${MOLTBANK_CUSTOM_API_URL}/api/mods. Without an override, every auth begin registers the device-code against production's database (unreachable from a localhost test setup) and every mod install pulls from production's registry (which won't have your locally-developed mod).

The CLI prints [SECURITY WARNING] lines on stderr whenever it's pointed at a non-production base URL — intentional friction so you don't forget you're in dev mode.

2. Where the CLI looks for installed mods

export MOLTBANK_MODS_DIR="$(pwd)/.moltbank-dev/mods"

Default is ~/.moltbank/mods/<name>/. Pointing this at the in-repo .moltbank-dev/mods/ directory isolates your dev mods from anything globally installed. The npm run dev:link-mods script populates that directory.

3. The trust gate

No env var needed. Manifest signatures are not enforced — the trust gate runs in v1-no-crypto mode by default. Trust is via TLS to the registry, npm scope ownership with 2FA, and SRI integrity verification at install. See mod-registry-trust-decision-v1.md (on the operator desk) for the full rationale.

Optional verbose flag:

export MOLTBANK_VERBOSE_MOD_WARNINGS=1   # logs per-mod trust-gate decisions

By default per-mod "signature.value is empty" warnings are suppressed in dev-root mode (they polluted --json piped output). Set this to bring them back.

4. Which agent identity is active

export MOLTBANK_LOCAL_TEST_MODE=1
export MOLTBANK_CREDENTIALS_PATH="$HOME/.moltbank-test/agents/<agent-name>/credentials.json"

MOLTBANK_LOCAL_TEST_MODE=1 switches the credentials home from ~/.moltbank/ to ~/.moltbank-test/ and adds visible warnings on every command — keeps test funds from mixing with production keys.

MOLTBANK_CREDENTIALS_PATH selects which test agent is active. Each auth begin / auth poll cycle creates one credentials file under ~/.moltbank-test/agents/<name>/credentials.json. Most write commands refuse to execute without an explicit path set (deliberate — prevents accidentally trading against the wrong agent).

dev:link-mods script

dev:link-mods is a source-repo helper, not a moltbank command. It does three things:

1. Runs npm link for the root Moltbank CLI package so moltbank resolves to your in-tree CLI binary.
2. Runs npm link for each local mod package under packages/*-mod/ so each mod's bin/<binary> is on PATH.
3. Mirrors each mod's moltbank.mod.json + supporting files into .moltbank-dev/mods/<mod-name>/ so the host CLI can discover them.

By default the mirror uses symlinks for fast iteration — edits to packages/<mod>/... are immediately visible to the linked mod. There's no build step (we use tsx for runtime TypeScript).

npm run dev:link-mods            # symlinks (fast iteration, default)
npm run dev:link-mods -- --copy  # real copies + chmod 0o444 on each manifest

Use --copy whenever the mods directory will be exposed to a separate process you don't fully trust (sub-agent harnesses, CI sandboxes, security-testing runners). It does a real cp -r --dereference and chmods each moltbank.mod.json to 0o444 so a misbehaving runner can't silently rewrite tier, signature, minCliVersion, or permissions to bypass a mod doctor check. Re-run with --copy whenever you want to pick up source changes — the script rmSync's the target before re-mirroring, so the readonly bit doesn't block re-runs.

Sub-agent / sandbox runners

If you're handing the CLI off to a sub-process — a Claude Code sub-agent, a CI test runner, an automated harness — set ALL six dev env vars in the spawn so the sub-process can't accidentally talk to production. The full quickstart block above is the canonical setup. A few extra notes for sandbox use:

• Pair dev:link-mods --copy with a neutral target directory (not the in-tree .moltbank-dev/mods/) so a curious sub-agent can't walk symlinks back into your source tree.
• Pre-mint the test agent's credentials before spawning. Sub-agents can't run auth begin interactively because OAuth needs a real browser. The pattern: set up <agent-name> once via the host's auth flow, then point sub-agents at that agent's credentials file via MOLTBANK_CREDENTIALS_PATH.
• If you need the agent to NOT see your source code (e.g., when testing whether SKILL.md + --help is enough), pair --copy + the neutral target dir + an explicit instruction in the sub-agent prompt.

Building a new mod

For everything mod-specific (manifest format, the parseModArgs convention, custom verbs, streaming verbs, anti-patterns, testing), see docs/mod-developer-guide.md.

For SDK API reference: docs/mod-sdk.md. For the threat model + what mods can't do: docs/mod-security.md. For production manifest signing: docs/canonical-signing.md.

Environment Variables

| Variable | Description | |----------|-------------| | MOLTBANK_CUSTOM_API_URL | Optional non-production API URL override for explicit preview/dev testing. Defaults to https://app.moltbank.bot. | | MOLTBANK_CREDENTIALS_PATH | Credentials file path used by the current terminal session (required for most commands) | | MOLTBANK_MODS_DIR | Optional mods directory override. Use this for local mod development, for example $(pwd)/.moltbank-dev/mods. When the mods dir will be exposed to an untrusted runner, point this at a neutral path populated by dev:link-mods --copy rather than the in-tree .moltbank-dev/mods/. | | MOLTBANK_MODS_ALLOW_DEV_ROOT | No-op in v1 — retained so older dev workflows that still export it don't error. v1 ships with cryptographic trust enforcement dormant; tier:official mods install + run without any env-var bypass. The flag still disables the post-run cross-mod-write audit (which produces false positives when source files are edited mid-run during dev iteration). v1.5 will re-enable trust enforcement; at that point this flag will resume its original purpose of permitting unsigned dev-linked mods. | | MOLTBANK_LOCAL_TEST_MODE | Set to 1 to switch the credentials home from ~/.moltbank/ to ~/.moltbank-test/ and surface visible test-mode warnings on every command. Critical for keeping test funds separate from production keys. Required when running against a local moltbank-app server. | | MOLTBANK_VERBOSE_MOD_WARNINGS | Set to 1 to surface the per-mod "signature.value is empty" deprecation banner in dev-root mode. Suppressed by default to keep --json piped output clean. Useful when debugging manifest-signing issues. | | 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