hookstride-cli 0.2.0__tar.gz → 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. hookstride_cli-0.2.1/PKG-INFO +131 -0
  2. hookstride_cli-0.2.1/README.md +118 -0
  3. {hookstride_cli-0.2.0 → hookstride_cli-0.2.1}/pyproject.toml +2 -2
  4. {hookstride_cli-0.2.0 → hookstride_cli-0.2.1}/src/hookstride_cli/__init__.py +1 -1
  5. {hookstride_cli-0.2.0 → hookstride_cli-0.2.1}/src/hookstride_cli/main.py +1 -1
  6. {hookstride_cli-0.2.0 → hookstride_cli-0.2.1}/uv.lock +1 -1
  7. hookstride_cli-0.2.0/PKG-INFO +0 -179
  8. hookstride_cli-0.2.0/README.md +0 -166
  9. {hookstride_cli-0.2.0 → hookstride_cli-0.2.1}/.gitignore +0 -0
  10. {hookstride_cli-0.2.0 → hookstride_cli-0.2.1}/scripts/check.sh +0 -0
  11. {hookstride_cli-0.2.0 → hookstride_cli-0.2.1}/src/hookstride_cli/console.py +0 -0
  12. {hookstride_cli-0.2.0 → hookstride_cli-0.2.1}/tests/test_cli.py +0 -0
  13. {hookstride_cli-0.2.0 → hookstride_cli-0.2.1}/tests/test_console.py +0 -0
