Command Reference

For configuration keys, path precedence, and environment variable details, see Configuration.

Global Options

These options apply to all commands:

Option	Description
`--config <path>`	Path to config TOML file
`BETTER_WEBHOOK_CONFIG_PATH`	Environment variable alternative to `--config`

Initialize a default config file:

better-webhook init

capture

Start a standalone server to capture incoming webhooks.

better-webhook capture [options]

Options:

Option	Default	Description
`--host <host>`	`127.0.0.1`	Host to bind the capture server
`-p, --port <port>`	`3001`	Port to listen on
`-v, --verbose`	`false`	Enable verbose capture logging (enabled by default when `log_level=debug` unless overridden)
`--captures-dir <dir>`	config/default	Directory where captures are stored

Example:

better-webhook capture --port 3001

Captured webhooks are stored locally and can be viewed with captures list or replayed with captures replay.

captures

Manage captured webhooks. This command has several subcommands.

captures list

List captured webhooks.

better-webhook captures list [options]

Options:

Option	Default	Description
`--limit <limit>`	`20`	Maximum captures to show
`--provider <provider>`	—	Filter by provider
`--captures-dir <dir>`	—	Directory where captures are stored

Example:

# List recent captures
better-webhook captures list

# Filter by provider
better-webhook captures list --provider github

captures delete

Delete a specific capture.

better-webhook captures delete <captureId> [options]

Options:

Option	Description
`-f, --force`	Skip confirmation prompt

captures replay

Replay a captured webhook to a target URL.

better-webhook captures replay <capture-id> [target-url] [options]

capture-id is required. If target-url is omitted, the CLI uses --base-url and the captured request path.

Options:

Option	Description
`--base-url <url>`	Base URL used when `target-url` is omitted
`--method <method>`	Override HTTP method
`-H, --header <header>`	Add/override header (format: `key:value`)
`--timeout <duration>`	HTTP timeout (for example `30s`)
`-v, --verbose`	Show detailed request/response info (enabled by default when `log_level=debug` unless overridden)
`--captures-dir <dir>`	Directory where captures are stored

captures replay exits non-zero when the target response is HTTP 4xx or 5xx.

Example:

# Direct mode
better-webhook captures replay abc12345 http://localhost:3000/api/webhooks/github

# Build target from captured path + base URL
better-webhook captures replay abc12345 --base-url http://localhost:3000

# With options
better-webhook captures replay abc12345 http://localhost:3000/api/webhooks/github \
  -H "X-Custom-Header:value" \
  --verbose

templates

Manage webhook templates. See Templates for detailed documentation.

Quick Reference

# List remote templates
better-webhook templates list

# Download a template
better-webhook templates download github-push

# Download all templates
better-webhook templates download --all

# Refresh index and re-download templates
better-webhook templates download --all --refresh

# List local templates
better-webhook templates list --local

# Delete a local template
better-webhook templates delete github-push

# Search templates
better-webhook templates search github

# Clear template cache
better-webhook templates cache clear

# Remove all downloaded templates
better-webhook templates clean

# Execute a downloaded template
better-webhook templates run github-push http://localhost:3000/api/webhooks/github

templates run options

better-webhook templates run <template-id> [target-url] [options]

Option	Description
`--secret <secret>`	Secret used for provider-specific signing placeholders
`--allow-env-placeholders`	Allow `$env:*` placeholders in template content
`-H, --header <header>`	Add/override header (format: `key:value`)
`--timeout <duration>`	HTTP timeout (for example `30s`)
`-v, --verbose`	Show detailed request/response info (enabled by default when `log_level=debug` unless overridden)

templates run exits non-zero when the target response is HTTP 4xx or 5xx.

The command path is templates run (not top-level run) in the Go CLI.

Command Reference

On this page