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 install -g hookman

pnpm add -g hookman

# Use directly without installing
npx hookman <command>

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

List all deployments for a project.

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

Example output

Project: acme/payments
Endpoint: https://hookman.dev/w/acme/payments

  BRANCH                   URL                                           ACTIVE
  main                     https://myapp.com/api/webhooks/stripe
  feature/checkout    ●    https://pr-42.myapp.com/api/webhooks/stripe   active
  feature/billing          https://pr-51.myapp.com/api/webhooks/stripe

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.

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`	General error (see stderr for details)
`2`	Authentication failure — no API key found or key is invalid
`3`	Not found — org, project, or deployment does not exist
`4`	Quota exceeded — free tier limit reached

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