hookstride-cli 0.2.0__py3-none-any.whl

hookstride_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Hookstride developer CLI."""
+
+__version__ = "0.2.0"

hookstride_cli/console.py

@@ -0,0 +1,456 @@
+"""Interactive, read-only Hookstride console.
+
+The console intentionally does not execute shell commands. It uses the same
+project-scoped Control API commands as the CLI, keeps tokens only in memory,
+and stores no history on disk.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import getpass
+import os
+import shlex
+import uuid
+import warnings
+from collections.abc import Iterator
+
+import click
+from prompt_toolkit import PromptSession
+from prompt_toolkit.completion import WordCompleter
+from prompt_toolkit.formatted_text import FormattedText
+from prompt_toolkit.history import InMemoryHistory
+from typer.main import get_command
+
+from . import main as cli
+
+# Only these typed commands may execute through the console.
+# Future write actions must be explicitly reviewed, not implicitly unlocked.
+READ_COMMANDS: dict[str, set[str]] = {
+    "auth": {"status"},
+    "projects": {"list", "use"},
+    "destinations": {"list"},
+    "keys": {"list"},
+    "events": {"list", "show"},
+    "billing": {"status", "history"},
+    "incoming": {"sources", "routes", "bindings", "registration-keys"},
+    "config": {"show"},
+}
+ROOT_COMMANDS = {"status", "stats"}
+
+# Aliases that feel like a familiar operator console, but remain read-only.
+SHOW_TARGETS: dict[str, tuple[str, ...] | None] = {
+    "options": None,
+    "projects": ("projects", "list"),
+    "destinations": ("destinations", "list"),
+    "keys": ("keys", "list"),
+    "events": ("events", "list"),
+    "billing": ("billing", "status"),
+    "payments": ("billing", "history"),
+    "sources": ("incoming", "sources"),
+    "routes": ("incoming", "routes"),
+    "bindings": ("incoming", "bindings"),
+    "registration-keys": ("incoming", "registration-keys"),
+    "stats": ("stats",),
+    "status": ("status",),
+}
+
+SAFE_HISTORY_COMMANDS = frozenset(
+    [
+        "help", "?", "clear", "exit", "quit", "back", "status", "stats",
+        "history", "auth login", "auth logout", "auth status",
+        "projects list", "destinations list", "keys list", "billing status",
+        "billing history", "events list", "incoming sources",
+        "incoming routes", "incoming bindings", "incoming registration-keys",
+        "config show",
+        *(f"show {name}" for name in SHOW_TARGETS),
+        "set env dev", "set env production",
+    ]
+)
+COMMAND_COMPLETIONS = sorted(
+    {
+        *SAFE_HISTORY_COMMANDS,
+        "use ", "projects use ", "events show ", "events list --status ",
+        "events list --origin ", "events list --page ", "set project ",
+        "set env ", "json ", "show ", "auth ",
+    }
+)
+
+
+def _project_uuid(value: str) -> str:
+    try:
+        return str(uuid.UUID(value))
+    except (ValueError, AttributeError):
+        raise cli.CLIError("Expected a valid project UUID.") from None
+
+
+def _saved_project(environment: str) -> str | None:
+    settings = cli._read_config().get("projects", {})
+    value = settings.get(environment) if isinstance(settings, dict) else None
+    if not value:
+        return None
+    # An old/corrupt settings file should not crash the console.
+    try:
+        return _project_uuid(value)
+    except cli.CLIError:
+        return None
+
+
+def _history_safe(line: str) -> bool:
+    """Only retain recognized non-sensitive commands in process memory."""
+    if len(line) > 180 or any(ord(ch) < 32 or ord(ch) > 126 for ch in line):
+        return False
+    line = line.strip()
+    if line in SAFE_HISTORY_COMMANDS:
+        return True
+    tokens = line.split()
+    if len(tokens) == 2 and tokens[0] == "use":
+        try:
+            _project_uuid(tokens[1])
+            return True
+        except cli.CLIError:
+            return False
+    if len(tokens) == 3 and tokens[:2] in (
+        ["projects", "use"], ["set", "project"], ["events", "show"],
+    ):
+        try:
+            _project_uuid(tokens[2])
+            return True
+        except cli.CLIError:
+            return False
+    return False
+
+
+class SafeMemoryHistory(InMemoryHistory):
+    """Only safe, non-sensitive recognized commands enter arrow-key history."""
+
+    def append_string(self, string: str) -> None:
+        if _history_safe(string):
+            super().append_string(string)
+
+
+class HookstrideConsole:
+    def __init__(self, session: cli.Session) -> None:
+        self.session = session
+        self.start_environment = session.environment
+        self.origins = dict(cli.ORIGINS)
+        self.origins[session.environment] = session.origin
+        self.project = session.project or _saved_project(session.environment)
+        self.session.project = self.project
+        self.tokens: dict[str, str] = {}  # volatile; never persisted or printed
+        self.logged_out: set[str] = set()
+        self.history = SafeMemoryHistory()
+        self.click_command = get_command(cli.app)
+        self.completer = WordCompleter(
+            COMMAND_COMPLETIONS, ignore_case=True, sentence=True,
+        )
+
+    @property
+    def environment(self) -> str:
+        return self.session.environment
+
+    def _current_token(self) -> str | None:
+        env = self.environment
+        if env in self.logged_out:
+            return None
+        if token := self.tokens.get(env):
+            return token
+        if token := os.getenv(f"HOOKSTRIDE_{env.upper()}_CONTROL_TOKEN"):
+            return token if token.startswith("whrctl_") else None
+        # The legacy generic token is bound ONLY to the initial environment.
+        # Do not forward a development token to production on "set env".
+        if env == self.start_environment:
+            token = os.getenv("HOOKSTRIDE_CONTROL_TOKEN", "")
+            return token if token.startswith("whrctl_") else None
+        return None
+
+    @contextlib.contextmanager
+    def _token_scope(self) -> Iterator[None]:
+        """Temporarily expose just the selected environment's token to the CLI."""
+        previous = os.environ.get("HOOKSTRIDE_CONTROL_TOKEN")
+        current = self._current_token()
+        if current:
+            os.environ["HOOKSTRIDE_CONTROL_TOKEN"] = current
+        else:
+            os.environ.pop("HOOKSTRIDE_CONTROL_TOKEN", None)
+        try:
+            yield
+        finally:
+            if previous is None:
+                os.environ.pop("HOOKSTRIDE_CONTROL_TOKEN", None)
+            else:
+                os.environ["HOOKSTRIDE_CONTROL_TOKEN"] = previous
+
+    def _write(self, message: str) -> None:
+        # Message is trusted markup. Never interpolate raw API fields.
+        self.session.console.print(message)
+
+    def _error(self, message: str) -> None:
+        self._write(f"[red]✗[/red] {cli._escaped(message)}")
+
+    def _show_help(self) -> None:
+        self._write(
+            "\n"
+            "[bold]help[/bold]                  Show console help\n"
+            "[bold]show options[/bold]          Display environment, project and authentication\n"
+            "[bold]show projects[/bold]         List accessible projects\n"
+            "[bold]use UUID[/bold]              Select a project (also saves preference)\n"
+            "[bold]back[/bold]                  Leave the active project context\n"
+            "[bold]set env dev[/bold]           Switch to development API\n"
+            "[bold]set env production[/bold]    Switch to production API\n"
+            "[bold]auth login[/bold]            Enter a management token invisibly\n"
+            "[bold]auth logout[/bold]           Clear the current environment's session token\n"
+            "[bold]auth status[/bold]           Validate current token\n"
+            "[bold]show destinations[/bold]     Inspect outgoing webhooks\n"
+            "[bold]show events[/bold]           View recent events\n"
+            "[bold]events list --status failed[/bold]   Filter delivery history\n"
+            "[bold]events show UUID[/bold]      Inspect a delivery and attempts\n"
+            "[bold]show billing[/bold]          View plan and credits\n"
+            "[bold]show payments[/bold]         View payment history\n"
+            "[bold]show sources[/bold]          Inspect incoming sources\n"
+            "[bold]show keys[/bold]             List masked keys\n"
+            "[bold]json projects list[/bold]    Print the complete JSON response\n"
+            "[bold]history[/bold]               Recall recognized safe commands (memory only)\n"
+            "[bold]clear[/bold]                 Clear screen\n"
+            "[bold]exit[/bold]                  Close this console\n\n"
+
+        )
+
+    def _show_options(self) -> None:
+        project = self.project or "none"
+        rows = [
+            ["Environment", self.environment],
+            ["API", self.session.origin],
+            ["Project", project],
+            ["Authenticated token", "configured" if self._current_token() else "missing"],
+            ["Mode", "read-only"],
+        ]
+        cli._table(_FakeContext(self.session), "Session options", ["Setting", "Value"], rows)
+
+    def _history(self) -> None:
+        commands = list(self.history.get_strings())
+        if not commands:
+            self._write("[dim]No safe commands in history.[/dim]")
+            return
+        for i, command in enumerate(reversed(commands[-20:]), 1):
+            self._write(f"[dim]{i:>3}[/dim]  {cli._escaped(command)}")
+
+    def _set_environment(self, target: str) -> None:
+        if target not in cli.ORIGINS:
+            raise cli.CLIError("Use 'set env dev' or 'set env production'.")
+        self.session.environment = target
+        self.session.origin = self.origins[target]
+        self.project = _saved_project(target)
+        self.session.project = self.project
+        self._write(
+            f"[green]✓[/green] Environment: [bold]{target}[/bold] "
+            f"({_env_hint(self._current_token())})"
+        )
+
+    def _login(self) -> None:
+        # getpass does not echo, and is not part of the PromptSession history.
+        try:
+            # getpass normally degrades to VISIBLE input on unsupported terminals.
+            # Treat that warning as an exception before it can read a credential.
+            with warnings.catch_warnings():
+                warnings.simplefilter("error", getpass.GetPassWarning)
+                token = getpass.getpass("Control token (hidden): ").strip()
+        except getpass.GetPassWarning:
+            raise cli.CLIError(
+                "Cannot hide token input on this terminal. Authentication cancelled."
+            ) from None
+        except (KeyboardInterrupt, EOFError):
+            raise cli.CLIError("Authentication cancelled.") from None
+        if (
+            not token.startswith("whrctl_")
+            or not 16 <= len(token) <= 512
+            or any(ch.isspace() for ch in token)
+        ):
+            raise cli.CLIError("Expected a valid Control API management token.")
+        previous = self.tokens.get(self.environment)
+        logged_out = self.environment in self.logged_out
+        self.tokens[self.environment] = token
+        self.logged_out.discard(self.environment)
+        try:
+            with self._token_scope():
+                info = cli._request(self.session, "/control/v1/me/")
+        except (cli.CLIError, ValueError, TypeError):
+            if previous is None:
+                self.tokens.pop(self.environment, None)
+            else:
+                self.tokens[self.environment] = previous
+            if logged_out:
+                self.logged_out.add(self.environment)
+            raise cli.CLIError("Token verification failed for this environment.") from None
+        account = (info.get("user") or {}).get("email") if isinstance(info, dict) else None
+        if account:
+            self._write(f"[green]✓[/green] Authenticated as {cli._escaped(account)}")
+        else:
+            self._write("[green]✓[/green] Management token verified.")
+
+    def _logout(self) -> None:
+        self.tokens.pop(self.environment, None)
+        self.logged_out.add(self.environment)
+        self._write("[green]✓[/green] Signed out for this console environment.")
+
+    def _execute_cli(self, args: list[str], *, json_output: bool = False) -> None:
+        """Invoke existing read-only Click/Typer commands, never a shell."""
+        if not _allowed_cli(args):
+            raise cli.CLIError("Unknown or unavailable command. Type 'help'.")
+        group = args[0]
+        action = args[1] if len(args) > 1 else None
+        if _requires_project(group, action) and not self.project:
+            raise cli.CLIError("No project selected. Run 'show projects' then 'use UUID'.")
+        if _requires_token(group, action) and not self._current_token():
+            raise cli.CLIError("No management token for this environment. Run 'auth login'.")
+        options = ["--env", self.environment, "--api-url", self.session.origin]
+        if self.project:
+            options += ["--project", self.project]
+        if json_output:
+            options.append("--json")
+        try:
+            with self._token_scope():
+                self.click_command.main(
+                    args=[*options, *args],
+                    prog_name="hookstride",
+                    standalone_mode=False,
+                )
+        except click.exceptions.Exit as exc:
+            # 'status' already displayed a red Offline panel. Do not add an
+            # unrelated error when returning to the interactive prompt.
+            if group == "status" and not json_output and exc.exit_code == 1:
+                return
+            raise cli.CLIError("Invalid command arguments. Type 'help'.") from None
+        except (click.ClickException, click.Abort):
+            # Click errors can quote user-provided arguments; don't echo them.
+            raise cli.CLIError("Invalid command arguments. Type 'help'.") from None
+        if args[:2] == ["projects", "use"]:
+            self.project = _project_uuid(args[2])
+            self.session.project = self.project
+
+    def execute_line(self, line: str) -> bool:
+        """Run one input line. False means exit; all other outcomes continue."""
+        line = line.strip()
+        if not line:
+            return True
+        try:
+            parts = shlex.split(line, posix=True)
+            if not parts:
+                return True
+            command = parts[0].lower()
+            if command in {"exit", "quit"} and len(parts) == 1:
+                return False
+            if command in {"help", "?"} and len(parts) == 1:
+                self._show_help()
+            elif command == "clear" and len(parts) == 1:
+                self.session.console.clear()
+            elif command == "history" and len(parts) == 1:
+                self._history()
+            elif command == "back" and len(parts) == 1:
+                self.project = None
+                self.session.project = None
+                self._write("[dim]Project context cleared. Run 'use UUID' to select one.[/dim]")
+            elif command == "set" and len(parts) == 3 and parts[1].lower() == "env":
+                self._set_environment(parts[2].lower())
+            elif command == "set" and len(parts) == 3 and parts[1].lower() == "project":
+                self._execute_cli(["projects", "use", parts[2]])
+            elif command == "use" and len(parts) == 2:
+                self._execute_cli(["projects", "use", parts[1]])
+            elif command == "auth" and len(parts) == 2 and parts[1] == "login":
+                self._login()
+            elif command == "auth" and len(parts) == 2 and parts[1] == "logout":
+                self._logout()
+            elif command == "show" and len(parts) == 2:
+                target = SHOW_TARGETS.get(parts[1].lower(), ())
+                if target is None:
+                    self._show_options()
+                elif target:
+                    self._execute_cli(list(target))
+                else:
+                    raise cli.CLIError("Unknown display target. Type 'help'.")
+            elif command == "json" and len(parts) > 1:
+                self._execute_cli(parts[1:], json_output=True)
+            else:
+                self._execute_cli(parts)
+        except ValueError:
+            self._error("Invalid command syntax. Type 'help'.")
+        except cli.CLIError as exc:
+            self._error(str(exc))
+        except (click.ClickException, click.Abort, click.exceptions.Exit):
+            self._error("Invalid command arguments. Type 'help'.")
+        return True
+
+    def run(self) -> None:
+        self._write(
+            "\n[bold cyan]HOOKSTRIDE[/bold cyan] [dim]CONSOLE v0.2[/dim]\n"
+            "[dim]Type 'help' for commands, 'auth login' for a token, "
+            "or 'exit' to quit.[/dim]\n"
+        )
+        terminal = PromptSession(
+            history=self.history,
+            completer=self.completer,
+            complete_while_typing=False,
+        )
+        try:
+            while True:
+                tag = self.environment
+                if self.project:
+                    tag += ":" + self.project[:8]
+                prompt = FormattedText(
+                    [("ansicyan bold", "hookstride"),
+                     ("", " ["), ("ansigreen", tag), ("", "] > ")]
+                )
+                try:
+                    line = terminal.prompt(prompt)
+                except KeyboardInterrupt:
+                    self._write("[dim]Interrupted; type 'exit' to quit.[/dim]")
+                    continue
+                except EOFError:
+                    break
+                if not self.execute_line(line):
+                    break
+        finally:
+            self.tokens.clear()
+            self.logged_out.clear()
+            self._write("[dim]Console closed.[/dim]")
+
+
+class _FakeContext:
+    def __init__(self, obj: cli.Session) -> None:
+        self.obj = obj
+
+
+def _env_hint(token: str | None) -> str:
+    return "token configured" if token else "run 'auth login' to authenticate"
+
+
+def _allowed_cli(parts: list[str]) -> bool:
+    if not parts:
+        return False
+    if parts[0] in ROOT_COMMANDS:
+        return len(parts) == 1
+    return (
+        len(parts) >= 2
+        and parts[0] in READ_COMMANDS
+        and parts[1] in READ_COMMANDS[parts[0]]
+    )
+
+
+def _requires_project(group: str, action: str | None) -> bool:
+    return group in {
+        "destinations", "keys", "events", "billing", "incoming",
+    } or group == "stats"
+
+
+def _requires_token(group: str, action: str | None) -> bool:
+    return group != "status" and not (group == "config" and action == "show")
+
+
+def run_console(session: cli.Session) -> None:
+    if session.json_output:
+        raise cli.CLIError("Interactive console does not support --json; use 'json COMMAND' inside it.")
+    if not os.isatty(0):
+        raise cli.CLIError(
+            "Interactive console requires a terminal. Use direct Hookstride CLI commands in scripts."
+        )
+    HookstrideConsole(session).run()

