CLI reference

The catchbin CLI is a single Go binary. Install it and authenticate as described on the Install page. This page is the command and flag reference.

Conventions

• stdout carries data; stderr carries diagnostics. Status lines, reconnect notices, and errors go to stderr, so you can pipe data on stdout without noise.
• --json on most commands emits machine-readable output instead of the formatted card.
• Commands exit non-zero on failure with a stable exit code.

configure

catchbin configure

Prompts for a workspace API key (hidden input), validates it, and writes it to your config file. See Install → Authenticate.

forward

Open a persistent connection and re-send each captured webhook to a target.

catchbin forward <workspace-id>/<slug> <target> [--json]

• <workspace-id>/<slug> — the endpoint, written as the pair in its URL (for example wk_ab12cd34ef56/stripe-dev).
• <target> — where to deliver events (localhost:3000, or any URL such as https://staging.example.com).
• --json — emit one JSON object per forwarded event on stdout.

Requires the endpoint to be in store_and_forward mode. See Forward to localhost.

replay

Replay a captured event from your machine. Reaches localhost and your LAN.

catchbin replay <event-id> --target <url> [--strip | --resign] [--secret-from-stdin] [--json]

• --target — the URL to replay to (required).
• --strip — remove provider signature headers before sending (default).
• --resign — compute a fresh signature using the target’s secret (prompted for hidden, or via --secret-from-stdin). Mutually exclusive with --strip.
• --secret-from-stdin — read the re-sign secret from stdin (for CI).

See Replay an event. For cloud-side replay to a public target, use api events replay.

api endpoints

Manage endpoints over the public API.

catchbin api endpoints list
catchbin api endpoints create --slug <slug> [--display-name <name>] [--operating-mode <mode>] \
    [--signature-header <name>] [--signature-prefix <prefix>]
catchbin api endpoints get <endpoint-id>
catchbin api endpoints delete <endpoint-id>

• --slug is required on create. --operating-mode accepts values such as store_and_forward.
• --signature-header / --signature-prefix configure a Generic-provider endpoint.
• Endpoints created in the dashboard are not deletable with an API key.

Note

<endpoint-id> is the endpoint’s UUID (from list or the dashboard) — distinct from the <workspace-id>/<slug> pair that forward takes.

api events

Inspect and act on captured events.

catchbin api events list <endpoint-id> [--limit N] [--before <ts>] [--before-id <id>] [--after <ts>] [--after-id <id>]
catchbin api events get <endpoint-id>/<event-id>
catchbin api events delete <endpoint-id>/<event-id>
catchbin api events curl <endpoint-id>/<event-id> [--unmasked]
catchbin api events replay <endpoint-id>/<event-id> --target <url>

• list returns newest-first; page with the cursor values printed after a page (--before/--before-id, --after/--after-id).
• curl prints a ready-to-run curl reconstruction of the captured request; --unmasked reveals masked credential headers.
• replay here is server-delegated — catchbin’s cloud re-sends the event to --target (public targets only). It is gated by the endpoint’s replay_from_api flag. For localhost, use the top-level replay command instead.

Exit codes

Code	Class	Condition
0	success	Command completed without error
1	usage error	Bad arguments, missing required flag, invalid combination
2	configuration error	Missing or invalid API key, unreadable config, bad URL
3	authentication error	API key rejected (401), access denied
4	not found	Referenced resource does not exist (404)
5	protocol error	Server rejected the connection with a terminal status (422, 426)
6	target error	forward or replay could not reach the local target
7	signal exit	Terminated by Ctrl-C or SIGTERM (clean shutdown)