Configuration
Configure Better Webhook CLI with config files, environment variables, and command flags.
Configuration
The CLI supports three configuration layers:
- Config file (
config.toml) - Environment variables
- Command flags
Use this page to set up predictable defaults and reduce repetitive flags.
Quick Setup
Generate a default config file
better-webhook initThis creates ~/.better-webhook/config.toml with documented defaults.
Review and adjust settings
Open the generated file and update directories or log level as needed.
Use overrides only when needed
Use environment variables or command flags for temporary changes.
Config File Location
By default, the CLI resolves the config file path to:
~/.better-webhook/config.tomlYou can choose a different file path with --config or BETTER_WEBHOOK_CONFIG_PATH.
Config Path Precedence
The CLI resolves which config file to load in this order:
--config <path>BETTER_WEBHOOK_CONFIG_PATH~/.better-webhook/config.toml
Config Keys
| Key | Default | Env Override | Flag Override | Description |
|---|---|---|---|---|
captures_dir | ~/.better-webhook/captures | BETTER_WEBHOOK_CAPTURES_DIR | --captures-dir | Directory where captured webhook payloads are stored |
templates_dir | ~/.better-webhook/templates | BETTER_WEBHOOK_TEMPLATES_DIR | --templates-dir | Directory where downloaded templates and cache files are stored |
log_level | info | BETTER_WEBHOOK_LOG_LEVEL | command-specific --verbose behavior | Default logging verbosity (debug, info, warn, error). debug enables verbose output by default for capture, captures replay, and templates run unless --verbose is explicitly set. |
Value Precedence
For each setting value (captures_dir, templates_dir, log_level), precedence is:
- Command flags
- Environment variables
- Config file
- Built-in defaults
This means one-off command flags always win over persistent defaults.
Environment Variables
# Config file path
export BETTER_WEBHOOK_CONFIG_PATH="$HOME/.better-webhook/config.toml"
# Value overrides
export BETTER_WEBHOOK_CAPTURES_DIR="$HOME/tmp/bw-captures"
export BETTER_WEBHOOK_TEMPLATES_DIR="$HOME/tmp/bw-templates"
export BETTER_WEBHOOK_LOG_LEVEL="debug"Custom Config File Path
# Use an explicit config file for this command
better-webhook --config ./configs/dev.toml captures list
# Generate defaults into a custom path
better-webhook --config ./configs/dev.toml initinit does not overwrite existing files unless you pass --force.
Example Config File
captures_dir = "~/.better-webhook/captures"
templates_dir = "~/.better-webhook/templates"
log_level = "info"The generated config from better-webhook init includes additional inline comments and guidance.