Configuration

The Hookie CLI uses global config under ~/.hookie/, optional repository hookie.yml files, and a few environment variables.

Global Configuration

Authentication tokens are stored in your system keychain when available (macOS Keychain or equivalent), with a config-file fallback. Machine ID and optional relay overrides live in the config file.

Default path: ~/.hookie/config.json. Override the directory with HOOKIE_CONFIG_DIR when home directory resolution differs across terminals or tools:

export HOOKIE_CONFIG_DIR="$HOME/.hookie"

You normally manage this with hookie login and hookie logout rather than editing files by hand.

Environment Variables

Repository Configuration

Create a hookie.yml in your repository for app_id, forward URLs, and per-source forwarding so teammates can run hookie listen without flags.

File Format

app_id: billing-api-k7m2xp
forward: http://localhost:3001/webhooks
sources:
  stripe: http://localhost:3002/webhooks/stripe
  checkout: http://localhost:3003/webhooks/checkout

Fields

• app_id (optional) — Application public id to subscribe to (all sources).
• source_id (optional) — Source slug for a single source. Requires app_id.
• forward (optional) — Default forward URL for all events. Must include scheme and host.
• sources (optional) — Map of source slug → forward URL for per-source forwarding. Each URL must include scheme and host.

Configuration Discovery

The CLI searches for hookie.yml from the current working directory upward until it finds one or reaches the filesystem root. The closest file wins.

Example from /project/app/src/components:

1. /project/app/src/components/hookie.yml
2. /project/app/src/hookie.yml
3. /project/app/hookie.yml
4. /project/hookie.yml
5. /hookie.yml

Priority Order

For hookie listen:

1. CLI flags (--app-id, --source-id, --forward-to, and so on) — highest priority
2. Repository config (hookie.yml)
3. Anonymous mode — if no app or source is set by flags or config, even when logged in

# Flag overrides config
hookie listen --app-id checkout-api-m2n8xp

# Config used when no targeting flags
hookie listen

# No app/source in flags or hookie.yml → anonymous ephemeral channel
hookie listen

Initializing Configuration

hookie init

This command:

1. Checks whether hookie.yml already exists in the current directory (prompts to overwrite)
2. Requires authentication
3. Fetches your applications
4. Shows an interactive selector to choose an application
5. Prompts for an optional forward URL
6. Writes hookie.yml in the current directory

hookie init is the interactive flow. hookie listen does not prompt you to pick an app; without targeting info it goes anonymous.

Example Output

? Select an application
  ▸ My Webhook App (billing-api-k7m2xp)
    API Gateway (checkout-api-m2n8xp)

? Forward URL (optional)
  http://localhost:3001/webhooks

✓ Created hookie.yml

Configuration:
  App ID: billing-api-k7m2xp
  Forward URL: http://localhost:3001/webhooks

You can now run hookie listen without specifying flags.
To add per-source forwarding, edit hookie.yml and add entries under 'sources'.

Per-Source Forwarding

Different sources can forward to different endpoints.

Basic Example

app_id: billing-api-k7m2xp
forward: http://localhost:3001/webhooks  # Default for all sources
sources:
  stripe: http://localhost:3002/payments
  checkout: http://localhost:3003/webhooks

How It Works

When an event arrives:

1. If the event's source slug is in the sources map, use that URL
2. Otherwise use the default forward URL (if set)
3. If neither applies, the event is not forwarded

With the config above:

• stripe → http://localhost:3002/payments
• checkout → http://localhost:3003/webhooks
• any other source → http://localhost:3001/webhooks

Advanced Example

app_id: billing-api-k7m2xp
# No default forward URL
sources:
  stripe: http://localhost:3002/payments
  subscriptions: http://localhost:3003/subscriptions

Team Collaboration

1. Commit hookie.yml so clones can run hookie listen with shared defaults
2. Keep environment-specific forward URLs appropriate for local ports
3. Treat the file as living documentation of which app or sources the repo uses

Example Workflow

# Developer A
cd my-project
hookie init
git add hookie.yml
git commit -m "Add hookie.yml configuration"
git push

# Developer B
git clone my-project
cd my-project
hookie login
hookie listen

Validation

The CLI validates repository config:

• source_id requires app_id — source slugs are scoped to an application
• URL format — Forward URLs need a scheme (http:// or https://) and host
• YAML syntax — Invalid YAML surfaces a parse error

Error Examples

# source_id without app_id
Error: invalid configuration in hookie.yml: source_id requires app_id

# Missing scheme in URL
Error: invalid forward URL: URL must include a scheme (e.g., http:// or https://)

# YAML syntax error
Error: failed to parse hookie.yml: yaml: line 2: found character that cannot start any token

Related Commands

• Listen — Uses repository configuration when listening
• Status — Check relay connectivity and login state
• Applications — Find application public ids
• Sources — Find source slugs for per-source forwarding