CLI reference

The hookman CLI lets you register deployments, switch active targets, manage conditional routing rules, and manage your projects from the terminal or CI/CD pipelines.

Installation

npm install -g @hookman/cli

pnpm add -g @hookman/cli

# Use directly without installing
npx @hookman/cli <command>

The package is published as @hookman/cli; it installs a hookman binary, so all commands below are run as hookman ….

Authentication

API key resolution

The CLI resolves your API key in this priority order:

--key <key> flag (explicit, highest priority)
HOOKMAN_API_KEY environment variable
~/.hookman/config.json (written by hookman login)
.hookman file in the current working directory

If no key is found, the CLI exits with a clear error and instructions.

`hookman login`

Opens your browser to the Hookman dashboard to authenticate. Saves the resulting API key to ~/.hookman/config.json.

hookman login

After authenticating in the browser, return to your terminal. The key is saved automatically.

`hookman whoami`

Prints the current authenticated user and org(s).

hookman whoami
# → Authenticated as [email protected]
# → Orgs: acme (owner), darren-workspace (owner)

Commands

`hookman register`

hookman register \
  --org     <orgSlug>     \
  --project <projectSlug> \
  --branch  <label>       \
  --url     <targetUrl>   \
  [--key    <apiKey>]     \
  [--json]

Flags

Flag	Required	Description
`--org`	Yes	Your org slug
`--project`	Yes	Your project slug
`--branch`	Yes	Branch label — used as the routing key and display name
`--url`	Yes	Full target URL including webhook path
`--key`	No	API key (overrides env/config)
`--json`	No	Output result as JSON

Behaviour

If no deployment with this --branch label exists, it is created.
If a deployment with this label already exists, its URL is updated.
The command is idempotent — safe to call on every deploy from CI.

Example

hookman register \
  --org acme \
  --project payments \
  --branch feature/checkout \
  --url https://pr-42.myapp.com/api/webhooks/stripe

✓ Registered: feature/checkout → https://pr-42.myapp.com/api/webhooks/stripe
  Hookman endpoint: https://hookman.dev/w/acme/payments

`hookman remove`

Remove a deployment by label.

hookman remove \
  --org     <orgSlug>     \
  --project <projectSlug> \
  --branch  <label>       \
  [--key    <apiKey>]     \
  [--json]

Returns exit code 0 whether or not the deployment existed (idempotent — safe for CI cleanup jobs).

Example

hookman remove \
  --org acme \
  --project payments \
  --branch feature/checkout

✓ Removed: feature/checkout

`hookman switch`

Set the active deployment for manual-switch routing.

hookman switch \
  --org     <orgSlug>     \
  --project <projectSlug> \
  --branch  <label>       \
  [--key    <apiKey>]

After this command, all incoming webhooks to the project’s endpoint are forwarded to the named deployment — until you switch again or configure automatic routing.

Example

hookman switch \
  --org acme \
  --project payments \
  --branch feature/checkout

# → ✓ Active deployment set to: feature/checkout
# → Webhooks now routing to: https://pr-42.myapp.com/api/webhooks/stripe

`hookman rule`

Manage CLI/CI-driven conditional routing rules. See Routing strategies overview for how dynamic rules relate to manual (dashboard) rules, evaluation tiers, and priority — this section covers the CLI flags only.

`hookman rule set`

Create or update a dynamic routing rule.

hookman rule set \
  --name     <ruleName>    \
  --source   <source>      \
  --path     <path>        \
  --op       <op>          \
  [--value   <value>]      \
  --target   <branchLabel> \
  [--priority <n>]         \
  [--org     <orgSlug>]     \
  [--project <projectSlug>] \
  [--key     <apiKey>]

Flags

Flag	Required	Description
`--name`	Yes	Rule name — identifies the rule for later `set`/`remove` calls
`--source`	Yes	Where to read the condition from: `header`, `query`, `body`, or `body_raw`
`--path`	Yes	Header/query name, or dot-path into the JSON body (ignored for `body_raw`)
`--op`	Yes	Comparison operator: `eq`, `neq`, `contains`, `not_contains`, `starts_with`, `ends_with`, `exists`, `not_exists`, `regex`
`--value`	Only for ops other than `exists`/`not_exists`	Value to compare against
`--target`	Yes	Branch label of a deployment already registered via `hookman register` — resolved to that deployment’s target URL
`--priority`	No	Lower runs first among dynamic rules (default: appended after existing dynamic rules). Run `hookman rule ls` to see priorities already in use — a colliding value is rejected with a 400.
`--org`	No	Org slug
`--project`	No	Project slug
`--key`	No	API key (overrides env/config)

