CLI reference

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

Installation

npm

npm install -g @hookman/cli

pnpm

pnpm add -g @hookman/cli

npx (no install)

# 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:

1. --key <key> flag (explicit, highest priority)
2. HOOKMAN_API_KEY environment variable
3. ~/.hookman/config.json (written by hookman login)
4. .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

Register a deployment, or update it if the label already exists.

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 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

---

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

Tip

For GitHub specifically, use the Hookman GitHub Action instead — it handles deployment_status events automatically and doesn’t require you to extract the preview URL manually.

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