Metadata-Version: 2.5
Name: hookstride-cli
Version: 0.2.1
Summary: Command-line access to Hookstride projects, webhook activity, and billing.
License: Proprietary
Requires-Python: >=3.11
Requires-Dist: click<9,>=8.1
Requires-Dist: httpx<1,>=0.28
Requires-Dist: prompt-toolkit<4,>=3.0.52
Requires-Dist: rich<15,>=14
Requires-Dist: typer<1,>=0.20
Description-Content-Type: text/markdown

# Hookstride CLI

Hookstride CLI provides command-line access to project information, webhook activity, incoming integrations, and billing records in Hookstride. It includes an interactive console for inspecting the same information without using the web dashboard.

The current release supports read operations only. It cannot create or modify destinations, replay deliveries, manage credentials, or initiate payments.

## Installation

Requires Python 3.11 or later.

```bash
uv tool install hookstride-cli
```

Alternatively, use `pipx install hookstride-cli`.

```bash
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:

```bash
hookstride console
```

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

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

```bash
hookstride status
hookstride auth status
hookstride projects list
hookstride projects use PROJECT_UUID

hookstride destinations list
hookstride keys list
hookstride events list --status failed
hookstride events show EVENT_UUID
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 `PROJECT_UUID` and `EVENT_UUID` with identifiers from your account.

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

```bash
hookstride --project PROJECT_UUID events list
```

### Interactive console

```bash
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`.

### JSON output

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

```bash
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.

## Environments and local settings

The CLI connects to the development API by default: `https://api-dev.hookstride.voteeasy.net`.

To access production, select it explicitly:

```bash
hookstride --env production console
```

Production requests use `https://api.hookstride.voteeasy.net`. 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

Product documentation: https://hookstride.voteeasy.net/docs

Source: https://github.com/quarj0/webhook-reliability-api/tree/main/cli