Behaviour

--target is a branch label, not a URL — it’s looked up against the project’s registered deployments (the same labels hookman register/switch use) and resolved to that deployment’s stored target URL.
The rule is created if --name doesn’t already exist, or updated in place if it does.
Publishes immediately — there’s no separate publish step, unlike manual rules created in the dashboard (see Routing strategies overview).

Example

hookman rule set \
  --org acme \
  --project payments \
  --name staging-header \
  --source header --path x-env --op eq --value staging \
  --target feature/checkout

✓ Created rule "staging-header" → feature/checkout (published v7)

`hookman rule remove`

Remove a dynamic routing rule by name, and publish the change immediately.

hookman rule remove \
  --name    <ruleName>    \
  [--org    <orgSlug>]     \
  [--project <projectSlug>] \
  [--key    <apiKey>]

Exits 0 whether or not the rule existed (idempotent — safe for CI cleanup jobs).

Example

hookman rule remove --org acme --project payments --name staging-header

✓ Removed rule: staging-header

`hookman rule ls`

List dynamic routing rules for a project, including each rule’s priority — useful for picking a free slot before calling rule set --priority.

hookman rule ls [--org <orgSlug>] [--project <projectSlug>] [--key <apiKey>] [--json]

Example

hookman rule ls --org acme --project payments

Managed rules in acme/payments
  ●    5  staging-header       header[x-env] eq "staging" → https://pr-42.myapp.com/api/webhooks/stripe

`hookman ls`

List orgs, an org’s projects, or a project’s deployments — drill down by adding --org, then --project.

hookman ls [--org <orgSlug>] [--project <projectSlug>] [--key <apiKey>] [--json]

Flags

Flag	Required	Description
`--org`	No	Org slug — list its projects instead of all orgs
`--project`	No	Project slug (with `--org`) — list its deployments instead of projects
`--key`	No	API key (overrides env/config)
`--json`	No	Output as JSON

Behaviour

Bare hookman ls lists every org you belong to.
hookman ls --org <orgSlug> lists that org’s projects.
hookman ls --org <orgSlug> --project <projectSlug> lists that project’s deployments.

Example

hookman ls

Organisations
  · acme (owner, pro)

hookman ls --org acme

Projects in acme
  · payments (Payments)

hookman ls --org acme --project payments

Deployments in acme/payments
  ● main               https://myapp.com/api/webhooks/stripe
  ○ feature/checkout   https://pr-42.myapp.com/api/webhooks/stripe

`hookman listen`

Forward a deployment’s webhook traffic to your local machine (mirrors stripe listen). Useful for developing against real webhooks — Stripe, Paddle, etc. — without deploying first.

hookman listen \
  --forward-to <url>   \
  --branch     <label> \
  [--org       <orgSlug>]     \
  [--project   <projectSlug>] \
  [--key       <apiKey>]

Flags

Flag	Required	Description
`--forward-to`	Yes	Local URL to deliver webhooks to, e.g. `localhost:4242/webhook`
`--branch`	Yes	Deployment label to attach to
`--org`	No	Org slug
`--project`	No	Project slug
`--key`	No	API key (overrides env/config)

Behaviour

Enables local mode for the deployment, then opens a persistent connection and streams matching webhooks to --forward-to as they arrive — your local server sees the same request the upstream provider sent.
The dashboard’s routing tools show the deployment as “local mode” while hookman listen is running, and “listening” once the connection is live.
Ctrl+C disables local mode and closes the connection. Only one listener can be active per deployment at a time.

Example

hookman listen \
  --org acme \
  --project payments \
  --branch feature/checkout \
  --forward-to localhost:4242/webhook

✓ Local mode enabled for feature/checkout
Ready! Forwarding feature/checkout webhooks to http://localhost:4242/webhook
  Ctrl+C to stop
  POST → 200

`hookman logs`

Show recent webhook deliveries for a project.

hookman logs [--org <orgSlug>] [--project <projectSlug>] [--limit <n>] [--status <class>] [--method <list>] [--replay-only] [--key <apiKey>] [--json]

Flag	Required	Description
`--limit`	No	Number of deliveries to show (max 200, default 50)
`--status`	No	Status classes, comma-separated, e.g. `2xx` or `4xx,5xx`
`--method`	No	HTTP methods, comma-separated, e.g. `POST,GET`
`--replay-only`	No	Only show replayed deliveries
`--org`, `--project`, `--key`, `--json`	No	As for the other commands

`hookman tail`

Stream a project’s deliveries as they arrive. See Live tail & routing decisions for what each line means.

