Reference

CLI

Manage endpoints, destinations, and secrets from the terminal, and keep project configuration in version control with pull and apply.

The hooks CLI logs in with an API key and talks to the same public /v1 API as the console. Install it from this repository, then run:

hooks login --api-key "$HOOKS_API_KEY"
hooks whoami

The CLI token is written to ~/.config/hooks/config.json with mode 600 and is never printed.

Resource commands

Every resource command supports --json for machine-readable output.

# Endpoints
hooks endpoints list
hooks endpoints get ep_123
hooks endpoints create --file endpoint.yaml
hooks endpoints update ep_123 --file endpoint.yaml
hooks endpoints delete ep_123

# Destinations (list and create need the owning endpoint)
hooks destinations list --endpoint ep_123
hooks destinations get dst_123
hooks destinations create --endpoint ep_123 --file destination.yaml
hooks destinations update dst_123 --file destination.yaml
hooks destinations delete dst_123

# Secrets: values are write-only and never printed
hooks secrets list
hooks secrets get sec_123
hooks secrets create --file secret.yaml
hooks secrets update sec_123 --file secret.yaml
hooks secrets delete sec_123

# Built-in and project templates; apply creates an endpoint
hooks templates list
hooks templates get stripe-to-http
hooks templates apply stripe-to-http --values '{"url":"https://example.com/hook"}'

# Project templates: create/update/delete take a full definition
hooks templates create --file acme.yaml
hooks templates update acme --data '{"name":"Acme (staging)"}'
hooks templates delete acme

Built-in templates are read-only; custom is true for templates created in the workspace. Creating or updating a template needs the endpoints:write scope and workspace admin, and ids cannot collide with built-ins.

--file accepts YAML or JSON. --data '<json>' passes an object inline. Bodies match the REST API request shapes in the API reference.

Secret responses contain metadata only. The CLI never prints a secret value, including after secrets create or secrets update.

Config as code

hooks pull exports endpoints, their destinations, and secret names. Secret values are omitted because the API is write-only.

hooks pull --output hooks.yaml
hooks pull --format json --output hooks.json

hooks apply compares the file with the live project and creates or patches the difference. It matches endpoints by name and destinations by name (or URL when a destination has no name).

hooks apply -f hooks.yaml --dry-run   # print the diff, write nothing
hooks apply -f hooks.yaml             # prompt before writing
hooks apply -f hooks.yaml --yes       # non-interactive
hooks apply -f hooks.yaml --prune     # also delete destinations/secrets missing from the file

A pull followed by an apply is a no-op: the second run prints only = lines and applied 0 change(s).

To create secrets in a new workspace, provide values at apply time. value: in the file works for local runs, but prefer an environment variable named after the secret:

version: 1
endpoints:
  - name: Orders
    provider: stripe
    verificationMode: hmac
    destinations:
      - name: Production API
        url: https://api.example.com/hooks/orders
secrets:
  - name: STRIPE_WEBHOOK_SECRET

HOOKS_SECRET_STRIPE_WEBHOOK_SECRET=whsec_... hooks apply -f hooks.yaml --yes

Secret names map to HOOKS_SECRET_<NAME> with non-alphanumeric characters replaced by _.

Limitations

Endpoints and destinations are never deleted by apply; deletion stays an explicit hooks endpoints delete or hooks destinations delete. Templates come from the server catalog and cannot be created, updated, or deleted through the API.