@zappyquote/cli

zappy - the official Zappy command-line client. A thin client over the public Zappy API v1 (https://zappyquote.com/developers/): no embedded provider credentials, no database access, nothing that bypasses the server's pricing, caps, rate limits or idempotency.

Version 0.1.1 · contract openapi-1.0.0@9dff9fdfbcd8c1bd · Node 18+ · zero dependencies · MIT

Install

# official download (always available):
curl -O https://zappyquote.com/dl/zappy-cli.mjs && node zappy-cli.mjs help
alias zappy='node "$PWD/zappy-cli.mjs"'     # the commands below use `zappy` (the npm package installs it for you)
# npm, ONLY once https://zappyquote.com/developers/ lists @zappyquote/cli as published by Zappy:
#   npm install -g @zappyquote/cli

Set up

Create an API key in Zappy under Account -> Developer, then:

zappy auth set-key        # paste at the hidden prompt; stored in ~/.config/zappy/credentials.json (mode 0600)
zappy auth status         # shows the key prefix only - the key is never printed again

ZAPPY_API_KEY in the environment takes precedence over the stored key.

Commands

| Command | Cost | |---|---| | zappy whoami / zappy usage | free - today's spend against your caps | | zappy capabilities | free | | zappy balance | free | | zappy quote <capability> | free - reserves nothing | | zappy jobs get <id> · zappy jobs watch <id> | free | | zappy creations list [--limit N] [--cursor C] | free | | zappy assets get <id> · zappy assets download <id> [--out FILE] | free (download verifies size + sha256) | | zappy image create "<prompt>" --max-credits N --confirm-billable | spends credits | | zappy image edit <asset_id> "<prompt>" --max-credits N --confirm-billable | spends credits | | zappy mcp config | prints a Remote MCP client configuration (placeholders) |

Add --json to any command for machine-readable output. --base <url> overrides the API base (default https://zappyquote.com/api/v1).

Paid commands

• They refuse to run without --confirm-billable and --max-credits (a hard ceiling; quote first).
• They generate - or take, via --idempotency-key - a stable idempotency key and print it. The CLI never retries a paid call. If a result is unclear, re-run the same command with --idempotency-key <the key>: the server replays the original job instead of charging again. Never re-run a paid command without the key.
• --wait polls the job (free) until it finishes.

Exit codes

0 ok · 1 error · 2 usage · 3 not configured / credential refused / insufficient scope · 4 the API refused (spend ceiling, cap, not available, not found) · 5 rate limited (see retry_after) · 6 API unreachable.

Credentials are redacted from every line this program prints.