hookman tail [--org <orgSlug>] [--project <projectSlug>] [--branch <label>] [--rule <name>] [--status <class>] [--method <list>] [--show-body] [--json] [--key <apiKey>]

Flag	Required	Description
`--branch`	No	Only deliveries routed to this deployment label
`--rule`	No	Only deliveries matched by this rule (by name)
`--status`	No	Status classes, comma-separated, e.g. `4xx,5xx`
`--method`	No	HTTP methods, comma-separated
`--show-body`	No	Also print each request body (needs payload storage on)
`--json`	No	One JSON object per line instead of text
`--org`, `--project`, `--key`	No	As for the other commands

It starts from now (no history), reconnects automatically if the connection drops, and stops cleanly on Ctrl+C.

`hookman inbox`

Throwaway email addresses for testing sign-up, verification and magic-link flows. Available on Pro and Team, and currently rolled out behind a feature flag — if your org doesn’t have it yet, commands fail with feature_not_enabled.

hookman inbox create [--label <note>] [--ttl <duration>] [--allow <sender>]... [--notify-url <url>]   # → [email protected]
hookman inbox ls
hookman inbox wait <inbox> [--since <iso>] [--timeout <duration>] [--extract code|link] [--match <regex>]
hookman inbox attachments <inbox> [--message <id>] [--out <dir>]
hookman inbox rm <inbox>

All subcommands accept --org, --key and --json.

create expires after --ttl (default 24h, max 30d).
wait blocks until mail arrives and prints the newest message, including extracted links and one-time codes; it exits 1 on timeout (--timeout, default 60s).
wait --extract code|link prints only the first one-time code (or link) of the newest message, with nothing else on stdout, so it works in scripts: CODE=$(hookman inbox wait "$ADDR" --extract code). It exits 1 on timeout or when the message has none. Add --match <regex> to take the first code or link matching a case-insensitive regex, for example --extract link --match verify.
create --allow restricts the inbox to mail from the given addresses or *@domain patterns (repeat the flag or comma-separate). Mail from anyone else is bounced with a generic “Mailbox unavailable” and does not count toward your monthly message quota. Senders can be forged, so this reduces noise and quota abuse but is not authentication; keep the address itself private.
create --notify-url makes Hookman POST {inboxId, address, messageId, from, subject, receivedAt} (no message content) to that public https URL when mail arrives. Delivery is best effort, with a short timeout and no retries or redirects.
attachments downloads a message’s attachments (newest message by default) into --out.
rm deletes the inbox and its messages.

Environment variables

Variable	Description
`HOOKMAN_API_KEY`	API key used for all commands. Takes precedence over `~/.hookman/config.json`.
`HOOKMAN_ORG`	Default org slug — used when `--org` is omitted.
`HOOKMAN_PROJECT`	Default project slug — used when `--project` is omitted.
`HOOKMAN_API_URL`	API host the CLI talks to. Defaults to `https://api.hookman.dev` — set this to point at a self-hosted instance.
`HOOKMAN_APP_URL`	Dashboard host `hookman login` opens in the browser. Defaults to `https://app.hookman.dev` — set alongside `HOOKMAN_API_URL` for a self-hosted instance.

Setting HOOKMAN_ORG and HOOKMAN_PROJECT lets you shorten commands in a single-project CI environment:

# In your CI environment:
# HOOKMAN_API_KEY=hm_live_xxx
# HOOKMAN_ORG=acme
# HOOKMAN_PROJECT=payments

hookman register --branch feature/checkout --url https://pr-42.myapp.com/api/webhooks/stripe
hookman remove   --branch feature/checkout

Exit codes

Code	Meaning
`0`	Success
`1`	Any failure — auth, not found, quota, network, etc. (see stderr for details)

hookman remove is the one exception: it exits 0 even if the deployment didn’t exist, since removing something already gone is not a failure (see above).

Using in CI/CD

GitHub Actions

- name: Register deployment
  env:
    HOOKMAN_API_KEY: ${{ secrets.HOOKMAN_API_KEY }}
  run: |
    npx hookman register \
      --org acme \
      --project payments \
      --branch ${{ github.head_ref }} \
      --url ${{ steps.deploy.outputs.preview-url }}/api/webhooks/stripe

GitLab CI

register-hookman:
  stage: deploy
  script:
    - npx hookman register
        --org $HOOKMAN_ORG
        --project payments
        --branch $CI_COMMIT_REF_NAME
        --url $CI_ENVIRONMENT_URL/api/webhooks/stripe
  variables:
    HOOKMAN_API_KEY: $HOOKMAN_API_KEY