CLI — send mail from the command line

The paperplane CLI is a thin wrapper over the same public REST API the website and every integration use — quote a letter, send it, and check its status without leaving your terminal or scripts. No install step required with npx, no account, no API key.

Install

Run it directly with npx, or install it globally:

npm install -g paperplane

Quote a letter

Price a letter before sending anything. Free, one all-in total:

npx paperplane quote \
  --to "Maria Alvarez, 1 Main St, Richmond VA 23220" \
  --text "Dear Maria, ..." \
  --class certified

Send a letter

Upload a PDF and mail it. --from is required — USPS requires a return address on every letter — or set PAPERPLANE_FROM once so you don't have to pass it every time.

npx paperplane send letter.pdf \
  --to "Maria Alvarez, 1 Main St, Richmond VA 23220" \
  --from "Alex Rivera, 12 Grove Ave, Richmond VA 23221" \
  --sandbox

--sandbox runs the entire flow — upload, screening, simulated fulfillment, a tracking number — instantly and free, and mails nothing.

Check status

npx paperplane status ord_abc123

Configuration

• PAPERPLANE_FROM — a default --from address, same one-line shorthand format.
• PAPERPLANE_API_URL — override the API base URL (for testing against a local or staging server).

Addresses

Addresses are one line: "Name, Street, City ST ZIP", or with a second line: "Name, Street, Line2, City ST ZIP".

Payment

Every order carries its own payment — a prepaid credit code (--credit-code pp-xxxx-xxxx-xxxx) for hands-off scripts, or a Stripe payment link a human approves. Sandbox orders need neither.

The CLI covers quoting, sending, and status — for everything else (webhooks, cancellation, uploads from outside the CLI, MCP for agents), see the full API documentation.