> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://mpp.dev/api/mcp` to find what you need.

# CLI Reference \[Built-in command-line tool for paid HTTP requests]

The `mppx` package includes a bundled CLI runtime for making HTTP requests with automatic MPP and x402 payment handling. Published packages omit the CLI source files and source maps.

## Usage

The `mppx` CLI is bundled with the package.

:::code-group
```bash [npm]
$ npx mppx example.com
```

```bash [pnpm]
$ pnpm mppx example.com
```

```bash [bun]
$ bunx mppx example
```
:::

### Global install

To use the `mppx` CLI outside of a project, install globally.

:::code-group
```bash [npm]
$ npm install -g mppx
$ mppx example.com
```

```bash [pnpm]
$ pnpm add -g mppx
$ mppx example.com
```

```bash [bun]
$ bun add -g mppx
$ mppx example.com
```
:::

## Commands and options

:::terminal
```bash [terminal]
$ mppx --help
```

```txt
// [!include ~/snippets/cli-help.txt]
```
:::

## Choose a payment protocol

Keep the default `--protocol auto` for most requests. The CLI prefers MPP when the server offers both protocols and uses x402 when MPP isn't available.

Require one protocol when testing an integration or refusing the other protocol:

```bash [terminal]
$ mppx https://api.example.com/paid --protocol x402
$ mppx https://api.example.com/paid --protocol mpp
```

x402 payments support compatible EVM `exact` Challenges and use the same account as EVM charge payments. Configure it with `--account`, `MPPX_ACCOUNT`, or `MPPX_PRIVATE_KEY`.

## Validate command

Use `mppx validate` to automatically verify an MPP server implementation end-to-end. The command tests `/llms.txt`, OpenAPI discovery, Challenge formats, error handling, and the full payment flow. A missing, empty, or non-text `/llms.txt` appears as a non-blocking `suggested` result.

```bash [terminal]
$ mppx validate https://api.example.com
```

To test a specific route that needs request data, pass a body or query parameters:

```bash [terminal]
$ mppx validate https://api.example.com --endpoint POST:/reports --body '{"format":"csv"}'
$ mppx validate https://api.example.com --endpoint GET:/quotes --query symbol=ETH
```

:::note[End-to-end payments]
Run `mppx validate` against both test and production versions of your server. On testnets and Stripe test mode, the CLI automatically completes roundtrip test payments. On mainnets, the CLI can complete real payments from the local `mppx` wallet.
:::

When your config declares payment methods, `mppx validate` uses their signing accounts, approval hooks, chain policies, and Session stores instead of substituting built-in methods or preflighting the local CLI wallet.

### Programmatic validation

Import `validate` from `mppx/validation` when you need structured results.

```ts twoslash [validate.ts]
import { validate } from 'mppx/validation'

const result = await validate({
  skipPayment: true,
  url: 'https://api.example.com',
})

console.log(result.summary.suggested)
```

The `summary` contains `failed`, `passed`, `skipped`, `suggested`, and `warnings` counts. Individual checks use the matching `severity`, including `'suggested'` for optional improvements such as publishing `/llms.txt`. Suggested checks don't make validation fail.

## Environment variables

| Variable | Description |
|----------|-------------|
| `MPPX_ACCOUNT` | Default account name |
| `MPPX_CONFIG` | Path to an `mppx.config.ts`, `mppx.config.js`, or `mppx.config.mjs` file |
| `MPPX_PRIVATE_KEY` | Use a private key directly instead of the keychain |
| `MPPX_RPC_URL` | Default RPC endpoint |
| `MPPX_STRIPE_SECRET_KEY` | Stripe secret key for Stripe payment methods (test mode only: `sk_test_...`) |
| `MPPX_STRIPE_SPT_URL` | Custom Stripe shared payment token endpoint (advanced) |

## Method options

Pass method-specific key-value pairs with `-M` (repeatable):

```bash [terminal]
$ mppx example.com/content -M deposit=1
$ mppx example.com/content -M allowCustomEscrow=true
```

For Tempo Session payments, `deposit` sets the maximum deposit in token units: `1` means one token, not one base unit. To reuse a channel, pass `-M channel=<channel-id>` with the full channel ID returned when it was opened. Omit `channel` to let the SDK open one. The CLI accepts only the canonical reserve contract by default; pass `allowCustomEscrow=true` only when you trust the server's custom deployment. For Stripe, use `paymentMethod`.

