CLI Reference

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.

Global install

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

Commands and options

$ mppx --help

[email protected] — Make HTTP requests with automatic payment handling

Usage: mppx <url> [options]

Arguments:
  url  URL to make request to

Options:
  --account, -a <string>       Account name (env: MPPX_ACCOUNT)
  --auto-swap                  Auto-swap source tokens into payment currency
  --config, -c <string>        Path to config file
  --confirm                    Show confirmation prompts
  --currency <string>          Payment currency/token address to select
  --data, -d <string>          Send request body (implies POST unless -X is set)
  --fail, -f                   Fail silently on HTTP errors (exit 22)
  --header, -H <array>         Add header (repeatable)
  --include, -i                Include response headers in output
  --insecure, -k               Skip TLS certificate verification (true for localhost/.local)
  --json-body, -J <string>     Send JSON body (sets Content-Type and Accept, implies POST)
  --location, -L               Follow redirects
  --method, -X <string>        HTTP method
  --method-opt, -M <array>     Method-specific option (key=value, repeatable)
  --network <mainnet|testnet>  Tempo network
  --pay-with <string>          Source token for Tempo auto-swap
  --protocol <auto|mpp|x402>   Payment protocol to use (default: auto)
  --rpc-url, -r <string>       RPC endpoint, defaults to public RPC for chain (env: MPPX_RPC_URL)
  --session <string>           Session selection: auto, new, or channel ID (default: auto)
  --silent, -s                 Silent mode (suppress progress and info)
  --slippage <number>          Tempo auto-swap max slippage percentage
  --user-agent, -A <string>    Set User-Agent header (default: mppx/0.10.1)
  --verbose, -v <count>        Verbosity (-v details, -vv headers) (default: 0)

Examples:
  mppx mpp.dev/api/ping/paid  # Make a payment request

Commands:
  account   Manage accounts (create, default, delete, export, fund, list, view)
  discover  Discovery tooling
  init      Create an mppx.config.ts file in the current directory
  services  Browse the MPP services registry
  sessions  Manage persistent payment sessions (list, view, close)
  sign      Sign a payment challenge and output the Authorization header
  validate  Validate an MPP server implementation end-to-end

Integrations:
  completions  Generate shell completion script
  mcp          Register as MCP server (add, doctor)
  skills       Sync skill files to agents (add, list)

Global Options:
  --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
  --format <toon|json|yaml|md|jsonl>  Output format
  --full-output                       Show full output envelope
  --help                              Show help
  --llms, --llms-full                 Print LLM-readable manifest
  --mcp                               Start as MCP stdio server
  --schema                            Show JSON Schema for command
  --token-count                       Print token count of output (instead of output)
  --token-limit <n>                   Limit output to n tokens
  --token-offset <n>                  Skip first n tokens of output
  --update                            Update to latest version
  --version                           Show version

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:

$ 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.

$ mppx validate https://api.example.com

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

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

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.

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

Method options

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

$ 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.

$ mppx account list --format 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:

$ mppx init

Use --force to overwrite an existing config file:

$ 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.

import { defineConfig, resolveAccount } from 'mppx/cli'
import { tempo } from 'mppx/client'
 
export default defineConfig({
  methods: [tempo({
    account: await resolveAccount(),
    allowedChainIds: [4217], // Tempo mainnet
  })],
})

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.

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.

$ 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:

$ mppx sign --challenge "$challenge" --dry-run

Account commands

Manage local keychain-backed accounts with mppx account.

$ 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:

$ mppx account export --account main

Stripe payments

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

$ export MPPX_STRIPE_SECRET_KEY=sk_test_...
$ mppx https://example.com/content

Pass method-specific options with -M:

$ mppx https://example.com/content -M paymentMethod=pm_card_visa

Agent integration

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

$ mppx mcp add

Sync skill files to your agent's skill directory:

$ mppx skills add

Generate shell completions:

$ mppx completions