postbox-agent CLI

postbox-agent is the command-line client for PieterPost MCP. It lets an authenticated PieterPost user send one-off letters and postcards through hosted payment links, while still exposing the API-key, credit-wallet, Mailbook, upload, and generic MCP tool paths.

The separate pieterpost npm package is a thin alias that exposes the same implementation under the PieterPost brand name.

Install

npm install -g postbox-agent
postbox-agent login

When published, these are equivalent entry points:

npx postbox-agent help
npx pieterpost help

For local development from this repo:

pnpm --filter postbox-agent typecheck
pnpm --filter postbox-agent build
node packages/postbox-agent-cli/dist/index.js help

Default User Flow

The default CLI flow is one-off sending:

1. The user runs postbox-agent login.
2. The CLI opens PieterPost OAuth in the browser and stores the MCP token locally.
3. The user runs postbox-agent letter ... or postbox-agent postcard ....
4. The CLI resolves the recipient, uploads any local assets, and creates a hosted payment link.
5. For a quote-and-confirm flow, the user can run postbox-agent send letter ... or postbox-agent send postcard ....
6. The user pays in the browser.
7. PieterPost creates and sends the letter or postcard after successful payment.

The CLI defaults the hosted checkout return page to a customer-facing success screen, not MCP documentation. That return page uses --locale when provided, falls back to English, and names the order type as a letter or postcard.

This flow does not require the user to create public API keys or pre-fund credits.

postbox-agent letter \
  --to "Ada Lovelace" \
  --message-file letter.md

postbox-agent postcard \
  --recipient recipient.json \
  --front postcard-front.jpg \
  --message "Wish you were here"

--to searches Mailbook contacts. Use --contact-id when multiple contacts match, or --recipient / --recipient-file for structured recipient JSON.

Custom postcard fronts must be square, with a 1:1 aspect ratio. When generating or preparing postcard artwork for --front, create or crop the image to 1:1 before uploading.

Payment Links

Use letter or postcard for the default hosted payment URL path. Use send for the guided quote-then-payment-link path. Use payment-link when the payload is already prepared and you only want the hosted payment URL.

postbox-agent payment-link letter --payload order.json

payment-link calls the MCP create_payment_link tool. checkout-link calls the compatibility create_checkout_link tool. --email / --sender-email is optional for hosted payment links; Stripe Checkout collects the payer email when it is omitted.

API And Credit Paths

The CLI still supports the public API and credit-wallet flows exposed by MCP.

postbox-agent wallet --mode live --currency eur
postbox-agent topup create --amount-cents 1000 --currency eur
postbox-agent direct-send letter --payload order.json --confirm-live-send --max-amount-cents 250
postbox-agent api-key create --name "Production integration"

direct-send is intentionally explicit. In live mode it requires --confirm-live-send, and callers should set --max-amount-cents when automating sends.

Mailbook

postbox-agent mailbook list --query Ada
postbox-agent mailbook get --contact-id contact_123
postbox-agent mailbook create --payload contact.json
postbox-agent mailbook update --payload contact-update.json
postbox-agent mailbook delete --contact-id contact_123

Uploads

Local files are uploaded through MCP before the order is created.

postbox-agent upload --kind postcard-image --file front.jpg
postbox-agent upload --kind letter-attachment --file attachment.pdf
postbox-agent upload --kind letter-stamp-image --file stamp.png

The higher-level send, quote, and payment-link commands upload files automatically for:

• --front on postcards. The file must be a square 1:1 image.
• --attachment on letters
• --stamp on letters

Generic MCP Access

Every MCP tool remains available:

postbox-agent tools
postbox-agent tool call quote_order --payload order.json --json
postbox-agent search "payment links"
postbox-agent fetch --id docs://public-api/orders
postbox-agent init

Use --payload for JSON payload files or inline JSON. --json prints machine-readable output.

Configuration

The CLI stores OAuth configuration at:

~/.config/postbox-agent/config.json

Environment variables:

• POSTBOX_AGENT_BASE_URL: default PieterPost base URL override
• POSTBOX_AGENT_CONFIG: custom config file path
• POSTBOX_AGENT_ACCESS_TOKEN: bypass stored OAuth tokens with a bearer token
• POSTBOX_AGENT_DEBUG: print structured error details

The previous AGENT_POST_* environment variable names are still accepted as compatibility aliases.

The default base URL is https://pieterpost.com. Use --base-url for local or staging targets:

postbox-agent --base-url http://localhost:3000 login

Architecture

The CLI is a remote MCP client, not a separate sending backend.

• src/index.ts owns process startup and error handling.
• src/commands.ts maps CLI commands to MCP tools.
• src/oauth.ts performs OAuth dynamic client registration, PKCE, and loopback callback login.
• src/config.ts stores the selected base URL, MCP URL, OAuth client, access token, and refresh token.
• src/mcp.ts performs JSON-RPC calls to /mcp/, refreshes expired access tokens, and parses MCP tool results.
• src/payloads.ts builds letter/postcard payloads, resolves Mailbook contacts, uploads local files, and validates hosted-payment requirements.
• src/io.ts handles file, stdin, JSON, and terminal output helpers.

CLI MCP requests send x-pieterpost-client: postbox-agent-cli. The server stores only generic client-type usage metadata (cli) plus response status and tool/route key, so dashboard reporting stays cumulative and anonymized like the existing API and MCP usage charts.

All product behavior remains in the Next.js app and MCP tools. The CLI should stay thin: compose payloads, call MCP, and present results.