# BillerAPI CLI

Inspect resources, forward signed webhooks to localhost, and fire deterministic sandbox events without writing throwaway scripts.

> **Note — Release status**
> The account-free demo is available in `billerapi-cli@1.1.0`.

## Try it before signup



**Terminal**

```bash
npx -y billerapi-cli@1.1.0 demo
```

This read-only command does not create an account or write local configuration.



### Create now, claim later

After the exact CLI release is available, create an immediate sandbox profile
without signup or prompts:

```bash
billerapi sandbox create
```

The receipt contains a sensitive, one-shot `claim_url`. Give it only to the
intended human who will attach the sandbox and accept the current legal
documents later on the web. Production is the default; use `--environment
local`, `--environment staging`, or `--environment production` to create
through that environment's API Gateway and save the matching sandbox-data host.
Unclaimed sandboxes expire after 60 days.

### Configure your coding agents

Only after npm confirms the exact published CLI version, the hosted MCP endpoint
has live deployment and canary proof, and `billerapi --help` lists the command,
preview and apply the detected Claude Code, Cursor, and Codex changes:

```bash
npx -y billerapi-cli@1.1.0 agent setup --dry-run
npx -y billerapi-cli@1.1.0 agent setup --expected-bundle-sha256 <reviewed_bundle_sha256>
```

Existing configuration must parse before the command touches it. It installs
the BillerAPI MCP entry and public skills with compare-and-swap writes,
then prints a secret-free receipt of every change. Do not start a harness during
apply: an existing config or managed skill can be briefly absent, and a claimed
skill directory can be marked in progress while reviewed files are published.
If apply is terminated during that window, later setup runs fail closed without
changing either copy. Restore the intended private backup manually, preserve the
other copy for review, then run a fresh dry-run.
This first release supports macOS on Apple silicon only; other runtimes fail
before download or mutation.
Apply requires the exact `bundle_sha256` from the reviewed dry-run receipt and
refuses if the downloaded bytes have changed. Production is the default. Pass
`--environment local`, `--environment staging`, or `--environment production`
to select that environment's generated canonical MCP and skills-catalog hosts,
and repeat the same environment for preview and apply because it is bound into
the approval digest.

## Local webhook loop

**Terminal**

```bash
npm install -g billerapi-cli
billerapi login
billerapi doctor
billerapi samples create node-express
billerapi listen --forward-to http://localhost:3000/webhook

# In another terminal
billerapi trigger bill.created --link_id=lnk_1 --amount=4200
```

The listener reconnects with exponential backoff and falls back to delivery polling after repeated stream failures. Forwarded requests use the production-compatible signature scheme.

## Useful commands

- `billerapi bills list` — Query bill resources
- `billerapi billers list` — Explore the catalog
- `billerapi links list` — Inspect account links
- `billerapi webhooks deliveries` — Debug delivery history
- `billerapi events tail` — Follow the activity feed
- `billerapi env sandbox` — Switch the active profile mode

> **Warning — Production forwarding is deliberately gated**
> A production profile requires `--prod` and confirmation before mirroring events to a laptop because payloads may contain customer data.