hookstride_cli-0.2.1/PKG-INFO ADDED
@@ -0,0 +1,131 @@
1
+ Metadata-Version: 2.5
2
+ Name: hookstride-cli
3
+ Version: 0.2.1
4
+ Summary: Command-line access to Hookstride projects, webhook activity, and billing.
5
+ License: Proprietary
6
+ Requires-Python: >=3.11
7
+ Requires-Dist: click<9,>=8.1
8
+ Requires-Dist: httpx<1,>=0.28
9
+ Requires-Dist: prompt-toolkit<4,>=3.0.52
10
+ Requires-Dist: rich<15,>=14
11
+ Requires-Dist: typer<1,>=0.20
12
+ Description-Content-Type: text/markdown
13
+
14
+ # Hookstride CLI
15
+
16
+ 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.
17
+
18
+ The current release supports read operations only. It cannot create or modify destinations, replay deliveries, manage credentials, or initiate payments.
19
+
20
+ ## Installation
21
+
22
+ Requires Python 3.11 or later.
23
+
24
+ ```bash
25
+ uv tool install hookstride-cli
26
+ ```
27
+
28
+ Alternatively, use `pipx install hookstride-cli`.
29
+
30
+ ```bash
31
+ hookstride --version
32
+ hookstride status
33
+ hookstride console
34
+ ```
35
+
36
+ Upgrade an existing installation with `uv tool upgrade hookstride-cli`.
37
+
38
+ ## Authentication
39
+
40
+ Authenticated commands require a **Control API token** (`whrctl_`), available from your Hookstride dashboard. Project delivery API keys (`whrk_`) do not grant CLI access.
41
+
42
+ In an interactive console, run `auth login` and enter the token at the hidden prompt:
43
+
44
+ ```bash
45
+ hookstride console
46
+ ```
47
+
48
+ For one-off commands, set `HOOKSTRIDE_CONTROL_TOKEN` in your shell without entering it on the command line:
49
+
50
+ ```bash
51
+ read -rs "HOOKSTRIDE_CONTROL_TOKEN?Control token: "
52
+ echo
53
+ export HOOKSTRIDE_CONTROL_TOKEN
54
+ hookstride auth status
55
+ ```
56
+
57
+ 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`.
58
+
59
+ Tokens entered through `auth login` are retained only for the interactive console session. The CLI does not write tokens to its settings file.
60
+
61
+ ## Commands
62
+
63
+ ```bash
64
+ hookstride status
65
+ hookstride auth status
66
+ hookstride projects list
67
+ hookstride projects use PROJECT_UUID
68
+
69
+ hookstride destinations list
70
+ hookstride keys list
71
+ hookstride events list --status failed
72
+ hookstride events show EVENT_UUID
73
+ hookstride stats
74
+
75
+ hookstride incoming sources
76
+ hookstride incoming routes
77
+ hookstride incoming bindings
78
+ hookstride incoming registration-keys
79
+
80
+ hookstride billing status
81
+ hookstride billing history
82
+ hookstride config show
83
+ ```
84
+
85
+ Replace `PROJECT_UUID` and `EVENT_UUID` with identifiers from your account.
86
+
87
+ Commands that operate on a project use the selected project. You can override the selection for an individual command:
88
+
89
+ ```bash
90
+ hookstride --project PROJECT_UUID events list
91
+ ```
92
+
93
+ ### Interactive console
94
+
95
+ ```bash
96
+ hookstride console
97
+ ```
98
+
99
+ 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`.
100
+
101
+ ### JSON output
102
+
103
+ Use `--json` before a command to retrieve structured data for scripts:
104
+
105
+ ```bash
106
+ hookstride --json projects list
107
+ hookstride --project PROJECT_UUID --json events list --status failed
108
+ hookstride --env production --json billing history
109
+ ```
110
+
111
+ Errors go to standard error; unsuccessful requests return a nonzero exit code.
112
+
113
+ ## Environments and local settings
114
+
115
+ The CLI connects to the development API by default: `https://api-dev.hookstride.voteeasy.net`.
116
+
117
+ To access production, select it explicitly:
118
+
119
+ ```bash
120
+ hookstride --env production console
121
+ ```
122
+
123
+ 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`.
124
+
125
+ 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.
126
+
127
+ ## Documentation
128
+
129
+ Product documentation: https://hookstride.voteeasy.net/docs
130
+
131
+ Source: https://github.com/quarj0/webhook-reliability-api/tree/main/cli
hookstride_cli-0.2.1/README.md ADDED
@@ -0,0 +1,118 @@
1
+ # Hookstride CLI
2
+
3
+ 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.
4
+
5
+ The current release supports read operations only. It cannot create or modify destinations, replay deliveries, manage credentials, or initiate payments.
6
+
7
+ ## Installation
8
+
9
+ Requires Python 3.11 or later.
10
+
11
+ ```bash
12
+ uv tool install hookstride-cli
13
+ ```
14
+
15
+ Alternatively, use `pipx install hookstride-cli`.
16
+
17
+ ```bash
18
+ hookstride --version
19
+ hookstride status
20
+ hookstride console
21
+ ```
22
+
23
+ Upgrade an existing installation with `uv tool upgrade hookstride-cli`.
24
+
25
+ ## Authentication
26
+
27
+ Authenticated commands require a **Control API token** (`whrctl_`), available from your Hookstride dashboard. Project delivery API keys (`whrk_`) do not grant CLI access.
28
+
29
+ In an interactive console, run `auth login` and enter the token at the hidden prompt:
30
+
31
+ ```bash
32
+ hookstride console
33
+ ```
34
+
35
+ For one-off commands, set `HOOKSTRIDE_CONTROL_TOKEN` in your shell without entering it on the command line:
36
+
37
+ ```bash
38
+ read -rs "HOOKSTRIDE_CONTROL_TOKEN?Control token: "
39
+ echo
40
+ export HOOKSTRIDE_CONTROL_TOKEN
41
+ hookstride auth status
42
+ ```
43
+
44
+ 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`.
45
+
46
+ Tokens entered through `auth login` are retained only for the interactive console session. The CLI does not write tokens to its settings file.
47
+
48
+ ## Commands
49
+
50
+ ```bash
51
+ hookstride status
52
+ hookstride auth status
53
+ hookstride projects list
54
+ hookstride projects use PROJECT_UUID
55
+
56
+ hookstride destinations list
57
+ hookstride keys list
58
+ hookstride events list --status failed
59
+ hookstride events show EVENT_UUID
60
+ hookstride stats
61
+
62
+ hookstride incoming sources
63
+ hookstride incoming routes
64
+ hookstride incoming bindings
65
+ hookstride incoming registration-keys
66
+
67
+ hookstride billing status
68
+ hookstride billing history
69
+ hookstride config show
70
+ ```
71
+
72
+ Replace `PROJECT_UUID` and `EVENT_UUID` with identifiers from your account.
73
+
74
+ Commands that operate on a project use the selected project. You can override the selection for an individual command:
75
+
76
+ ```bash
77
+ hookstride --project PROJECT_UUID events list
78
+ ```
79
+
80
+ ### Interactive console
81
+
82
+ ```bash
83
+ hookstride console
84
+ ```
85
+
86
+ 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`.
87
+
88
+ ### JSON output
89
+
90
+ Use `--json` before a command to retrieve structured data for scripts:
91
+
92
+ ```bash
93
+ hookstride --json projects list
94
+ hookstride --project PROJECT_UUID --json events list --status failed
95
+ hookstride --env production --json billing history
96
+ ```
97
+
98
+ Errors go to standard error; unsuccessful requests return a nonzero exit code.
99
+
100
+ ## Environments and local settings
101
+
102
+ The CLI connects to the development API by default: `https://api-dev.hookstride.voteeasy.net`.
103
+
104
+ To access production, select it explicitly:
105
+
106
+ ```bash
107
+ hookstride --env production console
108
+ ```
109
+
110
+ 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`.
111
+
112
+ 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.
113
+
114
+ ## Documentation
115
+
116
+ Product documentation: https://hookstride.voteeasy.net/docs
117
+
118
+ Source: https://github.com/quarj0/webhook-reliability-api/tree/main/cli
{hookstride_cli-0.2.0 → hookstride_cli-0.2.1}/pyproject.toml RENAMED
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "hookstride-cli"
7
- version = "0.2.0"
8
- description = "Readable, project-scoped Hookstride Control API terminal client."
7
+ version = "0.2.1"
8
+ description = "Command-line access to Hookstride projects, webhook activity, and billing."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
11
11
  license = { text = "Proprietary" }
{hookstride_cli-0.2.0 → hookstride_cli-0.2.1}/src/hookstride_cli/__init__.py RENAMED
@@ -1,3 +1,3 @@
1
1
  """Hookstride developer CLI."""
2
2
 
3
- __version__ = "0.2.0"
3
+ __version__ = "0.2.1"
{hookstride_cli-0.2.0 → hookstride_cli-0.2.1}/src/hookstride_cli/main.py RENAMED
@@ -24,7 +24,7 @@ from rich.markup import escape
24
24
  from rich.panel import Panel
25
25
  from rich.text import Text
26
26
 
27
- VERSION = "0.2.0"
27
+ VERSION = "0.2.1"
28
28
  ORIGINS = {
29
29
  "dev": "https://api-dev.hookstride.voteeasy.net",
30
30
  "production": "https://api.hookstride.voteeasy.net",
{hookstride_cli-0.2.0 → hookstride_cli-0.2.1}/uv.lock RENAMED
@@ -62,7 +62,7 @@ wheels = [
62
62
 
63
63
  [[package]]
64
64
  name = "hookstride-cli"
65
- version = "0.2.0"
65
+ version = "0.2.1"
66
66
  source = { editable = "." }
67
67
  dependencies = [
68
68
  { name = "click" },
hookstride_cli-0.2.0/PKG-INFO DELETED
@@ -1,179 +0,0 @@
1
- Metadata-Version: 2.5
2
- Name: hookstride-cli
3
- Version: 0.2.0
4
- Summary: Readable, project-scoped Hookstride Control API terminal client.
5
- License: Proprietary
6
- Requires-Python: >=3.11
7
- Requires-Dist: click<9,>=8.1
8
- Requires-Dist: httpx<1,>=0.28
9
- Requires-Dist: prompt-toolkit<4,>=3.0.52
10
- Requires-Dist: rich<15,>=14
11
- Requires-Dist: typer<1,>=0.20
12
- Description-Content-Type: text/markdown
13
-
14
- # Hookstride CLI
15
-
16
- 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.
17
-
18
- ## Install
19
-
20
- Once the first package release is available on PyPI, install with:
21
-
22
- ```bash
23
- uv tool install hookstride-cli
24
- hookstride --version
25
- hookstride console
26
- ```
27
-
28
- Alternative: `pipx install hookstride-cli`. Update with `uv tool upgrade hookstride-cli`.
29
- Requires Python 3.11 or newer. No checkout or Django backend installation is needed.
30
-
31
- ## Authentication
32
-
33
- 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.
34
-
35
- 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:
36
-
37
- ```bash
38
- printf "Control token: "
39
- read -rs HOOKSTRIDE_CONTROL_TOKEN
40
- printf "\\n"
41
- export HOOKSTRIDE_CONTROL_TOKEN
42
-
43
- hookstride auth status
44
- ```
45
-
46
- 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.
47
-
48
- ## Explore development
49
-
50
- ```bash
51
- hookstride status
52
- hookstride auth status
53
- hookstride projects list
54
- hookstride projects use 00000000-0000-0000-0000-000000000000
55
-
56
- hookstride destinations list
57
- hookstride keys list
58
- hookstride incoming sources
59
- hookstride incoming routes
60
- hookstride incoming bindings
61
- hookstride incoming registration-keys
62
- hookstride events list --status failed
63
- hookstride events show 00000000-0000-0000-0000-000000000000
64
- hookstride stats
65
- hookstride billing status
66
- hookstride billing history
67
- hookstride config show
68
- ```
69
-
70
- Replace the sample UUIDs with your own project/event IDs.
71
-
72
- 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.
73
-
74
- **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`.
75
-
76
- ## Development checks
77
-
78
- When the GitHub Actions runner is unavailable, run the **same** CLI tests locally
79
- without sending anything to the live Hookstride API:
80
-
81
- ```bash
82
- bash cli/scripts/check.sh
83
- ```
84
-
85
- This checks Python syntax, Ruff, isolated unit tests using mocked HTTP responses,
86
- and basic commands. A successful local run is not a substitute for a live
87
- read-only smoke test against the deployed development API.
88
-
89
- Tables use compact, borderless columns. Identifiers and long URLs are shortened
90
- only when necessary to fit the terminal; the actual API response is not changed.
91
- Use `--json` to copy complete project IDs, payment references and destination URLs.
92
-
93
- ## Interactive operator console (v0.2)
94
-
95
- Start a lightweight, Metasploit-inspired, **read-only** interactive console:
96
-
97
- ```bash
98
- hookstride console
99
- ```
100
-
101
- The shell starts on the **development API** by default. Enter `help` for
102
- available commands, use Tab for completion, Ctrl+C to cancel the current line,
103
- and Ctrl+D or `exit` to close the console.
104
-
105
- ```text
106
- HOOKSTRIDE CONSOLE v0.2
107
- hookstride [dev] > auth login
108
- Control token (hidden):
109
- ✓ Authenticated as developer@example.com
110
- hookstride [dev] > show projects
111
- Projects
112
- ========
113
- Name Workspace Role Plan Project ID
114
- ---------- ------------ ----- ------ ------------------------------------
115
- Production Beta Testing owner flex ddc21845-d0f1-49af-8d35-2719dc641f69
116
-
117
- hookstride [dev] > use ddc21845-d0f1-49af-8d35-2719dc641f69
118
- hookstride [dev:ddc21845] > show payments
119
- hookstride [dev:ddc21845] > events list --status failed
120
- hookstride [dev:ddc21845] > show destinations
121
- hookstride [dev:ddc21845] > json events list
122
- hookstride [dev:ddc21845] > back
123
- hookstride [dev] > exit
124
- ```
125
-
126
- This console accepts the existing read-only CLI commands, plus convenient
127
- `show` aliases, `set env dev|production`, `use UUID`,
128
- `back`, `clear`, `history`, and `auth login|logout`.
129
- `projects use UUID` and `use UUID` persist only the active project's UUID
130
- in local settings. The console does not support a shell escape, external
131
- processes, POST/DELETE operations, or purchases.
132
-
133
- ### Token handling
134
-
135
- `auth login` securely prompts for a Control API token via hidden input. Tokens
136
- are kept **in memory for this console process only**, are discarded at exit,
137
- are never written to a config or history file, and are never echoed. The
138
- console stores only a **safe subset** of commands in volatile arrow-key history;
139
- it never records tokens or arbitrary query/search strings.
140
-
141
- You may also provide an existing token through environment variables:
142
-
143
- ```bash
144
- # Use a development token with the default development console
145
- export HOOKSTRIDE_DEV_CONTROL_TOKEN="…" # do not put real secrets in shell history
146
- hookstride console
147
-
148
- # To start directly against production, explicitly select it
149
- hookstride --env production console
150
- ```
151
-
152
- For safest handling, prefer `auth login` over typing tokens in shell commands.
153
- For interactive environment changes, the generic legacy
154
- `HOOKSTRIDE_CONTROL_TOKEN` is **never forwarded to another environment**.
155
- Use `auth login` separately after `set env production`, or provide a
156
- matching `HOOKSTRIDE_PRODUCTION_CONTROL_TOKEN` token. This prevents a dev
157
- token from accidentally being sent to the production API.
158
-
159
- The console requires a real interactive terminal and refuses `--json console`.
160
- For CI and scripting, use ordinary commands such as
161
- `hookstride --json events list` instead.
162
-
163
- ## Output for scripts
164
-
165
- Pass `--json` **before** the command:
166
-
167
- ```bash
168
- hookstride --json projects list | jq .
169
- hookstride --json events list --status failed | jq '.results'
170
- hookstride --env production --json billing history
171
- ```
172
-
173
- The raw structured response is printed to stdout without terminal formatting. Network and HTTP errors go to stderr and cause a nonzero exit status.
174
-
175
- ## Scope
176
-
177
- 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.
178
-
179
- Do not store passwords, signing secrets, private keys, or Paystack keys in Hookstride CLI configuration.
hookstride_cli-0.2.0/README.md DELETED
@@ -1,166 +0,0 @@
1
- # Hookstride CLI
2
-
3
- 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.
4
-
5
- ## Install
6
-
7
- Once the first package release is available on PyPI, install with:
8
-
9
- ```bash
10
- uv tool install hookstride-cli
11
- hookstride --version
12
- hookstride console
13
- ```
14
-
15
- Alternative: `pipx install hookstride-cli`. Update with `uv tool upgrade hookstride-cli`.
16
- Requires Python 3.11 or newer. No checkout or Django backend installation is needed.
17
-
18
- ## Authentication
19
-
20
- 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.
21
-
22
- 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:
23
-
24
- ```bash
25
- printf "Control token: "
26
- read -rs HOOKSTRIDE_CONTROL_TOKEN
27
- printf "\\n"
28
- export HOOKSTRIDE_CONTROL_TOKEN
29
-
30
- hookstride auth status
31
- ```
32
-
33
- 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.
34
-
35
- ## Explore development
36
-
37
- ```bash
38
- hookstride status
39
- hookstride auth status
40
- hookstride projects list
41
- hookstride projects use 00000000-0000-0000-0000-000000000000
42
-
43
- hookstride destinations list
44
- hookstride keys list
45
- hookstride incoming sources
46
- hookstride incoming routes
47
- hookstride incoming bindings
48
- hookstride incoming registration-keys
49
- hookstride events list --status failed
50
- hookstride events show 00000000-0000-0000-0000-000000000000
51
- hookstride stats
52
- hookstride billing status
53
- hookstride billing history
54
- hookstride config show
55
- ```
56
-
57
- Replace the sample UUIDs with your own project/event IDs.
58
-
59
- 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.
60
-
61
- **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`.
62
-
63
- ## Development checks
64
-
65
- When the GitHub Actions runner is unavailable, run the **same** CLI tests locally
66
- without sending anything to the live Hookstride API:
67
-
68
- ```bash
69
- bash cli/scripts/check.sh
70
- ```
71
-
72
- This checks Python syntax, Ruff, isolated unit tests using mocked HTTP responses,
73
- and basic commands. A successful local run is not a substitute for a live
74
- read-only smoke test against the deployed development API.
75
-
76
- Tables use compact, borderless columns. Identifiers and long URLs are shortened
77
- only when necessary to fit the terminal; the actual API response is not changed.
78
- Use `--json` to copy complete project IDs, payment references and destination URLs.
79
-
80
- ## Interactive operator console (v0.2)
81
-
82
- Start a lightweight, Metasploit-inspired, **read-only** interactive console:
83
-
84
- ```bash
85
- hookstride console
86
- ```
87
-
88
- The shell starts on the **development API** by default. Enter `help` for
89
- available commands, use Tab for completion, Ctrl+C to cancel the current line,
90
- and Ctrl+D or `exit` to close the console.
91
-
92
- ```text
93
- HOOKSTRIDE CONSOLE v0.2
94
- hookstride [dev] > auth login
95
- Control token (hidden):
96
- ✓ Authenticated as developer@example.com
97
- hookstride [dev] > show projects
98
- Projects
99
- ========
100
- Name Workspace Role Plan Project ID
101
- ---------- ------------ ----- ------ ------------------------------------
102
- Production Beta Testing owner flex ddc21845-d0f1-49af-8d35-2719dc641f69
103
-
104
- hookstride [dev] > use ddc21845-d0f1-49af-8d35-2719dc641f69
105
- hookstride [dev:ddc21845] > show payments
106
- hookstride [dev:ddc21845] > events list --status failed
107
- hookstride [dev:ddc21845] > show destinations
108
- hookstride [dev:ddc21845] > json events list
109
- hookstride [dev:ddc21845] > back
110
- hookstride [dev] > exit
111
- ```
112
-
113
- This console accepts the existing read-only CLI commands, plus convenient
114
- `show` aliases, `set env dev|production`, `use UUID`,
115
- `back`, `clear`, `history`, and `auth login|logout`.
116
- `projects use UUID` and `use UUID` persist only the active project's UUID
117
- in local settings. The console does not support a shell escape, external
118
- processes, POST/DELETE operations, or purchases.
119
-
120
- ### Token handling
121
-
122
- `auth login` securely prompts for a Control API token via hidden input. Tokens
123
- are kept **in memory for this console process only**, are discarded at exit,
124
- are never written to a config or history file, and are never echoed. The
125
- console stores only a **safe subset** of commands in volatile arrow-key history;
126
- it never records tokens or arbitrary query/search strings.
127
-
128
- You may also provide an existing token through environment variables:
129
-
130
- ```bash
131
- # Use a development token with the default development console
132
- export HOOKSTRIDE_DEV_CONTROL_TOKEN="…" # do not put real secrets in shell history
133
- hookstride console
134
-
135
- # To start directly against production, explicitly select it
136
- hookstride --env production console
137
- ```
138
-
139
- For safest handling, prefer `auth login` over typing tokens in shell commands.
140
- For interactive environment changes, the generic legacy
141
- `HOOKSTRIDE_CONTROL_TOKEN` is **never forwarded to another environment**.
142
- Use `auth login` separately after `set env production`, or provide a
143
- matching `HOOKSTRIDE_PRODUCTION_CONTROL_TOKEN` token. This prevents a dev
144
- token from accidentally being sent to the production API.
145
-
146
- The console requires a real interactive terminal and refuses `--json console`.
147
- For CI and scripting, use ordinary commands such as
148
- `hookstride --json events list` instead.
149
-
150
- ## Output for scripts
151
-
152
- Pass `--json` **before** the command:
153
-
154
- ```bash
155
- hookstride --json projects list | jq .
156
- hookstride --json events list --status failed | jq '.results'
157
- hookstride --env production --json billing history
158
- ```
159
-
160
- The raw structured response is printed to stdout without terminal formatting. Network and HTTP errors go to stderr and cause a nonzero exit status.
161
-
162
- ## Scope
163
-
164
- 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.
165
-
166
- Do not store passwords, signing secrets, private keys, or Paystack keys in Hookstride CLI configuration.