@beryl-so/cli 0.2.0 → 0.6.0

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 (21) hide show
  1. package/README.md +227 -149
  2. package/dist/adapters/cli.js +39 -11
  3. package/dist/adapters/mcp.js +6 -0
  4. package/dist/beryl-test-skill.js +136 -0
  5. package/dist/commands/account.js +3 -0
  6. package/dist/commands/auth.js +62 -7
  7. package/dist/commands/config-vars.js +1 -0
  8. package/dist/commands/credentials.js +35 -1
  9. package/dist/commands/environments.js +2 -0
  10. package/dist/commands/explorations.js +15 -0
  11. package/dist/commands/inboxes.js +117 -0
  12. package/dist/commands/init.js +93 -14
  13. package/dist/commands/projects.js +1 -0
  14. package/dist/commands/runs.js +104 -2
  15. package/dist/commands/slack.js +82 -0
  16. package/dist/commands/tests.js +23 -3
  17. package/dist/commands/workspaces.js +3 -0
  18. package/dist/local-run.js +168 -0
  19. package/dist/registry/index.js +7 -0
  20. package/dist/schema.generated.js +152 -1
  21. package/package.json +1 -1
package/README.md CHANGED
@@ -12,9 +12,10 @@ that exposes every command to coding agents.
12
12
  npx @beryl-so/cli@latest init
