Peer Pay CLI

Test Peer Pay locally and manage your merchant account from the terminal. Requires Node.js 22 or newer.

npm install -g @zkp2p/peer-pay-cli

Run peer-pay-cli in a terminal for the interactive menu. Without a terminal, no command prints help to stderr and exits 2.

Test locally

Start the mock backend in one terminal:

peer-pay-cli serve --state ./peer-pay.json

In another terminal, register your local webhook handler and create an order:

peer-pay-cli --local webhooks create --url http://localhost:3000/webhooks/peer-pay --events ORDER_FULFILLED
peer-pay-cli --local orders create --amount 10
peer-pay-cli --local payments create ORDER_ID --rail venmo
peer-pay-cli --local simulate ORDER_ID --event PAYMENT_SETTLED
peer-pay-cli --local status

Replace ORDER_ID with the returned order ID. The mock listens on 127.0.0.1:4020; your webhook handler stays on localhost. No account, database, or tunnel is needed. The mock serves API endpoints only. No money moves.

Set up your merchant

peer-pay-cli login --email [email protected]
peer-pay-cli setup

Enter the email verification code, answer the setup questions, and review the changes before applying them. The same CLI manages payment settings, webhooks, team invitations, API keys, and hosted sandbox tests.

Email sessions refresh only for management requests when the saved access token is missing or expired, or once after a 401. API-key commands and credentials export do not contact Privy. A management request performs at most one refresh.

Setup requires a hosted profile and offers inline sign-in in a terminal. For scripts, use peer-pay-cli setup --file setup.json --dry-run or --yes after signing in. Run peer-pay-cli sandbox enable to enable, save, and activate the remote sandbox profile in one step.

Continue with a coding agent

peer-pay-cli handoff --harness codex --project ./my-store --launch

Supports Codex, Claude Code (claude), OpenCode (opencode), and Gemini CLI (gemini). Install your chosen agent separately. In a terminal, peer-pay-cli handoff asks for the agent, project directory, and whether to launch. Use --harness prompt for instructions only. In scripts, omit --launch to save instructions without launching. You can also pass --harness, --project, and --launch to setup to continue with the agent after applying your merchant settings. Handoff prompts contain profile references, not credentials.

Help

peer-pay-cli --help
peer-pay-cli orders --help
peer-pay-cli orders create --help

Login names and activates your merchant profile automatically; --profile NAME can name it explicitly. After login, commands target your Peer Pay account. Add --local to target the mock, or run peer-pay-cli use local. Selection is --profile NAME > --local > active profile > saved local. profiles marks the active profile; status reports profile and mode; logout clears the active selection when removing that profile. Serve never changes the active profile. --json returns structured output; piped output is JSON automatically. Credentials are redacted by default. Export them directly to a new private file:

peer-pay-cli credentials export --output .env.peer-pay --webhook-id WEBHOOK_ID

Keep exported credentials and local state out of version control.

Signing in again replaces the profile's API key with the server-authorized key. If the server withholds the key (for example, for a cashier), saved API keys, order tokens, and webhook secrets are cleared. Removing cached credentials does not revoke previously copied merchant keys; revoke them by rotating the merchant key.

• Local testing guide
• Merchant setup
• Command reference
• Webhook verification

Develop from this repository

npm run dev:peer-pay-cli -- --help
npm run build:peer-pay-cli
npm --workspace apps/peer-pay-cli run test
npm --workspace apps/peer-pay-cli run typecheck
npm --workspace apps/peer-pay-cli run lint
npm pack --workspace apps/peer-pay-cli

The npm artifact bundles the local server and installs the official Privy SDK for hosted authentication. It does not require repository files after installation.