Hookstride CLI

Hookstride CLI lets you manage projects and webhook destinations, inspect delivery activity, and view billing records. It includes an interactive console with the same selected-project commands.

Version 0.3.1 adds signed test-event sending with an existing project's delivery API key, and optional delivery-status polling. Project and destination management remain available; billing and credential changes, delivery replay, and destructive operations remain unavailable.

Installation

Requires Python 3.11 or later.

uv tool install hookstride-cli

Alternatively, use pipx install hookstride-cli.

hookstride --version
hookstride status
hookstride console

Upgrade an existing installation with uv tool upgrade hookstride-cli.

Authentication

Authenticated commands require a Control API token (whrctl_), available from your Hookstride dashboard. Project delivery API keys (whrk_) do not grant CLI access.

In an interactive console, run auth login and enter the token at the hidden prompt:

hookstride console

For one-off commands, set HOOKSTRIDE_CONTROL_TOKEN in your shell without entering it on the command line:

read -rs "HOOKSTRIDE_CONTROL_TOKEN?Control token: "
echo
export HOOKSTRIDE_CONTROL_TOKEN
hookstride auth status

The read example above works in zsh. In Bash, use read -rs -p "Control token: " HOOKSTRIDE_CONTROL_TOKEN followed by echo and export HOOKSTRIDE_CONTROL_TOKEN.

Tokens entered through auth login are retained only for the interactive console session. The CLI does not write tokens to its settings file.

Commands

hookstride status
hookstride auth status
hookstride projects list
hookstride projects use PROJECT_UUID
hookstride projects create --account ACCOUNT_UUID --name "Staging" --slug staging
hookstride projects update PROJECT_UUID --name "Production EU"

hookstride destinations list
hookstride destinations create --name "Webhook receiver" --url "https://app.example.com/webhooks/hookstride"
hookstride destinations update DESTINATION_UUID --url "https://api.example.com/webhooks/hookstride"
hookstride destinations update DESTINATION_UUID --pause
hookstride destinations update DESTINATION_UUID --resume
hookstride keys list
hookstride events list --status failed
hookstride events show EVENT_UUID
hookstride events send DESTINATION_UUID --type webhook.test --wait
hookstride stats

hookstride incoming sources
hookstride incoming routes
hookstride incoming bindings
hookstride incoming registration-keys

hookstride billing status
hookstride billing history
hookstride config show

Replace the example UUIDs with identifiers from your account. Find your workspace's account_id with hookstride --json projects list; that ID is required for project creation. Project creation and renaming require an admin/owner role. Destination changes require developer access or higher.

Commands that operate on a project use the selected project. You can override the selection for an individual command:

hookstride --project PROJECT_UUID events list

Interactive console

hookstride console

Use help to view commands, Tab for completion, and exit or Ctrl+D to leave. The console also supports show projects, show events, show destinations, use PROJECT_UUID, back, and set env dev|production. The same projects create/update, destinations create/update, and events send commands work inside the console. Commands with customer-provided names and URLs are not saved to console history.

JSON output

Use --json before a command to retrieve structured data for scripts:

hookstride --json projects list
hookstride --project PROJECT_UUID --json events list --status failed
hookstride --env production --json billing history

Errors go to standard error; unsuccessful requests return a nonzero exit code. When creating a destination, the server returns a signing secret once. Save it securely immediately. Both terminal output and --json deliberately include that one-time secret, so avoid piping creation output into logs or public CI artifacts.

Send a test event

Use an existing active destination from hookstride destinations list. The command securely prompts for a project delivery API key (whrk_). It cannot use a Control API token (whrctl_); these credentials have different permissions.

hookstride --env production projects use PROJECT_UUID
hookstride --env production events send DESTINATION_UUID --wait
hookstride --env production events show EVENT_UUID

The event type defaults to webhook.test, with a harmless JSON payload: {"message":"Hookstride CLI delivery test","source":"cli"}. To send a different JSON object without placing its contents in shell history:

hookstride --env production events send DESTINATION_UUID --type demo.delivery --payload-file ./demo-payload.json --wait

To avoid the hidden prompt, set HOOKSTRIDE_PRODUCTION_API_KEY or HOOKSTRIDE_DEV_API_KEY for the matching environment only. Never add keys to CLI arguments, commit them to Git, or paste them into a public CI log. The CLI does not save delivery keys or their prompts in its configuration or history. The --wait flag polls for a terminal status and exits nonzero if delivery fails. A non-delivered event can be examined using events show with the usual Control token.

Environments and local settings

The CLI connects to the production API by default: https://api.hookstride.com. A new release must be published to PyPI before existing installations receive this change.

To inspect the development API explicitly, select it:

hookstride --env dev console

Development requests use https://api-dev.hookstride.com. Use a Control API token issued for the selected environment. A custom HTTPS API origin can be supplied with --api-url.

Project selections are stored separately by environment in ~/.config/hookstride/settings.json. This file contains project identifiers, not authentication tokens. Console tokens and command history remain in memory and are discarded at exit.

Documentation

Documentation: https://hookstride.com