13
13
  ```
14
14
 
15
- Signs you in, pins this repo to a project (creating it if needed — the agent starts
16
- exploring and authoring tests immediately), and wires the MCP server into Claude Code
17
- or Cursor. Safe to re-run.
15
+ Signs you in, pins this repo to a project (creating it if needed — and asking whether
16
+ you want to author tests locally with your own coding agent, the default, or let Beryl's
17
+ agent explore and author them), and wires the MCP server into Claude Code or Cursor.
18
+ Safe to re-run.
18
19
 
19
20
  ## Install
20
21
 
@@ -58,223 +59,300 @@ Every non-interactive command below is exposed as an MCP tool with the same name
58
59
 
59
60
  ### init
60
61
 
61
- | Command | Summary |
62
- | --- | --- |
63
- | `beryl init` | Set up Beryl in this repo — sign in, pin a project, wire up your coding agent |
62
+ Set up Beryl in this repo — sign in, pin a project, wire up your coding agent
63
+
64
+ | Command | Summary | MCP tool |
65
+ | --- | --- | --- |
66
+ | `beryl init` | Set up Beryl in this repo — sign in, pin a project, wire up your coding agent | — |
64
67
 
65
68
  ### login
66
69
 
67
- | Command | Summary |
68
- | --- | --- |
69
- | `beryl login` | Authenticate the CLI with your Beryl account |
70
+ Authenticate the CLI with your Beryl account
71
+
72
+ | Command | Summary | MCP tool |
73
+ | --- | --- | --- |
74
+ | `beryl login` | Authenticate the CLI with your Beryl account | — |
75
+
76
+ ### signup
77
+
78
+ Register a new Beryl account (emails a 6-digit verification code)
79
+
80
+ | Command | Summary | MCP tool |
81
+ | --- | --- | --- |
82
+ | `beryl signup` | Register a new Beryl account (emails a 6-digit verification code) | `signup` |
70
83
 
71
84
  ### logout
72
85
 
73
- | Command | Summary |
74
- | --- | --- |
75
- | `beryl logout` | Remove the stored token from the CLI config |
86
+ Remove the stored token from the CLI config
87
+
88
+ | Command | Summary | MCP tool |
89
+ | --- | --- | --- |
90
+ | `beryl logout` | Remove the stored token from the CLI config | `logout` |
76
91
 
77
92
  ### whoami
78
93
 
79
- | Command | Summary |
80
- | --- | --- |
81
- | `beryl whoami` | Show the signed-in account and the CLI's resolved defaults |
94
+ Show the signed-in account and the CLI's resolved defaults
95
+
96
+ | Command | Summary | MCP tool |
97
+ | --- | --- | --- |
98
+ | `beryl whoami` | Show the signed-in account and the CLI's resolved defaults | `whoami` |
82
99
 
83
100
  ### tokens
84
101
 
85
- | Command | Summary |
86
- | --- | --- |
87
- | `beryl tokens list` | List your personal access tokens |
88
- | `beryl tokens create <name>` | Mint a new personal access token (shown once) |
89
- | `beryl tokens revoke <token-id>` | Revoke a personal access token |
102
+ Manage the personal access tokens that authenticate the CLI and CI.
103
+
104
+ | Command | Summary | MCP tool |
105
+ | --- | --- | --- |
106
+ | `beryl tokens list` | List your personal access tokens | `tokens_list` |
107
+ | `beryl tokens create <name>` | Mint a new personal access token (shown once) | `tokens_create` |
108
+ | `beryl tokens revoke <token-id>` | Revoke a personal access token | `tokens_revoke` |
90
109
 
91
110
  ### workspaces
92
111
 
93
- | Command | Summary |
94
- | --- | --- |
95
- | `beryl workspaces list` | List workspaces you belong to |
96
- | `beryl workspaces get` | Show one workspace |
97
- | `beryl workspaces create <name>` | Create a workspace |
98
- | `beryl workspaces update` | Rename a workspace or change its visibility |
99
- | `beryl workspaces delete` | Delete a workspace and everything in it |
100
- | `beryl workspaces use <workspace>` | Set the default workspace for future commands |
101
- | `beryl workspaces history` | Show the workspace's action history (who did what, when) |
102
- | `beryl workspaces leave` | Leave a workspace you are a member of |
112
+ Create and manage workspaces, and pick the one your commands act on by default.
113
+
114
+ | Command | Summary | MCP tool |
115
+ | --- | --- | --- |
116
+ | `beryl workspaces list` | List workspaces you belong to | `workspaces_list` |
117
+ | `beryl workspaces get` | Show one workspace | `workspaces_get` |
118
+ | `beryl workspaces create <name>` | Create a workspace | `workspaces_create` |
119
+ | `beryl workspaces update` | Rename a workspace or change its visibility | `workspaces_update` |
120
+ | `beryl workspaces delete` | Delete a workspace and everything in it | `workspaces_delete` |
121
+ | `beryl workspaces use <workspace>` | Set the default workspace for future commands | `workspaces_use` |
122
+ | `beryl workspaces history` | Show the workspace's action history (who did what, when) | `workspaces_history` |
123
+ | `beryl workspaces leave` | Leave a workspace you are a member of | `workspaces_leave` |
103
124
 
104
125
  ### members
105
126
 
106
- | Command | Summary |
107
- | --- | --- |
108
- | `beryl members list` | List workspace members |
109
- | `beryl members set-role <user-id> <role>` | Change a member's role |
110
- | `beryl members remove <user-id>` | Remove a member from the workspace |
127
+ Manage who belongs to a workspace and their roles.
128
+
129
+ | Command | Summary | MCP tool |
130
+ | --- | --- | --- |
131
+ | `beryl members list` | List workspace members | `members_list` |
132
+ | `beryl members set-role <user-id> <role>` | Change a member's role | `members_set_role` |
133
+ | `beryl members remove <user-id>` | Remove a member from the workspace | `members_remove` |
111
134
 
112
135
  ### invites
113
136
 
114
- | Command | Summary |
115
- | --- | --- |
116
- | `beryl invites send <email>` | Invite someone to the workspace by email |
117
- | `beryl invites list` | List the workspace's outstanding invitations |
118
- | `beryl invites revoke <invitation-id>` | Revoke a pending invitation |
119
- | `beryl invites mine` | List invitations sent to you |
120
- | `beryl invites accept <invitation>` | Accept an invitation (by id, or by the token from the invite email) |
121
- | `beryl invites decline <invitation-id>` | Decline an invitation |
137
+ Send, list, and revoke workspace invitations, and accept ones sent to you.
138
+
139
+ | Command | Summary | MCP tool |
140
+ | --- | --- | --- |
141
+ | `beryl invites send <email>` | Invite someone to the workspace by email | `invites_send` |
142
+ | `beryl invites list` | List the workspace's outstanding invitations | `invites_list` |
143
+ | `beryl invites revoke <invitation-id>` | Revoke a pending invitation | `invites_revoke` |
144
+ | `beryl invites mine` | List invitations sent to you | `invites_mine` |
145
+ | `beryl invites accept <invitation>` | Accept an invitation (by id, or by the token from the invite email) | `invites_accept` |
146
+ | `beryl invites decline <invitation-id>` | Decline an invitation | `invites_decline` |
122
147
 
123
148
  ### projects
124
149
 
150
+ Create and manage projects — a site Beryl explores, authors tests for, and runs.
151
+
125
152
  `beryl projects` with no subcommand runs `projects list`.
126
153
 
127
- | Command | Summary |
128
- | --- | --- |
129
- | `beryl projects list` | List projects in the workspace |
130
- | `beryl projects get` | Show one project, including its current exploration state |
131
- | `beryl projects create <url>` | Create a project — the agent starts exploring and authoring tests immediately |
132
- | `beryl projects rename <name>` | Rename a project |
133
- | `beryl projects delete` | Delete a project and all its tests and runs |
134
- | `beryl projects re-explore` | Send the agent back in — run/heal existing tests and discover new flows |
135
- | `beryl projects report` | Aggregate quality report across recent runs (pass rates, flaky tests, trend) |
136
- | `beryl projects reusable-auth <url>` | Check whether a saved login can be reused for a URL before creating a project |
137
- | `beryl projects use <project>` | Set the default project for future commands |
154
+ | Command | Summary | MCP tool |
155
+ | --- | --- | --- |
156
+ | `beryl projects list` | List projects in the workspace | `projects_list` |
157
+ | `beryl projects get` | Show one project, including its current exploration state | `projects_get` |
158
+ | `beryl projects create <url>` | Create a project — the agent starts exploring and authoring tests immediately | `projects_create` |
159
+ | `beryl projects rename <name>` | Rename a project | `projects_rename` |
160
+ | `beryl projects delete` | Delete a project and all its tests and runs | `projects_delete` |
161
+ | `beryl projects re-explore` | Send the agent back in — run/heal existing tests and discover new flows | `projects_re_explore` |
162
+ | `beryl projects report` | Aggregate quality report across recent runs (pass rates, flaky tests, trend) | `projects_report` |
163
+ | `beryl projects reusable-auth <url>` | Check whether a saved login can be reused for a URL before creating a project | `projects_reusable_auth` |
164
+ | `beryl projects use <project>` | Set the default project for future commands | `projects_use` |
138
165
 
139
166
  ### envs
140
167
 
141
- | Command | Summary |
142
- | --- | --- |
143
- | `beryl envs list` | List a project's environments |
144
- | `beryl envs get <env-id>` | Show one environment |
145
- | `beryl envs create <name> <url>` | Add an environment (e.g. staging) to a project |
146
- | `beryl envs update <env-id>` | Update an environment's name, URL, or auth settings |
147
- | `beryl envs delete <env-id>` | Delete an environment |
168
+ Manage a project's environments — the URLs and auth Beryl runs tests against.
169
+
170
+ | Command | Summary | MCP tool |
171
+ | --- | --- | --- |
172
+ | `beryl envs list` | List a project's environments | `envs_list` |
173
+ | `beryl envs get <env-id>` | Show one environment | `envs_get` |
174
+ | `beryl envs create <name> <url>` | Add an environment (e.g. staging) to a project | `envs_create` |
175
+ | `beryl envs update <env-id>` | Update an environment's name, URL, or auth settings | `envs_update` |
176
+ | `beryl envs delete <env-id>` | Delete an environment | `envs_delete` |
148
177
 
149
178
  ### schedule
150
179
 
151
- | Command | Summary |
152
- | --- | --- |
153
- | `beryl schedule get` | Show the project's daily/weekly run schedule |
154
- | `beryl schedule set` | Enable scheduled runs (daily, or weekly on a given day) |
155
- | `beryl schedule disable` | Turn scheduled runs off |
180
+ View and set the schedule on which Beryl runs a project's tests automatically.
181
+
182
+ | Command | Summary | MCP tool |
183
+ | --- | --- | --- |
184
+ | `beryl schedule get` | Show the project's daily/weekly run schedule | `schedule_get` |
185
+ | `beryl schedule set` | Enable scheduled runs (daily, or weekly on a given day) | `schedule_set` |
186
+ | `beryl schedule disable` | Turn scheduled runs off | `schedule_disable` |
156
187
 
157
188
  ### tests
158
189
 
190
+ Author, inspect, version, and heal a project's tests — the checks Beryl runs on each run.
191
+
159
192
  `beryl tests` with no subcommand runs `tests list`.
160
193
 
161
- | Command | Summary |
162
- | --- | --- |
163
- | `beryl tests lint` | Validate a plan JSON file offline, before sending it to the server |
164
- | `beryl tests list` | List the project's tests with their latest result |
165
- | `beryl tests get <test-id>` | Show one test |
166
- | `beryl tests plan <test-id>` | Print a test's current step plan (JSON) |
167
- | `beryl tests create` | Create a test case from a JSON action plan — for tests authored locally, e.g. by your coding agent |
168
- | `beryl tests set-plan <test-id>` | Replace a test's step plan from a JSON file (creates a new version) |
169
- | `beryl tests rename <test-id> <title>` | Rename a test |
170
- | `beryl tests quarantine <test-id> <state>` | Mute a flaky test: it keeps running, but its failures stop failing the run |
171
- | `beryl tests delete <test-id>` | Delete a test, its version history, and its results |
172
- | `beryl tests recompile <test-id>` | Validate + verify an edited plan against the live site before persisting |
173
- | `beryl tests versions <test-id>` | List a test's version history |
174
- | `beryl tests version <test-id> <version-no>` | Show one specific version of a test (including its plan) |
175
- | `beryl tests diff <test-id> <from> <to>` | Diff two versions of a test's plan |
176
- | `beryl tests restore <test-id> <version-no>` | Restore a test to an earlier version |
177
- | `beryl tests reset <test-id>` | Discard user edits and return the test to its latest system-authored version |
178
- | `beryl tests heal <test-id> <state>` | Turn self-healing on or off for a test |
179
- | `beryl tests history <test-id>` | Pass/fail history, streak, and stability for a test |
180
- | `beryl tests script <test-id>` | Print the rendered Playwright spec for a test |
181
- | `beryl tests export <test-ids...>` | Export tests as Playwright .spec.ts files in a ZIP |
194
+ | Command | Summary | MCP tool |
195
+ | --- | --- | --- |
196
+ | `beryl tests lint` | Validate a plan JSON file offline, before sending it to the server | `tests_lint` |
197
+ | `beryl tests list` | List the project's tests with their latest result | `tests_list` |
198
+ | `beryl tests get <test-id>` | Show one test | `tests_get` |
199
+ | `beryl tests plan <test-id>` | Print a test's current step plan (JSON) | `tests_plan` |
200
+ | `beryl tests create` | Create a test case from a JSON action plan — for tests authored locally, e.g. by your coding agent | `tests_create` |
201
+ | `beryl tests set-plan <test-id>` | Replace a test's step plan from a JSON file (creates a new version) | `tests_set_plan` |
202
+ | `beryl tests rename <test-id> <title>` | Rename a test | `tests_rename` |
203
+ | `beryl tests quarantine <test-id> <state>` | Mute a flaky test: it keeps running, but its failures stop failing the run | `tests_quarantine` |
204
+ | `beryl tests delete <test-id>` | Delete a test, its version history, and its results | `tests_delete` |
205
+ | `beryl tests recompile <test-id>` | Validate + verify an edited plan against the live site before persisting | `tests_recompile` |
206
+ | `beryl tests versions <test-id>` | List a test's version history | `tests_versions` |
207
+ | `beryl tests version <test-id> <version-no>` | Show one specific version of a test (including its plan) | `tests_version` |
208
+ | `beryl tests diff <test-id> <from> <to>` | Diff two versions of a test's plan | `tests_diff` |
209
+ | `beryl tests restore <test-id> <version-no>` | Restore a test to an earlier version | `tests_restore` |
210
+ | `beryl tests reset <test-id>` | Discard user edits and return the test to its latest system-authored version | `tests_reset` |
211
+ | `beryl tests heal <test-id> <state>` | Turn self-healing on or off for a test | `tests_heal` |
212
+ | `beryl tests history <test-id>` | Pass/fail history, streak, and stability for a test | `tests_history` |
213
+ | `beryl tests script <test-id>` | Print the rendered Playwright spec for a test | `tests_script` |
214
+ | `beryl tests export <test-ids...>` | Export tests as Playwright .spec.ts files in a ZIP | `tests_export` |
182
215
 
183
216
  ### runs
184
217
 
218
+ Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and download results.
219
+
185
220
  `beryl runs` with no subcommand runs `runs list`.
186
221
 
187
- | Command | Summary |
188
- | --- | --- |
189
- | `beryl runs trigger` | Trigger a test run (whole suite, a subset, or one environment) |
190
- | `beryl runs list` | List recent runs |
191
- | `beryl runs get <run-id>` | Show one run with its per-test results |
192
- | `beryl runs watch <run-id>` | Attach to a run and stream progress until it finishes |
193
- | `beryl runs cancel <run-id>` | Cancel an in-flight run |
194
- | `beryl runs report <run-id>` | Show the generated report for a run |
195
- | `beryl runs download <run-id>` | Download a run's results, with its artifacts, to disk |
196
- | `beryl runs explain <result-id>` | AI explanation of why a test result failed |
222
+ | Command | Summary | MCP tool |
223
+ | --- | --- | --- |
224
+ | `beryl runs trigger` | Trigger a test run (whole suite, a subset, or one environment) | `runs_trigger` |
225
+ | `beryl runs local <test-id>` | Run a banked test locally with your own Playwright (public flows) | `runs_local` |
226
+ | `beryl runs list` | List recent runs | `runs_list` |
227
+ | `beryl runs get <run-id>` | Show one run with its per-test results | `runs_get` |
228
+ | `beryl runs watch <run-id>` | Attach to a run and stream progress until it finishes | `runs_watch` |
229
+ | `beryl runs cancel <run-id>` | Cancel an in-flight run | `runs_cancel` |
230
+ | `beryl runs report <run-id>` | Show the generated report for a run | `runs_report` |
231
+ | `beryl runs download <run-id>` | Download a run's results, with its artifacts, to disk | `runs_download` |
232
+ | `beryl runs explain <result-id>` | Explain, with AI, why a test result failed | `runs_explain` |
197
233
 
198
234
  ### explorations
199
235
 
200
- | Command | Summary |
201
- | --- | --- |
202
- | `beryl explorations list` | List the agent's exploration passes for a project |
203
- | `beryl explorations get <exploration-id>` | Show one exploration: authored tests, abandoned flows, coverage, frontier |
204
- | `beryl explorations steps <exploration-id>` | List every step the agent took in an exploration |
205
- | `beryl explorations watch <exploration-id>` | Stream an exploration live — watch the agent explore and author tests |
236
+ Inspect the agent's exploration runs — how it crawled a site and authored its tests.
237
+
238
+ | Command | Summary | MCP tool |
239
+ | --- | --- | --- |
240
+ | `beryl explorations list` | List the agent's exploration passes for a project | `explorations_list` |
241
+ | `beryl explorations get <exploration-id>` | Show one exploration: authored tests, abandoned flows, coverage, frontier | `explorations_get` |
242
+ | `beryl explorations steps <exploration-id>` | List every step the agent took in an exploration | `explorations_steps` |
243
+ | `beryl explorations cancel <exploration-id>` | Cancel an in-flight exploration | `explorations_cancel` |
244
+ | `beryl explorations watch <exploration-id>` | Stream an exploration live — watch the agent explore and author tests | `explorations_watch` |
206
245
 
207
246
  ### config
208
247
 
209
- | Command | Summary |
210
- | --- | --- |
211
- | `beryl config vars list` | List the project's config variables (visible to the agent during runs) |
212
- | `beryl config vars set <key> <value>` | Create or update a config variable |
213
- | `beryl config vars delete <key>` | Delete a config variable |
214
- | `beryl config secrets list` | List the project's secrets (values are never returned) |
215
- | `beryl config secrets set <key> <value>` | Create a secret (write-only; re-setting a key replaces it) |
216
- | `beryl config secrets delete <key>` | Delete a secret |
217
- | `beryl config files list` | List files uploaded for the agent to use (e.g. CSVs, upload fixtures) |
218
- | `beryl config files upload <file>` | Upload a file |
219
- | `beryl config files download <file-id>` | Get a short-lived download URL for a file |
220
- | `beryl config files delete <file-id>` | Delete an uploaded file |
248
+ Manage the variables, secrets, and files the agent can use while exploring and running.
249
+
250
+ | Command | Summary | MCP tool |
251
+ | --- | --- | --- |
252
+ | `beryl config vars list` | List the project's config variables (visible to the agent during runs) | `config_vars_list` |
253
+ | `beryl config vars set <key> <value>` | Create or update a config variable | `config_vars_set` |
254
+ | `beryl config vars delete <key>` | Delete a config variable | `config_vars_delete` |
255
+ | `beryl config secrets list` | List the project's secrets (values are never returned) | `config_secrets_list` |
256
+ | `beryl config secrets set <key> <value>` | Create a secret (write-only; re-setting a key replaces it) | `config_secrets_set` |
257
+ | `beryl config secrets delete <key>` | Delete a secret | `config_secrets_delete` |
258
+ | `beryl config files list` | List files uploaded for the agent to use (e.g. CSVs, upload fixtures) | `config_files_list` |
259
+ | `beryl config files upload <file>` | Upload a file | `config_files_upload` |
260
+ | `beryl config files download <file-id>` | Get a short-lived download URL for a file | `config_files_download` |
261
+ | `beryl config files delete <file-id>` | Delete an uploaded file | `config_files_delete` |
262
+
263
+ ### slack
264
+
265
+ Send run outcomes to a Slack channel via a per-project incoming webhook.
266
+
267
+ `beryl slack` with no subcommand runs `slack show`.
268
+
269
+ | Command | Summary | MCP tool |
270
+ | --- | --- | --- |
271
+ | `beryl slack show` | Show the project's Slack alert config (webhook is masked) | `slack_show` |
272
+ | `beryl slack set-webhook <url>` | Set the Slack incoming-webhook URL run alerts post to | `slack_set_webhook` |
273
+ | `beryl slack clear` | Remove the project's Slack webhook (stops all alerts) | `slack_clear` |
274
+ | `beryl slack test` | Post a sample alert to the configured webhook | `slack_test` |
221
275
 
222
276
  ### credentials
223
277
 
224
- | Command | Summary |
225
- | --- | --- |
226
- | `beryl credentials list` | List the workspace's saved logins |
227
- | `beryl credentials get <credential-id>` | Show one saved login (status and freshness — never the session itself) |
228
- | `beryl credentials projects <credential-id>` | List the projects using a saved login |
229
- | `beryl credentials delete <credential-id>` | Delete a saved login |
230
- | `beryl credentials attach <credential-id>` | Attach a saved login to a project |
231
- | `beryl credentials detach` | Detach the project's saved login |
232
- | `beryl credentials recapture <credential-id>` | Start a re-capture for an expiring saved login (returns a live browser URL) |
233
- | `beryl credentials capture` | Capture a login for the project interactively: log in once in a real browser |
278
+ Manage saved logins Beryl reuses to test behind authentication, and attach them to projects.
279
+
280
+ | Command | Summary | MCP tool |
281
+ | --- | --- | --- |
282
+ | `beryl credentials list` | List the workspace's saved logins | `credentials_list` |
283
+ | `beryl credentials get <credential-id>` | Show one saved login (status and freshness — never the session itself) | `credentials_get` |
284
+ | `beryl credentials projects <credential-id>` | List the projects using a saved login | `credentials_projects` |
285
+ | `beryl credentials delete <credential-id>` | Delete a saved login | `credentials_delete` |
286
+ | `beryl credentials attach <credential-id>` | Attach a saved login to a project | `credentials_attach` |
287
+ | `beryl credentials detach` | Detach the project's saved login | `credentials_detach` |
288
+ | `beryl credentials recapture <credential-id>` | Start a re-capture for an expiring saved login (returns a live browser URL) | `credentials_recapture` |
289
+ | `beryl credentials capture` | Capture a login for the project interactively: log in once in a real browser | — |
234
290
 
235
291
  ### auth-capture
236
292
 
237
- | Command | Summary |
238
- | --- | --- |
239
- | `beryl auth-capture start` | Start a login-capture browser session for the project (non-interactive) |
240
- | `beryl auth-capture capture <session-id>` | Capture the session after the user has logged in via the live-view URL |
241
- | `beryl auth-capture refresh <session-id>` | Capture a refreshed session for a project whose login is expiring |
242
- | `beryl auth-capture release <session-id>` | Release a login-capture browser session without capturing |
293
+ Drive a browser session that captures a target-site login for Beryl to reuse.
294
+
295
+ | Command | Summary | MCP tool |
296
+ | --- | --- | --- |
297
+ | `beryl auth-capture start` | Start a login-capture browser session for the project (non-interactive) | `auth_capture_start` |
298
+ | `beryl auth-capture login <session-id>` | Log into the target site headlessly with credentials (no human at the browser) | `auth_capture_login` |
299
+ | `beryl auth-capture capture <session-id>` | Capture the session after the user has logged in via the live-view URL | `auth_capture_capture` |
300
+ | `beryl auth-capture refresh <session-id>` | Capture a refreshed session for a project whose login is expiring | `auth_capture_refresh` |
301
+ | `beryl auth-capture release <session-id>` | Release a login-capture browser session without capturing | `auth_capture_release` |
302
+
303
+ ### inbox
304
+
305
+ Disposable email inboxes for testing flows that send mail — signups, OTPs, receipts.
306
+
307
+ | Command | Summary | MCP tool |
308
+ | --- | --- | --- |
309
+ | `beryl inbox create` | Mint a disposable email inbox that Beryl receives mail for | `inbox_create` |
310
+ | `beryl inbox read <inbox-id>` | Read the latest email from an inbox (waits for one to arrive) | `inbox_read` |
311
+ | `beryl inbox emails <inbox-id>` | List the emails an inbox has received | `inbox_emails` |
243
312
 
244
313
  ### account
245
314
 
246
- | Command | Summary |
247
- | --- | --- |
248
- | `beryl account get` | Show your account profile |
249
- | `beryl account update` | Update your profile |
250
- | `beryl account deletion-preview` | Preview what deleting your account would remove or leave |
315
+ View and update your personal account profile.
316
+
317
+ | Command | Summary | MCP tool |
318
+ | --- | --- | --- |
319
+ | `beryl account get` | Show your account profile | `account_get` |
320
+ | `beryl account update` | Update your profile | `account_update` |
321
+ | `beryl account deletion-preview` | Preview what deleting your account would remove or leave | `account_deletion_preview` |
251
322
 
252
323
  ### feedback
253
324
 
254
- | Command | Summary |
255
- | --- | --- |
256
- | `beryl feedback send <message>` | Send product feedback to the Beryl team |
325
+ Send product feedback to the Beryl team.
326
+
327
+ | Command | Summary | MCP tool |
328
+ | --- | --- | --- |
329
+ | `beryl feedback send <message>` | Send product feedback to the Beryl team | `feedback_send` |
257
330
 
258
331
  ### billing
259
332
 
260
- | Command | Summary |
261
- | --- | --- |
262
- | `beryl billing usage` | Show plan usage: services and weekly AI units |
263
- | `beryl billing subscription` | Show the workspace's subscription |
264
- | `beryl billing invoices` | List recent invoices |
265
- | `beryl billing portal` | Get a Stripe billing-portal link for the workspace |
333
+ Review a workspace's plan usage, subscription, and invoices.
334
+
335
+ | Command | Summary | MCP tool |
336
+ | --- | --- | --- |
337
+ | `beryl billing usage` | Show plan usage: services and weekly AI units | `billing_usage` |
338
+ | `beryl billing subscription` | Show the workspace's subscription | `billing_subscription` |
339
+ | `beryl billing invoices` | List recent invoices | `billing_invoices` |
340
+ | `beryl billing portal` | Get a Stripe billing-portal link for the workspace | `billing_portal` |
266
341
 
267
342
  ### mcp
268
343
 
269
- | Command | Summary |
270
- | --- | --- |
271
- | `beryl mcp` | Run the Beryl MCP server (stdio) — every CLI command as an agent tool |
344
+ Run the Beryl MCP server (stdio) — every CLI command as an agent tool
345
+
346
+ | Command | Summary | MCP tool |
347
+ | --- | --- | --- |
348
+ | `beryl mcp` | Run the Beryl MCP server (stdio) — every CLI command as an agent tool | — |
272
349
 
273
350
  Run `beryl <command> --help` for flags and examples.
274
351
 
275
352
  ## Global flags
276
353
 
354
+ - `-V, --version` — Print the CLI version and exit
277
355
  - `--json` — Print machine-readable JSON (NDJSON for streams)
278
356
  - `--api-url` — API base URL (default https://api.beryl.so)
279
357
  - `--token` — Personal access token (overrides config/BERYL_API_KEY)
280
- - `--help` — Show help
358
+ - `-h, --help` — Show help
package/dist/adapters/cli.js CHANGED
@@ -4,8 +4,10 @@ import { createContext } from "../context.js";
4
4
  import { CliError, EXIT_OK, EXIT_USAGE, UsageError } from "../errors.js";
5
5
  import { ApiClient } from "../http.js";
6
6
  import { autoFormat, bold, cyan, dim } from "../output.js";
7
- import { commandGroups, findCommand } from "../registry/index.js";
7
+ import { commandGroups, findCommand, groupSummary } from "../registry/index.js";
8
+ import { mcpToolFor } from "./mcp.js";
8
9
  export const GLOBAL_FLAGS = [
10
+ { name: "version", description: "Print the CLI version and exit", alias: "V" },
9
11
  { name: "json", description: "Print machine-readable JSON (NDJSON for streams)" },
10
12
  { name: "api-url", description: "API base URL (default https://api.beryl.so)", value: true },
11
13
  { name: "token", description: "Personal access token (overrides config/BERYL_API_KEY)", value: true },
@@ -137,10 +139,25 @@ export function usageLine(spec) {
137
139
  .join(" ");
138
140
  return `Usage: beryl ${spec.name}${args ? " " + args : ""} [flags]`;
139
141
  }
142
+ function globalFlagLabel(flag) {
143
+ const value = "value" in flag && flag.value ? " <value>" : "";
144
+ const long = `--${flag.name}${value}`;
145
+ return "alias" in flag && flag.alias ? `-${flag.alias}, ${long}` : long;
146
+ }
147
+ function globalFlagLines() {
148
+ const lines = [bold("Global options:")];
149
+ for (const g of GLOBAL_FLAGS) {
150
+ lines.push(` ${cyan(globalFlagLabel(g).padEnd(24))} ${g.description}`);
151
+ }
152
+ return lines;
153
+ }
140
154
  export function commandHelp(spec) {
141
155
  const lines = [spec.summary, "", usageLine(spec)];
142
156
  if (spec.description)
143
157
  lines.push("", spec.description);
158
+ const tool = mcpToolFor(spec);
159
+ if (tool)
160
+ lines.push("", `${dim("MCP tool:")} ${cyan(tool)}`);
144
161
  if (spec.args?.length) {
145
162
  lines.push("", bold("Arguments:"));
146
163
  for (const a of spec.args)
@@ -154,10 +171,7 @@ export function commandHelp(spec) {
154
171
  lines.push(` ${cyan(label.padEnd(24))} ${f.description}${suffix}`);
155
172
  }
156
173
  }
157
- lines.push("", bold("Global flags:"));
158
- for (const g of GLOBAL_FLAGS) {
159
- lines.push(` ${cyan(("--" + g.name).padEnd(24))} ${g.description}`);
160
- }
174
+ lines.push("", ...globalFlagLines());
161
175
  if (spec.examples?.length) {
162
176
  lines.push("", bold("Examples:"));
163
177
  for (const e of spec.examples)
@@ -171,25 +185,39 @@ export function rootHelp() {
171
185
  "",
172
186
  "Usage: beryl <command> [args] [flags]",
173
187
  "",
188
+ bold("Commands:"),
174
189
  ];
175
190
  for (const [group, specs] of commandGroups()) {
176
- if (specs.length === 1 && specs[0].name === group) {
177
- lines.push(` ${cyan(group.padEnd(14))} ${specs[0].summary}`);
191
+ const single = specs.length === 1 && specs[0].name === group;
192
+ const purpose = single ? specs[0].summary : groupSummary(specs);
193
+ lines.push(` ${cyan(group.padEnd(14))} ${purpose ?? ""}`.trimEnd());
194
+ if (single) {
195
+ const tool = mcpToolFor(specs[0]);
196
+ if (tool)
197
+ lines.push(` ${" ".repeat(14)} ${dim("MCP tool " + tool)}`);
178
198
  }
179
199
  else {
180
- lines.push(` ${cyan(group.padEnd(14))} ${specs
181
- .map((s) => s.name.split(" ").slice(1).join(" "))
182
- .join(", ")}`);
200
+ const subs = specs.map((s) => s.name.split(" ").slice(1).join(" ")).join(", ");
201
+ const toolPrefix = group.replace(/-/g, "_");
202
+ const tools = specs.some((s) => mcpToolFor(s)) ? ` · ${dim("MCP tools " + toolPrefix + "_*")}` : "";
203
+ lines.push(` ${" ".repeat(14)} ${dim(subs)}`, ` ${" ".repeat(14)} ${dim(`beryl ${group} --help`)}${tools}`);
183
204
  }
184
205
  }
206
+ lines.push("", ...globalFlagLines());
185
207
  lines.push("", `Run ${cyan("beryl <command> --help")} for details, ${cyan("beryl login")} to get started.`, `Docs: ${cyan("https://beryl.so/docs/cli")}`);
186
208
  return lines.join("\n");
187
209
  }
188
210
  function groupHelp(group, specs) {
189
211
  const lines = [`${bold("beryl " + group)} — subcommands:`, ""];
212
+ const purpose = groupSummary(specs);
213
+ if (purpose)
214
+ lines.push(purpose, "");
190
215
  for (const spec of specs) {
191
216
  const suffix = spec.groupDefault ? dim(` (default — \`beryl ${group}\` runs this)`) : "";
