@billerapi/cli

The official command-line interface for BillerAPI. Stripe/Plaid-style developer loop: authenticate, listen for real webhook events, fire sandbox triggers, bootstrap sample apps.

Install

npm install -g @billerapi/cli

Requires Node ≥ 18.

Quickstart

# 1. Save your sandbox credentials (opens the API keys page first)
billerapi login

# 2. Verify everything is reachable
billerapi doctor

# 3. Bootstrap a webhook handler in your language
billerapi samples create node-express

# 4. In one terminal, stream events to the local handler
billerapi listen --forward-to http://localhost:3000/webhook

# 5. In another terminal, fire a synthetic event
billerapi trigger bill.created --link_id=lnk_1 --amount=4200

Your local handler receives a HMAC-signed bill.created event within ~1s. The signature verifies via verifyWebhook from @billerapi/event-bus — same canonical scheme BillerAPI uses for production webhook delivery.

Commands

Run billerapi <command> --help for full options.

| Command | Purpose | |---|---| | login | Save credentials to ~/.billerapi/config.json (mode 0600) | | config <list\|get\|set\|use\|rm> | Manage saved profiles | | env [sandbox\|production] | Show or flip the active env | | doctor | Diagnose config + connectivity (4 active checks) | | bills <list\|get\|sync> | Bill resource queries | | billers <list\|get\|search-by-email> | Biller catalog | | links <list\|get> | Account links | | webhooks <list\|get\|deliveries\|replay> | Webhook config + history | | metering <usage\|api-calls> | Consumption + audit-log | | listen --forward-to <url> | Stream events to a local URL (WSS + poll fallback) | | trigger <event_type> | Fire a sandbox event (sandbox-env only) | | samples <list\|create> | Bootstrap a sample webhook handler | | open <dashboard\|api-keys\|docs> | Open a BillerAPI URL | | events <list\|tail> | Query the activity feed | | version [--check] | Print version; --check compares with npm | | completion <bash\|zsh\|fish> | Print a shell completion script |

Profiles + env vars

Credentials and base URL come from the active profile in ~/.billerapi/config.json. Override per-command with flags or env vars:

| Flag | Env var | Default | |---|---|---| | --profile <name> | BILLERAPI_PROFILE | activeProfile in config | | --client-id <id> | BILLERAPI_CLIENT_ID | profile.clientId | | --client-secret <secret> | BILLERAPI_CLIENT_SECRET | profile.clientSecret | | --api-base <url> | BILLERAPI_API_BASE | env-derived default | | --output <json\|table> | — | json | | --debug | — | off |

Listen

billerapi listen --forward-to <url> opens a WSS connection to events-stream-service, re-signs each event with your client_secret, and POSTs to the local URL. Reconnects with exponential backoff up to 30s. After 3 consecutive WSS-connect failures it degrades to polling /iam/webhooks/deliveries so the dev loop survives transient outages.

Production-env profiles require --prod flag and a confirmation prompt — mirroring real customer webhooks to a developer's laptop is a PII leak vector.

Trigger

billerapi trigger <event_type> [--key=value …] fires a synthetic event into the configured sandbox. Refuses non-sandbox profiles. Each event is tagged metadata.synthetic: true so webhooks-service filters it out of real client webhook URLs.

Samples

Bundled in the npm package under samples/. Each is a runnable webhook handler that verifies the BillButler-Signature header:

| Template | Path | Signing | |---|---|---| | node-express | Express + verifyWebhook from @billerapi/event-bus | | python-flask | Flask + stdlib hmac/hashlib | | go-stdlib | net/http + crypto/hmac |

Shell completion

# bash
billerapi completion bash >> ~/.bash_profile && source ~/.bash_profile

# zsh (requires fpath + compinit setup)
billerapi completion zsh > ~/.zsh/completions/_billerapi

# fish
billerapi completion fish > ~/.config/fish/completions/billerapi.fish

Source

Lives in the BillerAPI monorepo: packages/cli.

Issues: https://github.com/billbox-ai/billbox-platform/issues