Skip to content
EPP-402

Developers · CLI

epp402, every command.

One binary for the whole protocol: scaffold a provider, run the local stack, inspect a provider or a header, play the lifecycle, publish, query the registry, verify receipts and diagnose a setup. Every command works against the local stack and against the testnet.

Running it

terminalRepository
# Inside the repository, build once and use the linked binary:
pnpm build
pnpm exec epp402 --help

# Or run the TypeScript source directly, no build:
pnpm --filter @epp402/cli dev -- doctor

The package is not yet published to npm; npx @epp402/cli is the intended form once it is. .env files are read from the working directory upward, so a repository-root .env serves every package. Keys are never printed; doctor masks them.

Global option
1
  • --network <id>

    local | elysium-testnet

    The network. Otherwise NETWORK from the environment decides; the default is local.

Commands

Purpose and options of each command, as registered in the CLI.

Commands
13
  • init [dir]

    --name, --provider-id, --url, --network

    Scaffold a provider project: package.json, tsconfig.json, .env.example, src/server.ts, README.md. Defaults: My Provider, provider.example.com, http://127.0.0.1:4021, elysium-testnet.
  • dev

    --port (8402), --facilitator-port (4020), --facilitator-url, --provider-port (4021), --block-time (1), --quiet

    Start the local stack: anvil, the contracts deployed with the Foundry script, a facilitator on the anvil facilitator key (or an existing one with --facilitator-url), a demo provider with text.analyze and echo. Writes .data/local-stack.json. Needs Foundry and the repository.
  • inspect <target>

    --no-probe, --json

    A provider URL prints the discovery document, its signature check, the service table and a 402 probe per service. A base64 header value decodes PAYMENT-REQUIRED, PAYMENT-SIGNATURE, PAYMENT-RESPONSE or EPP-RECEIPT.
  • simulate

    --provider, --service, --params, --limit (1), --registry, --json

    The full lifecycle as an agent: discover, open a session, quote, pay through x402, verify the receipt against the chain, complete the session. Local stack by default; on a public network it needs --provider or PROVIDER_URL and AGENT_PRIVATE_KEY.
  • publish --url <providerUrl>

    --registry, --onchain, --no-registry-publish

    Ask the registry to crawl the provider; with --onchain, register or update it in EPP402Registry with PROVIDER_PRIVATE_KEY (must be the document's provider address, needs gas).
  • registry providers

    --category, --q, --registry, --json

    Indexed providers.
  • registry services

    --category, --q, --registry, --json

    Indexed services.
  • registry provider <providerId>

    --registry

    One provider as JSON, with its document and services.
  • registry stats

    --registry

    /v1/stats and /v1/network.
  • receipts verify <source>

    --offline, --rpc, --provider

    Verify a receipt from a .json file, stdin (-) or an EPP-RECEIPT header value: schema, signature, and the chain unless --offline. Exit code 1 when invalid.
  • session show <sessionId>

    --registry, --json

    A published session: totals, items, history, and how many quotes, intents, settlements and receipts the registry holds for it.
  • session list

    --buyer, --status, --registry

    Published sessions.
  • doctor

    --registry, --facilitator

    Node and Foundry versions, repository, network and RPC head, deployment manifest, each configured key (address, masked key, gas balance, refusal of published test keys on public chains), facilitator and registry health. Exit code 1 on failures.

A local session

terminalRepository
pnpm exec epp402 dev                       # terminal 1: anvil 8402, contracts, facilitator 4020, demo provider 4021
pnpm exec epp402 simulate                  # terminal 2: quote, tx hash, receipt verification, session state
pnpm exec epp402 simulate --service echo --params '{}' --json
pnpm exec epp402 inspect http://127.0.0.1:4021
pnpm exec epp402 receipts verify receipt.json --rpc http://127.0.0.1:8402
pnpm exec epp402 doctor

Configuration

Environment variables the CLI reads.

Environment
6
  • NETWORK, ELYSIUM_TESTNET_RPC_URL, LOCAL_RPC_URL, RPC_URL

    network resolution

    Which chain, and which RPC endpoint to use for it (@epp402/elysium).
  • EPP402_API_URL or NEXT_PUBLIC_API_URL

    registry commands

    Registry base URL, default http://127.0.0.1:4402.
  • FACILITATOR_URL

    doctor

    Facilitator base URL, default <registry>/facilitator.
  • PROVIDER_URL, AGENT_PRIVATE_KEY

    simulate on a public network

    The provider to buy from and the key that pays.
  • PROVIDER_PRIVATE_KEY

    publish --onchain

    The provider key that owns the registration.
  • DEPLOYER_PRIVATE_KEY, FACILITATOR_PRIVATE_KEY

    doctor

    Reported with their addresses and gas balances; never printed.