npm package: @moltbankhq/cli
Description: MoltBank JSON-first CLI with direct MCP calls and local stdio MCP bridge
Latest version: 0.1.0

# @moltbankhq/cli

Canonical MoltBank CLI (JSON-first) for [MoltBank](https://moltbank.bot).

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

## Install

```bash
npm install -g @moltbankhq/cli
```

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:

```bash
npx @moltbankhq/cli login
```

Or from a local install:

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

## What it does

This CLI provides:

- Human-run OAuth login with local credential storage (`~/.MoltBank/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:

```bash
moltbank login
```

Agent/chat-driven flow:

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

Then verify readiness:

```bash
moltbank auth status --json
moltbank doctor --json
```

## 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 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 |
| `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:

```bash
moltbank schema --json
```

Command-level discovery:

```bash
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:

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

## Configuration

Core flags:

```bash
moltbank auth begin --app-base-url https://app.moltbank.bot --credentials-path ~/.MoltBank/credentials.json --json
```

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

```bash
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`.

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

```bash
# .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` | Override local credentials file path |

## 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](https://moltbank.bot)
- [Documentation](https://app.moltbank.bot)
- [GitHub](https://github.com/moltbankhq)

## License

MIT