192
217
  lines.push(` ${cyan(spec.name.padEnd(28))} ${spec.summary}${suffix}`);
218
+ const tool = mcpToolFor(spec);
219
+ if (tool)
220
+ lines.push(` ${" ".repeat(28)} ${dim("MCP tool " + tool)}`);
193
221
  }
194
222
  lines.push("", `Run ${cyan(`beryl ${group} <subcommand> --help`)} for details.`);
195
223
  return lines.join("\n");
@@ -202,7 +230,7 @@ export async function runCli(argv) {
202
230
  break;
203
231
  words.push(tok);
204
232
  }
205
- if (argv.includes("--version") || argv[0] === "version") {
233
+ if (argv.includes("--version") || argv.includes("-V") || argv[0] === "version") {
206
234
  process.stdout.write(cliVersion() + "\n");
207
235
  return EXIT_OK;
208
236
  }
package/dist/adapters/mcp.js CHANGED
@@ -11,6 +11,12 @@ export function toolName(spec) {
11
11
  export function mcpTools() {
12
12
  return commands.filter((c) => !c.interactive && !c.hidden && c.name !== "mcp");
13
13
  }
14
+ const mcpToolNames = new Set(mcpTools().map(toolName));
15
+ /** The tool name a command is exposed as under `beryl mcp`, or undefined if it isn't exposed. */
16
+ export function mcpToolFor(spec) {
17
+ const name = toolName(spec);
18
+ return mcpToolNames.has(name) ? name : undefined;
19
+ }
14
20
  export function toolInputSchema(spec) {
15
21
  const properties = {};
16
22
  const required = [];