@postbotcz/cli

Mail a physical letter in the Czech Republic from your terminal, backed by the Postbot backend (which hands off to Česká pošta DopisOnline).

Install

npm i -g @postbotcz/cli
# or
bun add -g @postbotcz/cli

Quick start

posta auth                     # browser sign-in, mints and stores an API key
posta balance                  # 0 CZK on a new account
posta topup 500                # opens a Stripe Checkout link to add credit

posta send letter.pdf \
  --to-name "Jan Novák" --to-street "Dlouhá" --to-house "5" \
  --to-city "Praha" --to-zip "110 00"

Documents can be .pdf, .md, or .txt — the server renders markdown/text to a printable letter; the CLI just uploads the file as-is.

Commands

| Command | Description | |---|---| | posta auth | Sign in via your browser and store an API key locally. | | posta logout | Remove the locally stored API key and revoke it server-side. | | posta send <file> | Send a letter, charged against your account credit by default. | | posta status <orderId> | Look up the status of a Postbot order id (printed by posta send). | | posta topup <amountCzk> | Open a top-up payment for the given whole CZK amount. | | posta balance | Print your current account credit balance. |

send flags

| Flag | Description | |---|---| | --registered | Send as doporučené (registered) mail instead of obyčejné. | | --pay | One-off pay-per-letter (Stripe Checkout) instead of using account credit. | | --ref <id> | Attach your own job reference to the order, echoed back in status. | | --note "..." | Attach a free-text note to the order. | | --to-name "..." | Recipient name (required). | | --to-company "..." | Recipient company (optional). | | --to-street "..." | Recipient street (required). | | --to-house "..." | Recipient house number (required). | | --to-city "..." | Recipient city (required). | | --to-zip "..." | Recipient ZIP code (required). | | --from-name "..." | Sender name (required for --registered). | | --from-company "..." | Sender company (optional). | | --from-street "..." | Sender street. | | --from-house "..." | Sender house number. | | --from-city "..." | Sender city. | | --from-zip "..." | Sender ZIP code. | | --help, -h | Print usage. |

--registered sends doporučené mail (tracked, carrier compensation capped) instead of the default obyčejné (ordinary, no tracking). --pay skips your account credit entirely and opens a one-off Stripe pay-link for just this letter — useful for a single send without topping up first.

If your account balance is too low, send fails with your current balance, a top-up link, and a one-off pay-link for that specific letter (and offers to open one in your browser) instead of silently charging you.

Files

Supported input files: .pdf, .md, .txt. PDFs are uploaded as-is; the server renders markdown/text into a printable letter.

Config / environment

Credentials are written by posta auth to your config directory:

• $XDG_CONFIG_HOME/postbot/credentials.json (or ~/.config/postbot/ if XDG_CONFIG_HOME is unset) on Linux/macOS.
• %APPDATA%\postbot\credentials.json on Windows.

The file is written at mode 0600 (owner read/write only; this permission bit is a near-no-op on Windows, which has no POSIX permission model).

| Variable | Description | |---|---| | POSTBOT_API_URL | Override the API base URL (default https://postbot.cz). | | POSTBOT_API_KEY | CI escape hatch — use an API key directly instead of posta auth. Overrides the stored key. |

Auth model

posta auth runs a browser-based OAuth 2.0 Authorization Code + PKCE login (loopback redirect, RFC 8252) against the Postbot backend. On success the backend mints a Postbot API key (pb_…) bound to your account, which is stored locally and used as a Bearer token for send/status/topup/ balance. posta logout removes the local key and revokes it server-side.

Loopback auth requires a browser on the same machine as the CLI — it will not work over SSH (a Device Authorization Grant for headless/SSH use is a future addition). See ADR-0003 for why the CLI routes sends through the backend instead of talking to the Carrier directly.

Learn more

https://postbot.cz