Install and log in

The Hookspot CLI, hookspot, receives webhooks from Hookspot and forwards them to the app on your machine. Install it, log in, check its project, and upgrade it when a newer release is out.

Install the CLI

Install the CLI with npm, which needs Node.js 18 or newer:

npm install -g @hookspot/cli

On macOS or Linux, you can use Homebrew instead:

brew install hookspot/hookspot/hookspot-cli

Without Node.js or Homebrew, download the archive for your system from the latest release. Its INSTALL.md lists the steps.

Log in

hookspot login opens your browser and prints a code:

hookspot login

╭─ Log in ──────────────────────────╮
│ Confirm this code in your browser │
│                                   │
│   2NCL-AXSJ                       │
╰───────────────────────────────────╯
https://<hookspot-host>/cli/login/<token>
○ Waiting for approval… (Ctrl+C to cancel)
✓ Logged in as you@example.com
✓ Active project set to Documentation demo | Default project

In the browser:

1. Sign in to Hookspot if it asks.
2. Check that the Confirmation code matches the code in your terminal.
3. Pick an Organization and a Project.
4. Click Approve login.

The CLI saves a CLI key and the project you picked, then prints the last two lines. If no browser opens, for example on a remote machine, open the printed URL on your own computer. The link expires after 10 minutes.

Check the project

hookspot listen uses one project, the CLI’s active project. List the projects you can open:

hookspot project list

╭─ Projects ──────────────────────────────────────────────────────────────── 1 ─╮
│ UID                              ORGANIZATION        PROJECT                  │
├───────────────────────────────────────────────────────────────────────────────┤
│ proj_TgGWpwkrXkmA06kUc8LY1PaoCq  Documentation demo  Default project  active  │
╰───────────────────────────────────────────────────────────────────────────────╯

active marks the CLI’s active project. To switch, see Choose the CLI’s project.

Use a CLI key in CI

A CI job has no browser to approve a login, so the CLI reads its key from HOOKSPOT_CLI_KEY instead.

1. In Hookspot, open the user menu and click Account settings.
2. Select CLI key and copy the key.
3. In your CI system, save the key as a secret and expose it as the environment variable HOOKSPOT_CLI_KEY.

Caution

The CLI key opens every project your account can open. Keep it in a secret store, never in a command, a commit or a screenshot.

In the job, pass the project’s UID from hookspot project list:

hookspot --project proj_TgGWpwkrXkmA06kUc8LY1PaoCq listen --forward-to http://localhost:3000

╭─ Listening in Documentation demo | Default project ───────────────────────── 1 source • 1 route ─╮
│ Docs demo  https://<webhook-host>/RtXNHZuNw0VPjir0kS0v9L2sgE                                     │
│   → http://localhost:3000/webhooks                                                               │
╰──────────────────────────────────────────────────────────────────────────────────── ctrl-c quit ─╯
Connecting…
Ready. Waiting for requests (Ctrl-C to quit)
No requests yet. Check the whole path with a test event:

  curl -X POST 'https://<webhook-host>/RtXNHZuNw0VPjir0kS0v9L2sgE' -H 'Content-Type: application/json' -d '{"type":"hookspot.test"}'
#1   POST  Docs demo  /webhooks  order.created                              200    3ms  22:42:24.746

This is the CLI’s plain-text output. Wait for the Ready. line before the job sends webhooks.

Upgrading

Upgrade the CLI the way you installed it. For npm, run:

npm install -g @hookspot/cli@latest

For Homebrew, run:

brew upgrade hookspot-cli

For Docker, pull the newest image:

docker pull hookspot/cli

For a release archive, take these steps:

1. Download the new archive for your system from the latest release.
2. Replace the executable you installed with the one inside, as the archive’s INSTALL.md describes.

hookspot listen in a terminal and hookspot version tell you when a newer release is out. Check the upgrade with hookspot version, or with docker run --rm hookspot/cli version for Docker.

A CLI version stops working only when Hookspot drops something that version needs. hookspot listen warns you at least 30 days before that version stops working, unless a security fix cannot wait.