Metadata-Version: 2.5
Name: hookstride-cli
Version: 0.2.0
Summary: Readable, project-scoped Hookstride Control API terminal client.
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

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:

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

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

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

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

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

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

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