Metadata-Version: 2.5
Name: hookstride-cli
Version: 0.3.1
Summary: Manage Hookstride projects and destinations, inspect 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 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.

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

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

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

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

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

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