Skip to content
HookspotDocs

Search by task, command or setting.

    WebsiteOpen the app

    Install and log in

    Install the hookspot CLI, log in, and check the project it uses.

    The Hookspot CLI, hookspot, receives webhooks from Hookspot and forwards them to the app on your machine. Install it, log in, then check its project.

    Install the CLI

    Section titled “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.

    hookspot version tells you when a newer release is out. Update with npm install -g @hookspot/cli@latest or brew upgrade hookspot-cli.

    Log in

    Section titled “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

    Section titled “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

    Section titled “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.

    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.