Hookstride CLI

A fast, colorful, read-only terminal for the Hookstride Control API. Inspired by the clarity of tools like Nmap, it keeps ordinary REST responses unchanged for apps and integrations.

Install

Once the first package release is available on PyPI, install with:

uv tool install hookstride-cli
hookstride --version
hookstride console

Alternative: pipx install hookstride-cli. Update with uv tool upgrade hookstride-cli. Requires Python 3.11 or newer. No checkout or Django backend installation is needed.

Authentication

In the Hookstride dashboard, generate an MFA-verified Control API / Management token, beginning with whrctl_. Do not use a whrk_ delivery API key, and never paste a token directly into commands or issue comments.

The CLI reads HOOKSTRIDE_CONTROL_TOKEN from your current shell; it does not persist tokens on disk. For a Bash/Zsh terminal, paste interactively without writing the token in your command history:

printf "Control token: "
read -rs HOOKSTRIDE_CONTROL_TOKEN
printf "\\n"
export HOOKSTRIDE_CONTROL_TOKEN

hookstride auth status

The token may remain in your shell environment until you run unset HOOKSTRIDE_CONTROL_TOKEN. Environment values may be inspectable by processes with the appropriate local privileges; use an ephemeral, limited-life management token. Avoid recording terminal sessions while entering secrets.

Explore development

hookstride status
hookstride auth status
hookstride projects list
hookstride projects use 00000000-0000-0000-0000-000000000000

hookstride destinations list
hookstride keys list
hookstride incoming sources
hookstride incoming routes
hookstride incoming bindings
hookstride incoming registration-keys
hookstride events list --status failed
hookstride events show 00000000-0000-0000-0000-000000000000
hookstride stats
hookstride billing status
hookstride billing history
hookstride config show

Replace the sample UUIDs with your own project/event IDs.

The CLI starts on https://api-dev.hookstride.voteeasy.net. Use --env production (before the command) to target https://api.hookstride.voteeasy.net; configure each environment with its own corresponding Control token. The apex https://hookstride.voteeasy.net serves the frontend. You can also use --api-url https://your-api-host for a custom origin, or HTTP on loopback for local testing.

Project selection is environment-specific. The only persisted data is a project UUID in ~/.config/hookstride/settings.json, owner-readable; not your credentials. Override temporarily with --project PROJECT_UUID.

Development checks

When the GitHub Actions runner is unavailable, run the same CLI tests locally without sending anything to the live Hookstride API:

bash cli/scripts/check.sh

This checks Python syntax, Ruff, isolated unit tests using mocked HTTP responses, and basic commands. A successful local run is not a substitute for a live read-only smoke test against the deployed development API.

Tables use compact, borderless columns. Identifiers and long URLs are shortened only when necessary to fit the terminal; the actual API response is not changed. Use --json to copy complete project IDs, payment references and destination URLs.

Interactive operator console (v0.2)

Start a lightweight, Metasploit-inspired, read-only interactive console:

hookstride console

The shell starts on the development API by default. Enter help for available commands, use Tab for completion, Ctrl+C to cancel the current line, and Ctrl+D or exit to close the console.

HOOKSTRIDE CONSOLE v0.2
hookstride [dev] > auth login
Control token (hidden):
✓ Authenticated as developer@example.com
hookstride [dev] > show projects
Projects
========
Name        Workspace     Role   Plan    Project ID
----------  ------------  -----  ------  ------------------------------------
Production  Beta Testing  owner  flex    ddc21845-d0f1-49af-8d35-2719dc641f69

hookstride [dev] > use ddc21845-d0f1-49af-8d35-2719dc641f69
hookstride [dev:ddc21845] > show payments
hookstride [dev:ddc21845] > events list --status failed
hookstride [dev:ddc21845] > show destinations
hookstride [dev:ddc21845] > json events list
hookstride [dev:ddc21845] > back
hookstride [dev] > exit

This console accepts the existing read-only CLI commands, plus convenient show aliases, set env dev|production, use UUID, back, clear, history, and auth login|logout. projects use UUID and use UUID persist only the active project's UUID in local settings. The console does not support a shell escape, external processes, POST/DELETE operations, or purchases.

Token handling

auth login securely prompts for a Control API token via hidden input. Tokens are kept in memory for this console process only, are discarded at exit, are never written to a config or history file, and are never echoed. The console stores only a safe subset of commands in volatile arrow-key history; it never records tokens or arbitrary query/search strings.

You may also provide an existing token through environment variables:

# Use a development token with the default development console
export HOOKSTRIDE_DEV_CONTROL_TOKEN="…"  # do not put real secrets in shell history
hookstride console

# To start directly against production, explicitly select it
hookstride --env production console

For safest handling, prefer auth login over typing tokens in shell commands. For interactive environment changes, the generic legacy HOOKSTRIDE_CONTROL_TOKEN is never forwarded to another environment. Use auth login separately after set env production, or provide a matching HOOKSTRIDE_PRODUCTION_CONTROL_TOKEN token. This prevents a dev token from accidentally being sent to the production API.

The console requires a real interactive terminal and refuses --json console. For CI and scripting, use ordinary commands such as hookstride --json events list instead.

Output for scripts

Pass --json before the command:

hookstride --json projects list | jq .
hookstride --json events list --status failed | jq '.results'
hookstride --env production --json billing history

The raw structured response is printed to stdout without terminal formatting. Network and HTTP errors go to stderr and cause a nonzero exit status.

Scope

Version 0.2 includes interactive access to project, destination, incoming-source, delivery-stat, activity and billing reads. It does not yet create destinations, emit events, replay events, rotate credentials, or trigger payments. Those workflows require additional confirmation and integration tests before exposing them in a CLI. Server-side authorization, project scoping, and response redaction remain enforced by the Control API.

Do not store passwords, signing secrets, private keys, or Paystack keys in Hookstride CLI configuration.