hookstride_cli/main.py

@@ -0,0 +1,687 @@
+"""Hookstride CLI: developer-friendly, project-scoped Control API inspection.
+
+Read-only commands use control tokens. This module never persists a token.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import sys
+import tempfile
+import unicodedata
+import uuid
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+import typer
+from rich.cells import cell_len
+from rich.console import Console
+from rich.markup import escape
+from rich.panel import Panel
+from rich.text import Text
+
+VERSION = "0.2.0"
+ORIGINS = {
+    "dev": "https://api-dev.hookstride.voteeasy.net",
+    "production": "https://api.hookstride.voteeasy.net",
+}
+app = typer.Typer(
+    help="Hookstride · inspect your projects and webhook deliveries.",
+    add_completion=False,
+    no_args_is_help=False,
+    pretty_exceptions_show_locals=False,
+)
+auth_app = typer.Typer(help="Check Control API authentication.")
+projects_app = typer.Typer(help="List and select a workspace project.")
+destinations_app = typer.Typer(help="Inspect configured webhook destinations.")
+events_app = typer.Typer(help="Inspect delivery history and attempts.")
+billing_app = typer.Typer(help="Inspect project-isolated billing.")
+incoming_app = typer.Typer(help="Inspect incoming webhook sources.")
+keys_app = typer.Typer(help="Inspect masked project API keys.")
+config_app = typer.Typer(help="Inspect local CLI configuration.")
+app.add_typer(auth_app, name="auth")
+app.add_typer(projects_app, name="projects")
+app.add_typer(destinations_app, name="destinations")
+app.add_typer(events_app, name="events")
+app.add_typer(billing_app, name="billing")
+app.add_typer(incoming_app, name="incoming")
+app.add_typer(keys_app, name="keys")
+app.add_typer(config_app, name="config")
+
+
+class CLIError(Exception):
+    """An error safe to display without leaking credentials."""
+
+
+class Session:
+    def __init__(
+        self, environment: str, api_url: str | None, project: str | None,
+        json_output: bool, no_color: bool,
+    ) -> None:
+        if environment not in ORIGINS:
+            raise CLIError("Choose --env dev or --env production.")
+        self.environment = environment
+        self.origin = _origin(api_url or ORIGINS[environment])
+        self.project = _uuid(project) if project else None
+        self.json_output = json_output
+        self.console = Console(
+            stderr=False, no_color=no_color or json_output,
+            force_terminal=False if json_output else None,
+        )
+
+
+def _origin(value: str) -> str:
+    try:
+        parts = urlsplit(value)
+        # urlsplit accepts malformed ports unless the port property is accessed.
+        port = parts.port
+        hostname = parts.hostname
+    except ValueError:
+        raise CLIError("Invalid API origin. Specify a hostname and valid port.") from None
+    if (
+        not hostname or port == 0 or parts.username or parts.password
+        or parts.query or parts.fragment or parts.path not in ("", "/")
+    ):
+        raise CLIError("API URL must be an origin, without path, credentials or query.")
+    if parts.scheme != "https" and not (
+        parts.scheme == "http" and hostname in ("localhost", "127.0.0.1", "::1")
+    ):
+        raise CLIError("Use HTTPS for remote APIs; HTTP is allowed only on loopback.")
+    return value.rstrip("/")
+
+
+def _uuid(value: str) -> str:
+    try:
+        return str(uuid.UUID(value))
+    except (ValueError, AttributeError) as exc:
+        raise CLIError("Expected a valid project or event UUID.") from exc
+
+
+def _config_file() -> Path:
+    configured = os.environ.get("HOOKSTRIDE_CONFIG_FILE")
+    return Path(configured).expanduser() if configured else (
+        Path.home() / ".config" / "hookstride" / "settings.json"
+    )
+
+
+def _read_config() -> dict[str, Any]:
+    path = _config_file()
+    try:
+        if not path.exists():
+            return {}
+        parsed = json.loads(path.read_text(encoding="utf-8"))
+        return parsed if isinstance(parsed, dict) else {}
+    except (OSError, ValueError) as exc:
+        raise CLIError("Cannot read Hookstride CLI settings.") from exc
+
+
+def _save_project(env: str, project_id: str) -> None:
+    settings = _read_config()
+    profiles = settings.setdefault("projects", {})
+    if not isinstance(profiles, dict):
+        profiles = settings["projects"] = {}
+    profiles[env] = project_id
+    path = _config_file()
+    temporary = None
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        # Replace atomically: don't truncate a working config if interrupted.
+        # The temporary file is owner-only, and never contains auth tokens.
+        fd, temporary = tempfile.mkstemp(prefix=".settings-", dir=path.parent)
+        with os.fdopen(fd, "w", encoding="utf-8") as stream:
+            os.fchmod(stream.fileno(), 0o600)
+            json.dump(settings, stream, indent=2, sort_keys=True)
+            stream.write("\n")
+        os.replace(temporary, path)
+    except OSError as exc:
+        raise CLIError("Cannot save Hookstride CLI settings.") from exc
+    finally:
+        if temporary is not None:
+            with contextlib.suppress(FileNotFoundError):
+                os.unlink(temporary)
+
+
+def _session(ctx: typer.Context) -> Session:
+    return ctx.obj
+
+
+def _project(ctx: typer.Context) -> str:
+    session = _session(ctx)
+    if session.project:
+        return session.project
+    saved = _read_config().get("projects", {})
+    selected = saved.get(session.environment) if isinstance(saved, dict) else None
+    if not selected:
+        raise CLIError("Select a project with 'hookstride projects use UUID' or --project UUID.")
+    return _uuid(selected)
+
+
+def _token() -> str:
+    token = os.environ.get("HOOKSTRIDE_CONTROL_TOKEN", "").strip()
+    if not token.startswith("whrctl_"):
+        raise CLIError(
+            "Control token missing. Set HOOKSTRIDE_CONTROL_TOKEN to an MFA-verified "
+            "management token from the Hookstride dashboard."
+        )
+    return token
+
+
+def _request(
+    session: Session, path: str, *,
+    authenticate: bool = True, params: dict[str, Any] | None = None,
+) -> Any:
+    headers = {"Accept": "application/json"}
+    if authenticate:
+        headers["Authorization"] = "Bearer " + _token()
+    try:
+        with httpx.Client(
+            base_url=session.origin, headers=headers, timeout=15,
+            follow_redirects=False,
+        ) as client:
+            response = client.get(path, params=params)
+    except (httpx.HTTPError, httpx.InvalidURL, ValueError):
+        # Never print provider errors: transport exceptions may include headers.
+        raise CLIError("Unable to reach the Hookstride API. Check the URL and connection.") from None
+    if response.status_code == 401:
+        raise CLIError("Authentication rejected. Check that your control token is valid.")
+    if response.status_code == 403:
+        raise CLIError("Access denied for this account or project (HTTP 403).")
+    if response.status_code == 404:
+        raise CLIError("Resource not found or not enabled for this project (HTTP 404).")
+    if not 200 <= response.status_code < 300:
+        raise CLIError(f"API request failed (HTTP {response.status_code}).")
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise CLIError("API returned a non-JSON response.") from exc
+
+
+def _print(ctx: typer.Context, data: Any) -> None:
+    session = _session(ctx)
+    if session.json_output:
+        # ASCII escapes prevent C1/bidi controls from reaching the terminal
+        # while retaining all original JSON values for scripts.
+        typer.echo(json.dumps(data, indent=2, ensure_ascii=True))
+    else:
+        session.console.print_json(data=data)
+
+
+def _safe_terminal_text(value: Any) -> str:
+    """Display untrusted values without executable terminal or bidi controls.
+
+    Rich escaping handles markup, but not ESC/C1/OSC/CSI control sequences.
+    Make control/format characters visible as literal Unicode escapes before
+    any response field reaches a console renderer. Keep API/JSON values intact.
+    """
+    safe = []
+    for char in str(value):
+        number = ord(char)
+        if unicodedata.category(char) in {"Cc", "Cf", "Cs", "Zl", "Zp"}:
+            if number <= 0xFF:
+                safe.append(f"\\x{number:02x}")
+            elif number <= 0xFFFF:
+                safe.append(f"\\u{number:04x}")
+            else:
+                safe.append(f"\\U{number:08x}")
+        else:
+            safe.append(char)
+    return "".join(safe)
+
+
+def _plain(value: Any) -> Text:
+    return Text("—" if value is None or value == "" else _safe_terminal_text(value))
+
+
+def _escaped(value: Any) -> str:
+    """Render API-controlled values literally inside Rich markup templates."""
+    return escape(str(_plain(value)))
+
+
+def _colored_status(value: Any) -> Text:
+    label = _safe_terminal_text(value or "unknown")
+    style = {
+        "active": "green", "delivered": "green", "succeeded": "green",
+        "success": "green", "failed": "red", "revoked": "red",
+        "abandoned": "yellow", "pending": "yellow", "delivering": "cyan",
+    }.get(label.lower(), "white")
+    return Text(label.upper(), style=style)
+
+
+def _table(
+    ctx: typer.Context, title: str, columns: list[str],
+    rows: list[list[Any]], *, status_column: int | None = None,
+) -> None:
+    """Render Metasploit-style columns without borders or wrapped identifiers."""
+    session = _session(ctx)
+    if not rows:
+        session.console.print(f"[dim]No {title.lower()} found.[/dim]")
+        return
+
+    styled_rows = [
+        [
+            _colored_status(value) if i == status_column else _plain(value)
+            for i, value in enumerate(values)
+        ]
+        for values in rows
+    ]
+    widths = [
+        max(cell_len(header), *(row[i].cell_len for row in styled_rows))
+        for i, header in enumerate(columns)
+    ]
+    gap = 2
+    available = max(20, session.console.width - 1)
+
+    # Keep names, dates, plans and statuses readable. On narrow terminals,
+    # trim identifiers/references first instead of wrapping them across lines.
+    priority = [
+        100 if ("id" in header.lower() or "reference" in header.lower())
+        else 50 if header.lower() in {"url", "error"}
+        else 0
+        for header in columns
+    ]
+    minimums = [
+        min(width, 8 if priority[i] == 100 else 4)
+        for i, width in enumerate(widths)
+    ]
+    while sum(widths) + gap * (len(widths) - 1) > available:
+        candidates = [
+            i for i in range(len(widths)) if widths[i] > minimums[i]
+        ]
+        if not candidates:
+            break
+        index = max(candidates, key=lambda i: (priority[i], widths[i] - minimums[i]))
+        widths[index] -= 1
+
+    session.console.print(title, highlight=False)
+    session.console.print("=" * cell_len(title), highlight=False)
+
+    def row_text(values: list[Text]) -> Text:
+        result = Text()
+        for i, value in enumerate(values):
+            if i:
+                result.append(" " * gap)
+            rendered = value.copy()
+            rendered.truncate(widths[i], overflow="ellipsis")
+            result.append(rendered)
+            if i < len(values) - 1:
+                result.append(" " * max(0, widths[i] - rendered.cell_len))
+        return result
+
+    session.console.print(row_text([Text(col) for col in columns]), highlight=False)
+    session.console.print(row_text([Text("-" * size) for size in widths]), highlight=False)
+    for values in styled_rows:
+        session.console.print(row_text(values), highlight=False)
+
+
+def _date(value: Any) -> str:
+    return str(value or "—")[:19].replace("T", " ")
+
+
+def _entries(data: Any, label: str) -> list[dict[str, Any]]:
+    items = data.get("results") if isinstance(data, dict) else data
+    if not isinstance(items, list):
+        raise CLIError(f"Unexpected API response for {label}.")
+    return [entry for entry in items if isinstance(entry, dict)]
+
+
+def _print_or_table(
+    ctx: typer.Context, data: Any, title: str, columns: list[str],
+    rows: list[list[Any]], *, status_column: int | None = None,
+) -> None:
+    if _session(ctx).json_output:
+        _print(ctx, data)
+    else:
+        _table(ctx, title, columns, rows, status_column=status_column)
+
+
+@app.command("console")
+def console_entry(ctx: typer.Context) -> None:
+    """Start the interactive read-only Hookstride operator console."""
+    from .console import run_console
+
+    run_console(_session(ctx))
+
+
+@app.callback(invoke_without_command=True)
+def root(
+    ctx: typer.Context,
+    env: str = typer.Option("dev", "--env", help="dev or production."),
+    api_url: str | None = typer.Option(None, "--api-url", help="Override the API origin."),
+    project: str | None = typer.Option(None, "--project", help="Project UUID override."),
+    json_output: bool = typer.Option(False, "--json", help="Machine-readable JSON, no styling."),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable ANSI colors."),
+    version: bool = typer.Option(False, "--version", is_eager=True, help="Show CLI version."),
+) -> None:
+    if version:
+        typer.echo(f"hookstride {VERSION}")
+        raise typer.Exit()
+    try:
+        ctx.obj = Session(env, api_url, project, json_output, no_color)
+    except CLIError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(2) from exc
+    if ctx.invoked_subcommand is None:
+        _session(ctx).console.print(
+            Panel.fit(
+                "[bold cyan]HOOKSTRIDE[/bold cyan]  [dim]CLI[/dim]\n"
+                "[green]●[/green] Webhook delivery, from your terminal\n\n"
+                "Start with [bold]hookstride auth status[/bold] or "
+                "[bold]hookstride projects list[/bold].\n"
+                "Run [bold]hookstride --help[/bold] for all commands.",
+                border_style="cyan",
+            )
+        )
+
+
+@app.command("status")
+def status(ctx: typer.Context) -> None:
+    """Check whether Hookstride is online."""
+    session = _session(ctx)
+    try:
+        checks = {
+            label: _request(session, f"/{label}/", authenticate=False)
+            for label in ("health", "ready")
+        }
+        health = checks["health"]
+        readiness = checks["ready"]
+        online = (
+            isinstance(health, dict)
+            and health.get("status") in {"ok", "healthy"}
+            and isinstance(readiness, dict)
+            and readiness.get("status") == "ready"
+            and (
+                not isinstance(readiness.get("checks"), dict)
+                or all(value is True for value in readiness["checks"].values())
+            )
+        )
+    except CLIError:
+        if session.json_output:
+            raise
+        online = False
+    if session.json_output:
+        _print(ctx, checks)
+        if not online:
+            raise typer.Exit(code=1)
+        return
+    color = "green" if online else "red"
+    label = "Online" if online else "Offline"
+    session.console.print(
+        Panel.fit(f"[{color}]● {label}[/{color}]", title="Hookstride", border_style=color)
+    )
+    if not online:
+        raise typer.Exit(code=1)
+
+
+@auth_app.command("status")
+def auth_status(ctx: typer.Context) -> None:
+    """Verify your Control API token without printing it."""
+    data = _request(_session(ctx), "/control/v1/me/")
+    if _session(ctx).json_output:
+        # Authentication status never needs to dump membership/user PII.
+        _print(ctx, {"authenticated": True, "email": data.get("user", {}).get("email")})
+        return
+    user = data.get("user", {})
+    _session(ctx).console.print(Panel.fit(
+        f"[green]✓ Authenticated[/green]\n"
+        f"Account: {_escaped(user.get('email'))}\n"
+        f"Workspace memberships: {len(data.get('memberships', []))}",
+        title="Control API", border_style="green",
+    ))
+
+
+@projects_app.command("list")
+def projects_list(ctx: typer.Context) -> None:
+    """List projects accessible to the signed-in account."""
+    data = _request(_session(ctx), "/control/v1/projects/")
+    items = _entries(data, "projects")
+    _print_or_table(
+        ctx, data, "Projects", ["Name", "Workspace", "Role", "Plan", "Project ID"],
+        [[p.get("name"), p.get("account_name"), p.get("role"),
+          (p.get("subscription") or {}).get("plan_code"), p.get("id")]
+         for p in items],
+    )
+
+
+@projects_app.command("use")
+def projects_use(ctx: typer.Context, project_id: str = typer.Argument(..., help="Project UUID.")) -> None:
+    """Choose a default project for this environment (only saves its UUID)."""
+    session = _session(ctx)
+    project_id = _uuid(project_id)
+    data = _request(session, f"/control/v1/projects/{project_id}/")
+    _save_project(session.environment, project_id)
+    if session.json_output:
+        _print(ctx, {"selected_project": project_id, "name": data.get("name")})
+    else:
+        session.console.print(
+            f"[green]✓[/green] Using [bold]{_escaped(data.get('name'))}[/bold] "
+            f"({project_id}) in {session.environment}."
+        )
+
+
+@destinations_app.command("list")
+def destinations_list(ctx: typer.Context, page: int = typer.Option(1, min=1)) -> None:
+    """List the selected project's outgoing destinations."""
+    project = _project(ctx)
+    data = _request(_session(ctx), f"/control/v1/projects/{project}/destinations/", params={"page": page})
+    items = _entries(data, "destinations")
+    _print_or_table(
+        ctx, data, "Destinations", ["Name", "URL", "Active", "Destination ID"],
+        [[x.get("name"), x.get("url"), "yes" if x.get("is_active") else "no", x.get("id")]
+         for x in items],
+    )
+
+
+@keys_app.command("list")
+def keys_list(ctx: typer.Context) -> None:
+    """List API key metadata; the server never returns the raw secret."""
+    project = _project(ctx)
+    data = _request(_session(ctx), f"/control/v1/projects/{project}/api-keys/")
+    items = _entries(data, "API keys")
+    _print_or_table(
+        ctx, data, "API keys",
+        ["Name", "Masked key", "Enabled", "Expires", "Key ID"],
+        [[key.get("name"), key.get("masked_key"),
+          "yes" if key.get("is_active") else "no",
+          _date(key.get("expires_at")), key.get("id")]
+         for key in items],
+    )
+
+
+@events_app.command("list")
+def events_list(
+    ctx: typer.Context,
+    page: int = typer.Option(1, min=1),
+    status_filter: str | None = typer.Option(None, "--status", help="delivered, failed, pending..."),
+    origin: str | None = typer.Option(None, "--origin", help="api, incoming or replay."),
+    search: str | None = typer.Option(None, "--search", help="Event ID, type or destination."),
+) -> None:
+    """List recent delivery activity with optional filters."""
+    project = _project(ctx)
+    params: dict[str, Any] = {"page": page}
+    if status_filter:
+        params["status"] = status_filter
+    if origin:
+        params["origin"] = origin
+    if search:
+        params["q"] = search
+    data = _request(_session(ctx), f"/control/v1/projects/{project}/events/", params=params)
+    items = _entries(data, "events")
+    _print_or_table(
+        ctx, data, "Activity", ["Created", "Event", "Destination", "Status", "Attempts", "Event ID"],
+        [[_date(x.get("created_at")), x.get("event_type"), x.get("destination_name"),
+          x.get("status"), x.get("attempt_count"), x.get("id")] for x in items],
+        status_column=3,
+    )
+
+
+@events_app.command("show")
+def events_show(ctx: typer.Context, event_id: str = typer.Argument(...)) -> None:
+    """Inspect an event and its delivery attempts (redacted by the API)."""
+    project = _project(ctx)
+    data = _request(_session(ctx), f"/control/v1/projects/{project}/events/{_uuid(event_id)}/")
+    if _session(ctx).json_output:
+        _print(ctx, data)
+        return
+    session = _session(ctx)
+    session.console.print(Panel.fit(
+        f"[bold]{_escaped(data.get('event_type'))}[/bold]\n"
+        f"Status: {_escaped(str(_colored_status(data.get('status'))))}\n"
+        f"Destination: {_escaped(data.get('destination_name'))}\n"
+        f"Event ID: {_escaped(data.get('id'))}",
+        title="Delivery", border_style="cyan",
+    ))
+    _table(
+        ctx, "Delivery attempts", ["Attempt", "HTTP", "Duration (ms)", "Time", "Error"],
+        [[x.get("attempt_number"), x.get("status_code"), x.get("duration_ms"),
+          _date(x.get("created_at")), x.get("error")] for x in data.get("attempts", [])],
+    )
+
+
+@billing_app.command("status")
+def billing_status(ctx: typer.Context) -> None:
+    """Show the selected project's plan and Flex credit balance."""
+    project = _project(ctx)
+    data = _request(_session(ctx), f"/control/v1/projects/{project}/billing/")
+    if _session(ctx).json_output:
+        _print(ctx, data)
+        return
+    plan = data.get("subscription") or {}
+    _session(ctx).console.print(Panel.fit(
+        f"Plan: [bold]{_escaped(plan.get('plan_code'))}[/bold]\n"
+        f"Status: {_escaped(str(_colored_status(plan.get('status'))))}\n"
+        f"Flex credits: {_escaped(plan.get('flex_credits'))}\n"
+        f"Current period ends: {_escaped(_date(plan.get('current_period_end')))}\n"
+        f"Payment attempts: {len(data.get('records', []))}",
+        title="Project Billing", border_style="cyan",
+    ))
+
+
+@billing_app.command("history")
+def billing_history(ctx: typer.Context) -> None:
+    """Display per-project Paystack payment attempts and their statuses."""
+    project = _project(ctx)
+    data = _request(_session(ctx), f"/control/v1/projects/{project}/billing/")
+    records = data.get("records", [])
+    _print_or_table(
+        ctx, records, "Payment history",
+        ["Date", "Plan", "Amount", "Status", "Reference"],
+        [[_date(r.get("created_at")), r.get("plan_code"),
+          f"{r.get('currency', '')} {int(r.get('amount_minor', 0)) / 100:.2f}",
+          r.get("status"), r.get("reference")] for r in records],
+        status_column=3,
+    )
+
+
+@incoming_app.command("sources")
+def incoming_sources(ctx: typer.Context) -> None:
+    """List configured incoming sources, when ingress is enabled."""
+    project = _project(ctx)
+    data = _request(_session(ctx), f"/control/v1/projects/{project}/incoming/sources/")
+    items = data.get("sources", [])
+    _print_or_table(
+        ctx, data, "Incoming sources", ["Name", "Provider", "Routing", "Active", "Source ID"],
+        [[s.get("name"), s.get("provider"), s.get("routing"),
+          "yes" if s.get("is_active") else "no", s.get("id")] for s in items],
+    )
+
+
+@incoming_app.command("routes")
+def incoming_routes(ctx: typer.Context) -> None:
+    """List incoming event-routing rules for the selected project."""
+    project = _project(ctx)
+    data = _request(_session(ctx), f"/control/v1/projects/{project}/incoming/routes/")
+    routes = data.get("routes", [])
+    _print_or_table(
+        ctx, data, "Incoming routes",
+        ["Source", "Destination", "Pattern", "Active", "Route ID"],
+        [[route.get("source"), route.get("endpoint"),
+          route.get("event_pattern"), "yes" if route.get("is_active") else "no",
+          route.get("id")] for route in routes],
+    )
+
+
+@incoming_app.command("bindings")
+def incoming_bindings(ctx: typer.Context) -> None:
+    """List existing reference-to-destination bindings."""
+    project = _project(ctx)
+    data = _request(_session(ctx), f"/control/v1/projects/{project}/incoming/bindings/")
+    bindings = data.get("bindings", [])
+    _print_or_table(
+        ctx, data, "Incoming bindings",
+        ["Reference", "Source", "Destination", "Binding ID"],
+        [[item.get("reference"), item.get("source"),
+          item.get("endpoint"), item.get("id")] for item in bindings],
+    )
+
+
+@incoming_app.command("registration-keys")
+def incoming_registration_keys(ctx: typer.Context) -> None:
+    """List masked incoming registration keys (never raw credentials)."""
+    project = _project(ctx)
+    data = _request(
+        _session(ctx), f"/control/v1/projects/{project}/incoming/registration-keys/"
+    )
+    keys = data.get("keys", [])
+    _print_or_table(
+        ctx, data, "Registration keys",
+        ["Name", "Masked key", "Active", "Expiry", "Key ID"],
+        [[item.get("name"), item.get("masked_key"),
+          "yes" if item.get("is_active") else "no",
+          _date(item.get("expires_at")), item.get("id")] for item in keys],
+    )
+
+
+@app.command("stats")
+def delivery_stats(ctx: typer.Context) -> None:
+    """Show delivery success/failure totals for the selected project."""
+    project = _project(ctx)
+    data = _request(_session(ctx), f"/control/v1/projects/{project}/delivery-stats/")
+    if _session(ctx).json_output:
+        _print(ctx, data)
+        return
+    counts = data.get("events", {})
+    _table(
+        ctx, "Delivery overview", ["Total", "Delivered", "Failed", "Pending", "Success"],
+        [[counts.get("total"), counts.get("delivered"), counts.get("failed"),
+          counts.get("pending"), f"{counts.get('success_rate', 0)}%"]],
+    )
+
+
+@config_app.command("show")
+def config_show(ctx: typer.Context) -> None:
+    """Print the active API/profile settings, never the token value."""
+    session = _session(ctx)
+    saved = _read_config().get("projects", {})
+    selected = session.project or (saved.get(session.environment) if isinstance(saved, dict) else None)
+    data = {
+        "environment": session.environment,
+        "api_url": session.origin,
+        "project": selected,
+        "token_configured": bool(os.environ.get("HOOKSTRIDE_CONTROL_TOKEN", "").startswith("whrctl_")),
+        "token_source": "environment" if os.environ.get("HOOKSTRIDE_CONTROL_TOKEN", "").startswith("whrctl_") else None,
+    }
+    if session.json_output:
+        _print(ctx, data)
+    else:
+        _table(ctx, "Configuration", ["Setting", "Value"], [[k, v] for k, v in data.items()])
+
+
+def main() -> None:
+    try:
+        app()
+    except CLIError as exc:
+        # Error messages are intentionally generic. No auth tokens or response bodies.
+        is_json = "--json" in sys.argv[1:]
+        if is_json:
+            typer.echo(json.dumps({"error": str(exc)}), err=True)
+        else:
+            Console(stderr=True).print(f"[red]✗[/red] {exc}")
+        raise SystemExit(1) from exc
+
+
+if __name__ == "__main__":
+    main()

hookstride_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+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.

hookstride_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+hookstride_cli/__init__.py,sha256=QF0aMDPMekvBntMFgFH6tE4BkHN7vXuw45c6RMu4BOw,55
+hookstride_cli/console.py,sha256=uB4gqFlIwUaajYJ0Q_Mt4KOLImGEVbDFKBaDKJ2zgYU,18701
+hookstride_cli/main.py,sha256=ZS07efEzUQrfTBtvfKjct6YqHiUTRSDmhPhIccQU7_s,26191
+hookstride_cli-0.2.0.dist-info/METADATA,sha256=vC6z5xwcSjhr0loFni9yYJvvGo_rLqwurOssCG9h8Mg,7347
+hookstride_cli-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+hookstride_cli-0.2.0.dist-info/entry_points.txt,sha256=E9bqvnCFVO-lYULID8x-HTp0gYnfrYprB2R8n-DKy6Q,56
+hookstride_cli-0.2.0.dist-info/RECORD,,

hookstride_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hookstride_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hookstride = hookstride_cli.main:main