Command Reference

Run bachs --help to see the command list. Commands that take flags, such as bachs listen, support --help. For grouped commands such as events, sessions, and endpoints, run the group without a subcommand to see its operations, then add --help after the operation (for example, bachs events list --help). Run a resource name on its own to see its API operations. Every command accepts --api-key to override your stored credentials for that invocation. It is left out of the tables below to keep them readable.

Pairs this machine with your account through the browser. See Log in for the full flow.

Connect this machine

bachs login

Flag	What it does
`--sandbox`	Pair against the sandbox rather than production.
`--device-name <name>`	Label shown on the approval screen. Defaults to your hostname.
`--api-key <key>`	Log in with a key instead of the browser.

--api-key puts a credential in your shell history, and on Linux it is readable by other local users through the process list. Prefer the browser flow, or BACHS_API_KEY where no browser is available.

logout

Removes the credential stored on this machine. It does not affect a key supplied through BACHS_API_KEY or --api-key.

Forget the stored credential

bachs logout

Logging out removes the local credential but does not revoke the paired key. Revoke it from the developer portal if it should stop working immediately; otherwise it expires on its normal schedule.

whoami

Shows which environment your stored credentials target. Useful before running anything that changes data.

Check the active environment

bachs whoami

Response

Environment: sandbox
API base:    https://sandbox-api.bachs.io
Key:         sk_sandbox_a1b2c3d4…

listen

Forwards live events to a port on your machine. The connection is opened outbound, so there is no public URL and no tunnel. See Test webhooks locally for the full guide.

Forward every event

bachs listen --forward-to localhost:3000/webhooks

Flag	What it does
`--forward-to`, `-f`	Local target, for example `localhost:3000/webhooks`. Required.
`--events`, `-e`	Comma-separated event types to forward.
`--all`	Forward every event type. The default when `--events` is omitted.
`--device-name <name>`	Label for this session in the dashboard.

The target accepts the shapes people actually type. localhost:3000/webhooks, :3000/webhooks, and a full URL all work.

Forward two event types

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

Pass either --events or --all, not both. The CLI refuses rather than silently preferring one, so a filter you passed never does nothing without telling you.

sessions

Lists forwarding sessions that are currently connected to your account and closes sessions you no longer need. This is useful when events are reaching another machine or a terminal you left running.

sessions list

List live forwarding sessions

bachs sessions list

sessions close

Close one forwarding session

bachs sessions close whls_8f2e40f6bdf84c1980e1e1f6407f3f8a

Closing a session stops delivery to that CLI connection. It does not change registered webhook endpoints.

trigger

Emits a sample event so you can exercise a handler without making a real payment. The event goes through the ordinary delivery path, so it fans out to whatever is subscribed, records delivery attempts, and is signed like any other event.

Emit a sample event

bachs trigger collection.succeeded

Sandbox only. A fake collection.succeeded in production could have you fulfil an order nobody paid for, so the CLI refuses rather than warning. In production, use bachs events replay to redeliver a real past event.

The event type is a positional argument. These are supported:

Group	Event types
Collections	`collection.succeeded`, `collection.failed`
Payouts	`payout.created`, `payout.paid`, `payout.failed`
Refunds	`refund.created`, `refund.paid`, `refund.failed`
Checkout	`checkout.completed`, `checkout.expired`
Customers	`customer.created`, `customer.updated`

events

Lists past events and redelivers them. Replay is a plain API call, so it needs no forwarding session and works against your registered destinations in production too.

events list

Recent events and how they went

bachs events list

Flag	What it does
`--limit <n>`	How many events to show. Max 100, default 20.
`--type <event_type>`	Only this event type, for example `collection.succeeded`.
`--failed`	Only events whose last delivery failed.
`--undelivered`	Only events nothing was listening for.

--undelivered is the one to reach for when an event seems to have vanished. It shows events that matched no destination at all, which usually means the endpoint filter does not include that type.

events replay

Redeliver one event

bachs events replay evt_3ab4e0d5d27445cf8a52ab3d8cb8f0b1

events replay-failed

Redelivers events whose delivery failed, which saves replaying them one at a time after an outage on your side.

See what would be replayed

bachs events replay-failed --dry-run

Flag	What it does
`--dry-run`	List what would be replayed and stop.
`--limit <n>`	Most events to replay. Default 20.
`--type <event_type>`	Only this event type.

Run --dry-run first. It costs nothing and tells you exactly what the real run will touch.

endpoints

Manages the webhook destinations Bachs delivers to. These are the same destinations shown in the Developer Portal.

Your webhook destinations

bachs endpoints list

bachs endpoints create --url https://example.com/webhooks --events collection.succeeded,refund.paid

Flag	What it does
`--url <url>`	HTTPS URL to deliver to. Required.
`--events <a,b>`	Comma-separated event types. Required.
`--name <name>`	Label for this destination.

Remove a destination

bachs endpoints delete whe_8f2e40f6bdf84c1980e1e1f6407f3f8a

Resource commands

Every API operation is also a command, grouped by resource. Run a resource name on its own to see its operations:

See what you can do with customers

bachs customers

Operations

Usage: bachs customers <operation> [flags]

Operations:
  create                Create a customer
  get    <customer_id>  Retrieve a customer
  list                  List customers
  update <customer_id>  Update a customer

The available resources:

accounts
balances
checkout-sessions
connected-accounts
conversions
customer-sessions
customers
disputes
media
misc

payments
payouts
persons
platform-fees
product-groups
products
reference
refunds
subscriptions
transfers
webhooks

Operations follow the API. Anything the operation takes in its path is a positional argument, and everything else is a flag:

Retrieve one customer

bachs customers get cust_8f2e40f6bdf84c1980e1e1f6407f3f8a

List with a filter

bachs payments list --limit 10

You do not have to know whether a value belongs in the query string or the request body. A flag the operation lists as a query parameter is sent as one, and anything else becomes a body field:

Create a customer

bachs customers create --email ada@example.com --name "Ada Lovelace"

Values are converted to the JSON type the API expects. true and false become booleans, whole numbers become integers, and anything containing a decimal point is left as a string, so an amount like 29.00 stays exact rather than being rounded through a float. Responses print as formatted JSON, which pipes cleanly into jq:

Pull one field out of the response

bachs customers list --limit 5 | jq '.data[].email'

Resource commands read and write real data in whichever environment you are paired with. Run bachs whoami first if you are not sure, and prefer bachs login --sandbox while you are exploring.

Exit codes

Code	Meaning
`0`	The command succeeded.
`1`	The command ran and failed, for example the API returned an error.
`2`	The command was used incorrectly, for example a required flag was missing.

Scripts should check for a non-zero exit rather than parsing output, which is formatted for people and may change.

Get Started

Payouts

Virtual accounts

Products & pricing

Subscriptions

Customer portal

Payments

Dashboard

Developer Portal

CLI

For You and Your Customers

Command Reference

logout

whoami

listen

sessions

sessions list

sessions close

trigger

events

events list

events replay

events replay-failed

endpoints

Resource commands

Exit codes

​login

​logout

​whoami

​listen

​sessions

​sessions list

​sessions close

​trigger

​events

​events list

​events replay

​events replay-failed

​endpoints

​Resource commands

​Exit codes

login

logout

whoami

listen

sessions

sessions list

sessions close

trigger

events

events list

events replay

events replay-failed

endpoints

Resource commands

Exit codes