## JSON output

Pass `--format json` to commands that support structured output. This is useful when another tool calls `mppx`.

```bash [terminal]
$ mppx account list --format json
```

```json
{
  "accounts": [
    {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "isDefault": true,
      "name": "main"
    }
  ]
}
```

## Streaming output

The CLI writes response body chunks as they arrive. SSE messages and other streamed responses appear without waiting for the response to close.

## Init command

Create an `mppx.config.*` file in the current directory. The CLI uses `.ts` when it finds `tsconfig.json`, `.mjs` for an ESM package, and `.js` otherwise:

```bash [terminal]
$ mppx init
```

Use `--force` to overwrite an existing config file:

```bash [terminal]
$ mppx init --force
```

### Configure payment methods

The CLI loads configuration from `--config`, then `MPPX_CONFIG`, then the nearest `mppx.config.ts`, `mppx.config.js`, or `mppx.config.mjs` file up to the project root.

```ts twoslash [mppx.config.ts]
import { defineConfig, resolveAccount } from 'mppx/cli'
import { tempo } from 'mppx/client'

export default defineConfig({
  methods: [tempo({
    account: await resolveAccount(),
    allowedChainIds: [4217], // Tempo mainnet
  })],
})
```

| Property | Type | Description |
|----------|------|-------------|
| `extensions` | `readonly Extension.Extension[]` | Ordered payment lifecycle hooks that run before Credential creation |
| `methods` | `Method.AnyClient[]` | Client payment methods, including third-party methods |
| `paymentPreferences` | `PaymentPreferences` | Selection preferences when a server offers multiple methods |
| `plugins` | `Plugin[]` | CLI integrations that configure payment methods and output |

Configured methods remain authoritative throughout payment selection, retries, and Session voucher renewal. The CLI preserves their Challenge ordering, signing policy, chain allowlists, and channel stores.

### Configure payment extensions

Use extensions to enforce policy or prepare funds after the CLI selects and confirms a Challenge, immediately before it creates a Credential.

```ts twoslash [mppx.config.ts]
import { defineConfig, Extension } from 'mppx/cli'

export default defineConfig({
  extensions: [
    Extension.from({
      preparePayment({ challenge }) {
        if (challenge.realm !== 'api.example.com')
          throw new Error(`Payment blocked for ${challenge.realm}`)
      },
    }),
  ],
})
```

Extensions run in configuration order for paid requests, `mppx sign`, `mppx validate`, and persistent Sessions. Throw to reject payment. Return `{ credentialContext }` to replace the method-specific context passed to the next extension and Credential creation.

## Sign command

Sign a payment Challenge and output its serialized Payment Credential value without making a request. Pass the complete `WWW-Authenticate` value with `--challenge`. Send the result in the field advertised by `header`, or `Authorization` when omitted.

```bash [terminal]
$ challenge='Payment id="abc", realm="api.example.com", method="tempo", intent="charge", request="eyJhbW91bnQiOiIwIiwiY3VycmVuY3kiOiIweDIwYzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJyZWNpcGllbnQiOiIweDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIn0"'
$ mppx sign --challenge "$challenge"
```

Use `--dry-run` to validate and parse a Challenge without signing:

```bash [terminal]
$ mppx sign --challenge "$challenge" --dry-run
```

## Account commands

Manage local keychain-backed accounts with `mppx account`.

```bash [terminal]
$ mppx account create --account main
$ mppx account default --account main
$ mppx account list
$ mppx account view --account main
```

Export a local account private key when you need to import it into another wallet or tool:

```bash [terminal]
$ mppx account export --account main
```

:::warning
`mppx account export` prints the private key. Don't commit it, paste it into shared logs, or use it in client-side code.
:::

## Stripe payments

The CLI supports Stripe payment methods. Set your Stripe test-mode secret key and make requests to Stripe-enabled endpoints.

```bash [terminal]
$ export MPPX_STRIPE_SECRET_KEY=sk_test_...
$ mppx https://example.com/content
```

Pass method-specific options with `-M`:

```bash [terminal]
$ mppx https://example.com/content -M paymentMethod=pm_card_visa
```

## Agent integration

Register `mppx` as an MCP server for use with coding agents:

```bash [terminal]
$ mppx mcp add
```

Sync skill files to your agent's skill directory:

```bash [terminal]
$ mppx skills add
```

Generate shell completions:

```bash [terminal]
$ mppx completions
```