Metadata-Version: 2.5
Name: bachs-cli
Version: 0.1.0
Summary: Forward live Bachs webhook events to your local machine
Project-URL: Homepage, https://bachs.io
Project-URL: Documentation, https://docs.bachs.io/developer-portal/local-testing
Project-URL: Changelog, https://docs.bachs.io/changelog/api
Author-email: Bachs <support@bachs.io>
License: MIT
Keywords: bachs,cli,local-testing,payments,webhooks
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# bachs CLI

Forward live webhook events to your local machine. No tunnel, no public URL, no
third-party account.

## Install

```bash
pip install bachs-cli
# or, without installing:
pipx run bachs-cli listen --forward-to localhost:3000/webhooks
```

## Use

```bash
bachs login --api-key sk_sandbox_...
bachs listen --forward-to localhost:3000/webhooks
```

Every delivery prints as it arrives — event type, the status your handler
returned, and how long it took:

```
Ready! Forwarding sandbox events to http://localhost:3000/webhooks
Your webhook signing secret is whsec_a1b2c3... (^C to quit)
Session whls_8f2e… · 26 event type(s)

✓ collection.succeeded evt_3ab4e0d5 200 [42ms]
✗ refund.paid          evt_7c1f22a9 500 [131ms]
```

Narrow it down:

```bash
bachs listen --forward-to localhost:3000/webhooks --events collection.succeeded,refund.paid
```

Redeliver something that already happened. This needs no session and no socket
— it works against your registered endpoints too:

```bash
bachs events replay evt_3ab4e0d5d27445cf8a52ab3d8cb8f0b1
```

## How it works

The connection is opened **outbound** from your machine, so nothing needs to
reach you: no public URL, no inbound port, and it works behind NAT and
corporate firewalls.

Each session gets its **own signing secret**, printed when it starts. Payloads
are genuinely signed with it, so your verification code is exercised for real —
and your production endpoint's secret never leaves production.

A session is a webhook destination like any other, so event filtering,
delivery records and the dashboard all work the same way.

## Environments

The API key prefix picks the environment: `sk_sandbox_` for sandbox,
`sk_live_` for production. There is no `--env` flag to get out of step with the
key you are using.

## Notes

- Deliveries to a session are **not retried**. If your handler is down or your
  laptop is asleep, the event is dropped and shown as failed — you are watching
  the terminal, and a backlog arriving tomorrow would not help.
- Credentials are stored at `~/.config/bachs/config.json`, mode 0600. Set
  `BACHS_API_KEY` instead if you would rather not write a key to disk.
