@vigilbase/cli 0.2.1 → 0.2.2

package/CLOUDFLARE.md

@@ -2,7 +2,7 @@
 
 `vigilbase cf` and `vigilbase cloudflare` use the authenticated Vigilbase One API. Run `vigilbase login` first (signing in isn't supported on Windows yet). Your organization, permissions, customer links, and allowed zones determine access. The CLI never requires a Cloudflare API key.
 
-`cf checkup` runs on One's servers. `cloudflare-checkup` (also `local cloudflare-checkup`) runs on your machine with Cloudflare's own `cf` CLI and needs no Vigilbase login: one command, `npx @vigilbase/cli cloudflare-checkup`, verifies your work email with a code, installs cf if needed, signs in read-only, collects and uploads after you confirm. It works while vigilbase.com has local checkups switched on; otherwise it says so before asking for your email and points you to the checkup in your browser at https://vigilbase.com/tools/cloudflare-checkup (see [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/LOCAL.md)).
+`cf checkup` runs on One's servers. `cloudflare-checkup` (also `local cloudflare-checkup`) runs on your machine with Cloudflare's own `cf` CLI and needs no Vigilbase login: one command, `npx @vigilbase/cli cloudflare-checkup`, verifies your work email with a code, installs cf if needed, signs in read-only, collects and uploads after you confirm. It works while vigilbase.com has local checkups switched on; otherwise it says so before asking for your email and points you to the checkup in your browser at https://vigilbase.com/tools/cloudflare-checkup (see [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/LOCAL.md)).
 
 Customer provider access requires an `active` or `trialing` Cloudflare service
 entitlement for the selected account. Historical/inactive rows and legacy account
@@ -22,13 +22,13 @@ vigilbase cf zones
 vigilbase cf workspace --json
 ```
 
-`--customer-id` explicitly selects a customer; it never grants access to that customer. Customer users can usually omit it when their organization identifies the customer. Internal users should select it for customer-specific operations. Analytics always requires it. Live zone detail requires it; zone detail without it uses the stored workspace inventory.
+`--customer-id` explicitly selects a customer; it never grants access to that customer. Customer users can usually omit it when their organization identifies the customer. Internal users should select it for customer-specific operations: One answers accounts, workspace and checkup reads without it with HTTP 400. Analytics, DNS, WAF and speed settings always require it, for every user: One refuses these reads without it, so the CLI stops before sending them. Live zone detail requires it; zone detail without it uses the stored workspace inventory. When One answers 400 to accounts, workspace or checkup reads because the customer is missing, the CLI adds the hint `Vigilbase staff: add --customer-id <uuid>.`
 
 An account or zone positional ID can instead be supplied using `--account-id` or `--zone-id` for commands that take that kind of ID. Supplying both requires identical values. Account-resource commands reject `--zone-id`; DNS, WAF, and speed-settings reject `--account-id` because those APIs scope by zone. `--days` is accepted only for analytics.
 
 ## Command grammar
 
-In this table, `C` means `[--customer-id <uuid>]`, `A` means `[--account-id <hex-id>]`, and `Z` means `[--zone-id <hex-id>]`. Every command also accepts the common options above.
+In this table, `C` means `[--customer-id <uuid>]`, `C!` means a required `--customer-id <uuid>`, `A` means `[--account-id <hex-id>]`, and `Z` means `[--zone-id <hex-id>]`. Every command also accepts the common options above.
 
 | Command | Selection | Result |
 | --- | --- | --- |
@@ -38,9 +38,9 @@ In this table, `C` means `[--customer-id <uuid>]`, `A` means `[--account-id <hex
 | `cf accounts` | C A | Accessible account inventory including customer and service IDs |
 | `cf account <account-id>` | C | One stored account summary |
 | `cf workspace [section]` | C A Z | Workspace bootstrap or section data |
-| `cf dns <zone-id>` | C | DNS record IDs, types, names, contents, TTL and proxy state |
-| `cf waf <zone-id>` | C | Rules, expressions, analytics availability and suggestions |
-| `cf speed-settings <zone-id>` | C | Current performance settings; internal access required |
+| `cf dns <zone-id>` | C! | DNS record IDs, types, names, contents, TTL and proxy state |
+| `cf waf <zone-id>` | C! | Rules, expressions, analytics availability and suggestions |
+| `cf speed-settings <zone-id>` | C! | Current performance settings; internal access required |
 | `cf audit-logs <account-id>` | C | Most recent provider audit events, up to 100 |
 | `cf zero-trust <account-id>` | C | Users, Access applications, tunnels and authentication analytics |
 | `cf developer-platform <account-id>` | C | Workers, Workers analytics and Pages projects |
@@ -64,8 +64,8 @@ Replace example IDs with IDs from your account inventory:
 ```bash
 vigilbase cf account bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
 vigilbase cf zone aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --customer-id cb156546-b6ba-42a9-bdd0-4a09cb156546
-vigilbase cf dns aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --json
-vigilbase cf waf aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+vigilbase cf dns aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --customer-id cb156546-b6ba-42a9-bdd0-4a09cb156546 --json
+vigilbase cf waf aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --customer-id cb156546-b6ba-42a9-bdd0-4a09cb156546
 vigilbase cf zero-trust bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb --json
 vigilbase cf developer-platform bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
 vigilbase cf magic-transit bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb

package/COMMANDS.md

@@ -2,18 +2,19 @@
 
 The CLI uses public scanner APIs on `vigilbase.com` and authenticated APIs on
 `one.vigilbase.com`. Use `vigilbase <command> --help` or
-`vigilbase help <command>` for built-in help. Examples below omit `--json`,
-which every command supports.
+`vigilbase help <command>` for built-in help, and `vigilbase help <tool>` (for
+example `vigilbase help website-security`) for how to run a tool. Examples
+below omit `--json`, which every command supports.
 
 ## References
 
 | Area | Complete command and API reference |
 | --- | --- |
-| Cloudflare | [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/CLOUDFLARE.md) |
-| Security | [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/SECURITY.md) |
-| Customers, organizations, monitoring, support | [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/ONE.md) |
-| Local Cloudflare Checkup (cf on your machine) | [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/LOCAL.md) |
-| Sign-in, credentials, configuration, troubleshooting | [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/README.md) |
+| Cloudflare | [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/CLOUDFLARE.md) |
+| Security | [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/SECURITY.md) |
+| Customers, organizations, monitoring, support | [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/ONE.md) |
+| Local Cloudflare Checkup (cf on your machine) | [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/LOCAL.md) |
+| Sign-in, credentials, configuration, troubleshooting | [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/README.md) |
 
 The references list the supported operations, filters, response and pagination
 behaviour, API endpoints and access requirements of the CLI.
@@ -36,8 +37,13 @@ fragments. One requires HTTPS, except HTTP for loopback development.
 `--customer-id` is a command-specific One customer UUID; it does not change the
 session's permissions. API reads may still return 403 when the signed-in role
 lacks access. Unknown flags, flags a command doesn't take (including scope
-flags) and extra arguments fail before any API request. `--style` applies only
-to `badge`.
+flags), missing arguments and extra arguments fail before any API request. A
+missing argument is named with the command's usage, for example
+`Missing <url>. Usage: vigilbase headers <url>` or
+`Missing <customer-id>. Usage: vigilbase customers summary <customer-id>`.
+`cf dns`, `cf waf` and `cf speed-settings` require `--customer-id` before
+they send a request, because One refuses these reads without it. `--style`
+applies only to `badge`.
 
 ## Authentication
 
@@ -52,7 +58,7 @@ issuer's `/.well-known/openid-configuration` (for production,
 | `login --token <bearer>` | Older input, discouraged because arguments can appear in process lists and history. `VIGILBASE_ONE_TOKEN` also works; neither combines with `--token-stdin` | Same as `--token-stdin` |
 | `whoami` | Shows the saved session; signed out is a successful answer. Notes a CLI 0.2.0 `credentials.json` that is being ignored | Identity: discovery and userinfo (a refresh first if due). Legacy: One `GET /api/auth/get-session` |
 | `logout` | Revokes every saved Identity sign-in, signs a legacy session out, then deletes the credential files. A sign-in Identity has already ended counts as revoked; any other failed Identity revocation keeps every file | Identity: discovery, then `POST /api/auth/oauth2/revoke` per saved sign-in. Legacy: One `POST /api/auth/sign-out` (best effort) |
-| `doctor` | Checks the public API, your session and your saved sign-in independently; exits 1 if any check fails | `GET {base-url}/api/agent/tools`. Signed out or legacy: One `GET /api/auth/get-session`. Identity: `GET {issuer}/.well-known/openid-configuration`, then the userinfo endpoint it names (One is not contacted); a refresh at the token endpoint first if the access token expires within 60 seconds |
+| `doctor` | Checks the public API, your session and your saved sign-in independently; exits 1 if any check fails | `GET {base-url}/api/v1/agent/tools`. Signed out or legacy: One `GET /api/auth/get-session`. Identity: `GET {issuer}/.well-known/openid-configuration`, then the userinfo endpoint it names (One is not contacted); a refresh at the token endpoint first if the access token expires within 60 seconds |
 
 Credentials are saved atomically with owner-only permissions in
 `identity-credentials.json` (Identity) or `credentials.json` (legacy One
@@ -70,12 +76,28 @@ checked: One's `get-session`, the discovered userinfo endpoint, or the
 issuer's discovery URL when discovery itself failed. `checks.signIn` has no
 `url`.
 
+`whoami` JSON has `authenticated`, `oneBaseUrl`, `user`, `issuer`,
+`clientId`, `resource`, `organizationId`, `expiresAt`, `scope`, `obtainedAt`,
+`authRequiredTools` and `legacyIdentityFileIgnored`. `expiresAt` and `scope`
+are those of the access token in use, after any refresh `whoami` just made.
+`obtainedAt` is when you signed in; a refresh doesn't change it. Signed out,
+`expiresAt`, `scope` and `obtainedAt` are `null`.
+
+`authRequiredTools` means something different per command. The names stay as
+they are so scripts keep working:
+
+| Command | `authRequiredTools` in JSON |
+| --- | --- |
+| `list`, `doctor` | Every tool that needs a One sign-in, whether you are signed in or not. In `list`, `oneExecutableTools` is what you can run through One now |
+| `whoami` | The tools your sign-in unlocks: the same tools when signed in, `[]` when signed out |
+| `login` | Every tool that needs a One sign-in; all of them are unlocked once login succeeds |
+
 ## Public scanners and authenticated scans
 
 | Command | Options | API |
 | --- | --- | --- |
-| `list` (alias `tools`) | Lists the public catalog and the One-only scanners | GET `/api/agent/tools` |
-| `run <tool> <target>` | `--via public\|one`; `--public` forces the public API | POST `/api/agent/tools/<tool>/execute` (anonymous) or One POST `/api/tools/<tool>/execute` |
+| `list` (alias `tools`) | Lists the public catalog and the One-only scanners | GET `/api/v1/agent/tools` |
+| `run <tool> <target>` | `--via public\|one`; `--public` forces the public API | POST `/api/v1/agent/tools/<tool>/execute` (anonymous) or One POST `/api/tools/<tool>/execute` |
 | `headers <url>` | Shortcut for `run security-headers`; same routing options | Same as `run` |
 | `email <domain>` | Shortcut for `run email-security`; same routing options | Same as `run` |
 | `describe <tool>` | `--no-skill` skips fetching skill Markdown | Catalog plus the tool's published skill URL |
@@ -83,10 +105,16 @@ issuer's discovery URL when discovery itself failed. `checks.signIn` has no
 | `badge <domain>` | `--style default\|compact\|mini` | None; builds the public badge URL locally |
 
 Public tools: `security-headers`, `email-security`. One-only tools:
-`website-security`, `react2shell`, `fortibleed-check`. Public scans use the
+`website-security`, `react2shell`, `fortibleed-check`. Tools aren't commands of
+their own: run them with `run <tool> <target>` (`vigilbase help <tool>` prints
+that usage offline). Public scans use the
 public API unless you add `--via one`; being signed in doesn't change that.
 `--public` and `--via one` cannot be combined.
 
+Public paths are relative to `--base-url`. CLI 0.2.1 and earlier call the
+unversioned `/api/agent/tools` instead, which vigilbase.com plans to retire on
+1 September 2027.
+
 The public route is anonymous and never reads your saved sign-in, the
 credentials lock or Identity, so sign-in problems cannot make it fail. Runs
 that go through One (`--via one` and the One-only tools) need a sign-in.
@@ -130,6 +158,8 @@ Otherwise it prints `Request failed (HTTP <status>).`
 | `billing` | `summary`, `show`, `status` | GET `/api/account/billing` |
 | `billing portal` | `open`; `--no-open` prints the portal URL without opening a browser | POST `/api/billing/portal` |
 
+Invitations need a One browser session: Identity's management API doesn't accept CLI sign-ins, so `account invites` and `account invites create` answer 403 (`browser_session_required`) and the CLI points you to https://one.vigilbase.com.
+
 Creating an invitation sends it; `billing portal` starts a Stripe portal
 session. Both are explicit actions. Billing data comes from One's Stripe
 integration; the CLI does not store invoices or payment information.
@@ -200,6 +230,19 @@ also exits 1. A signed-out `whoami` is not a failure, and a healthy `doctor`
 does not need a sign-in. API error JSON keeps the status, code and retry delay
 when available.
 
+Vigilbase One's error messages are never shown, because they can describe
+One's configuration: the CLI prints `Request failed (HTTP <status>).` When it
+recognises the failure from the route, the status and One's error code, it adds
+a hint of its own (`Hint: …` in text, `hint` in JSON):
+
+| One answers | Hint |
+| --- | --- |
+| 400 without `--customer-id` to `support tickets`, or to a `cf` command that reads the Cloudflare workspace or checkups (`cf accounts`, `cf account`, `cf workspace`, `cf zones` with filters, `cf checkup`, `cf checkup start`) | `Vigilbase staff: add --customer-id <uuid>.` |
+| 403 to `security settings …` or `security notifications preferences` with `--customer-id` | `Personal settings belong to each user, so View-as (--customer-id) cannot read them.` |
+
+A security command that needs a customer (`FLAREHAWK_VIEW_AS_REQUIRED`) says
+`Select a customer with --customer-id <customer UUID> for security commands.`
+
 Security and customer operations keep JSON response envelopes and pagination
 fields. Cloudflare inventory commands may apply the account or zone filter you
 asked for locally as well as sending it to One; zone detail returns the

package/LOCAL.md

@@ -15,7 +15,7 @@ before it asks for your email; when local mode is off it stops with
 your browser at <https://vigilbase.com/tools/cloudflare-checkup>.
 
 `vigilbase cf checkup` runs on Vigilbase One's servers with stored credentials
-(see [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/CLOUDFLARE.md));
+(see [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/CLOUDFLARE.md));
 `vigilbase cloudflare-checkup` runs on your machine and needs no Vigilbase
 login.
 
@@ -31,7 +31,10 @@ npx @vigilbase/cli cloudflare-checkup
 If it answers `Unknown command "cloudflare-checkup"`, an older global install
 of the CLI (0.1.x) is running instead: `npx` prefers an installed global
 `@vigilbase/cli`. Run `npx @vigilbase/cli@latest cloudflare-checkup` once, or
-update the global install with `npm install -g @vigilbase/cli@latest`.
+update the global install with `npm install -g @vigilbase/cli@latest`. With
+Yarn 4.15+ or pnpm 11+, `yarn dlx` and `pnpm dlx` run an older release for a
+day after each release; use `npx` (see
+[Troubleshooting](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/README.md#troubleshooting)).
 
 The command does everything, in this order, and stops at the first problem
 before any slower step:
@@ -674,7 +677,7 @@ are never echoed.
 | `ACCOUNT_TOO_LARGE` | Over 100 zones: run the checkup in your browser instead, https://vigilbase.com/tools/cloudflare-checkup. |
 | `ACCOUNT_MISMATCH` | The checkup is bound to another account; run the same command again without `--account-id`. |
 | `OUTPUT_EXISTS` | Choose another `--out`, or pass `--overwrite`. |
-| `SNAPSHOT_INVALID` / `SNAPSHOT_SECRET_LIKE_VALUE` | Run the same command again (remove the credential-like text from the rule or name first). |
+| `SNAPSHOT_INVALID` / `SNAPSHOT_SECRET_LIKE_VALUE` | Run the same command again (remove the credential-like text from the rule or name first). When `inspect` or `submit` finds no file at the path, check the path, or collect one with `npx @vigilbase/cli cloudflare-checkup collect --out <file>`. |
 | `SNAPSHOT_TOO_LARGE` | Run the checkup in your browser instead, https://vigilbase.com/tools/cloudflare-checkup. |
 | `SNAPSHOT_STALE` | Snapshots are accepted for 24 hours; run the same command again. |
 | `EMAIL_INVALID` | Use your work email (personal and disposable addresses are refused), then run the same command again. |

package/ONE.md

@@ -12,6 +12,7 @@ vigilbase monitoring status CUSTOMER_UUID --light
 vigilbase monitoring history CUSTOMER_UUID --range 7d --region ams
 vigilbase orgs members
 vigilbase support tickets --all --limit 100
+vigilbase support tickets --customer-id CUSTOMER_UUID
 ```
 
 Replace uppercase placeholders with IDs from the corresponding list. Customer, report, Vigil investigation, and monitoring target IDs must be UUIDs. Organization IDs may contain letters, digits, underscores, and hyphens (maximum 256 characters).
@@ -87,11 +88,11 @@ A successful health response may describe an unconfigured backend or unknown pro
 ## Support
 
 ```sh
-vigilbase support tickets [--all] [--limit 1..100] [--json]
+vigilbase support tickets [--all] [--limit 1..100] [--customer-id <uuid>] [--json]
 ```
 
-`vigilbase support` also defaults to `tickets`. Maps to GET `/api/support/tickets?includeAll=true&limit=N`; omitted flags omit their query parameters. Requires `support:access`. The API identifies the current organization and its Pylon account. Open tickets are returned by default; `--all` includes closed tickets. Limit defaults to 50. An unlinked account returns an empty list with the API's explanation. `hasMore` is preserved, but this API exposes no cursor pagination. The API may rate-limit requests or return 503 when Pylon is unavailable.
+`vigilbase support` also defaults to `tickets`. Maps to GET `/api/support/tickets?includeAll=true&limit=N&customerId=UUID`; omitted flags omit their query parameters. Requires `support:access`. Without `--customer-id`, the API uses the current organization's customer and its Pylon account. Vigilbase staff must choose the customer with `--customer-id <uuid>` (a UUID from `vigilbase customers list`); One checks your access to it. Without it, One answers HTTP 400 and the CLI prints `Request failed (HTTP 400).` with the hint `Vigilbase staff: add --customer-id <uuid>.` Open tickets are returned by default; `--all` includes closed tickets. Limit defaults to 50. An account with no customer or no Pylon link returns an empty list with the API's explanation. `hasMore` is preserved, but this API exposes no cursor pagination. The API may rate-limit requests or return 503 when Pylon is unavailable.
 
 ## Related commands and validation
 
-See [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/README.md) for sign-in and configuration, [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/COMMANDS.md) for account, billing, public scanners, run history and Watchdog, [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/CLOUDFLARE.md) for `cf`/`cloudflare`, and [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/SECURITY.md) for security commands. The read operations above do not replace the existing explicitly confirmed write commands.
+See [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/README.md) for sign-in and configuration, [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/COMMANDS.md) for account, billing, public scanners, run history and Watchdog, [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/CLOUDFLARE.md) for `cf`/`cloudflare`, and [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/SECURITY.md) for security commands. The read operations above do not replace the existing explicitly confirmed write commands.

package/README.md

@@ -28,14 +28,14 @@ supported on Windows yet; public tools and `cloudflare-checkup` still work there
 
 | Reference | Covers |
 | --- | --- |
-| [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/COMMANDS.md) | Core commands, aliases, global options, API mapping, sign-in, output |
-| [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/CLOUDFLARE.md) | Accounts, zones, DNS, WAF, analytics, Zero Trust, Workers/Pages, audit, checkups |
-| [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/SECURITY.md) | Incidents, logs, intelligence, analytics, assets, connections, policies, notifications, reports |
-| [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/ONE.md) | Customer records, billing, reports, investigations, organizations, monitoring, support |
-| [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/LOCAL.md) | `cloudflare-checkup`: verifies your work email, collects your Cloudflare configuration on your machine with Cloudflare's `cf` and uploads it after you confirm |
+| [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/COMMANDS.md) | Core commands, aliases, global options, API mapping, sign-in, output |
+| [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/CLOUDFLARE.md) | Accounts, zones, DNS, WAF, analytics, Zero Trust, Workers/Pages, audit, checkups |
+| [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/SECURITY.md) | Incidents, logs, intelligence, analytics, assets, connections, policies, notifications, reports |
+| [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/ONE.md) | Customer records, billing, reports, investigations, organizations, monitoring, support |
+| [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/LOCAL.md) | `cloudflare-checkup`: verifies your work email, collects your Cloudflare configuration on your machine with Cloudflare's `cf` and uploads it after you confirm |
 
 These files ship with the package. Built-in help: `vigilbase <command> --help`
-or `vigilbase help <command>`.
+or `vigilbase help <command>`; `vigilbase help <tool>` shows how to run a tool.
 
 ## Examples
 
@@ -70,8 +70,8 @@ Cloudflare IDs come from the inventory you can access:
 ```bash
 vigilbase cf accounts
 vigilbase cf zones
-vigilbase cf dns <zone-id>
-vigilbase cf waf <zone-id> --json
+vigilbase cf dns <zone-id> --customer-id <customer-uuid>
+vigilbase cf waf <zone-id> --customer-id <customer-uuid> --json
 vigilbase cf zero-trust <account-id>
 vigilbase cf developer-platform <account-id>
 vigilbase cf analytics --customer-id <customer-uuid> --zone-id <zone-id> --days 7
@@ -94,8 +94,9 @@ vigilbase security audit --limit 50
 ```
 
 Customer users inherit their organization's scope. Internal operators add
-`--customer-id <customer-uuid>` for security views; Cloudflare analytics needs
-it too. Other customer-specific commands take the customer UUID as an argument.
+`--customer-id <customer-uuid>` for security views and support tickets.
+Everyone adds it to `cf analytics`, `cf dns`, `cf waf` and `cf speed-settings`.
+Other customer-specific commands take the customer UUID as an argument.
 Flags select records; One still decides whether your session can see them.
 
 After reviewing an incident, you can update its status explicitly:
@@ -142,7 +143,7 @@ read-only Cloudflare API token instead. When you are done:
 npx @vigilbase/cli cloudflare-checkup logout   # removes the read-only cf login and the cf it installed
 ```
 
-See [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/LOCAL.md) for
+See [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/LOCAL.md) for
 every step, what is uploaded and the error codes.
 
 ## Public tools and sign-in
@@ -191,7 +192,8 @@ fails and vigilbase.com explains why, the CLI shows that reason:
 reason is shown only when vigilbase.com sends it as a known error code, and it
 is cleaned to one line of at most 300 characters. Anything else, and every
 Vigilbase One error, prints only `Request failed (HTTP <status>).` without the
-server's text. Hints (`Hint: …`, `hint` in JSON) are always written by the CLI.
+server's text. Hints (`Hint: …`, `hint` in JSON) are always written by the CLI;
+COMMANDS.md lists the One errors that get one.
 
 Commands use named One APIs and One's own authorization. They never take
 Cloudflare or other provider secrets, delegated identity claims or an arbitrary
@@ -246,14 +248,14 @@ that passes the [directory checks](#directory-checks) but can't be parsed.
 ### Using CLI 0.1.x or 0.2.0 too
 
 - CLI 0.2.0 kept its Identity sign-in in `credentials.json`, which CLI 0.1.x
-  cannot read. The first 0.2.1 command that reads your sign-in moves it to
-  `identity-credentials.json` (under the lock), unless that file already
-  exists. From then on `credentials.json` is either absent or a legacy session
-  that 0.1.x can use.
+  cannot read. The first command of 0.2.1 or later that reads your sign-in
+  moves it to `identity-credentials.json` (under the lock), unless that file
+  already exists. From then on `credentials.json` is either absent or a legacy
+  session that 0.1.x can use.
 - If 0.2.0 later saves a new `credentials.json` while
-  `identity-credentials.json` exists, 0.2.1 ignores it. `whoami` notes it
-  (`legacyIdentityFileIgnored` in JSON), and `vigilbase logout` revokes and
-  removes it.
+  `identity-credentials.json` exists, 0.2.1 and later ignore it. `whoami`
+  notes it (`legacyIdentityFileIgnored` in JSON), and `vigilbase logout`
+  revokes and removes it.
 - An Identity login leaves a legacy `credentials.json` alone. A token login or
   a legacy device login first revokes and removes any Identity sign-in, so the
   new session is the one in use; if that revocation fails, login stops and
@@ -390,7 +392,7 @@ to 8 MiB; timeouts cover reading the body.
 **Check connectivity.** `vigilbase doctor` (add `--json` for details) runs
 three checks on their own and exits 1 if any fails:
 
-- `publicApi`: `GET https://vigilbase.com/api/agent/tools`.
+- `publicApi`: `GET https://vigilbase.com/api/v1/agent/tools`.
 - `one`: your session. Signed out or with a legacy session,
   `GET https://one.vigilbase.com/api/auth/get-session`; a signed-out answer
   counts as reachable. With an Identity sign-in, the issuer's
@@ -409,6 +411,14 @@ takes priority over a bare `npx @vigilbase/cli`. Update it with
 `npx @vigilbase/cli@latest cloudflare-checkup`. `vigilbase --version` shows
 which version answers.
 
+**`yarn dlx` or `pnpm dlx` runs an older version.** Yarn 4.15 and later and
+pnpm 11 and later skip releases published in the last 24 hours by default
+(Yarn's `npmMinimalAgeGate`, pnpm's `minimumReleaseAge`). For a day after a
+release, `yarn dlx @vigilbase/cli` and `pnpm dlx @vigilbase/cli` run an
+older release, and Yarn refuses the new version by number
+(`All versions satisfying "…" are quarantined`). Use `npx @vigilbase/cli`, or
+wait a day.
+
 **`Device sign-in isn't available at <origin> right now.`** Login got a 404
 from that origin. If you set `--one-url` or `--auth-url`, check it; otherwise
 try again later or email help@vigilbase.com. Public tools work without signing

package/SECURITY.md

@@ -40,7 +40,7 @@ Logs require `--start` and `--end` together as ISO timestamps with an explicit t
 | `assets datasets <asset>` | None | `/fabric/assets/<asset>/datasets` |
 | `assets graph <asset>` | `--dataset`, `--hours`, `--min-weight`, `--limit` | `/fabric/assets/<asset>/graph` |
 | `fabric default-asset` | None | `/fabric/default-asset` |
-| `detections` | `--asset-id` | `/detections?asset_id=…` when scoped |
+| `detections --asset-id <asset>` | None | `/detections?asset_id=<asset>` |
 | `providers` | None | `/providers?connectable=false` |
 | `connections [list]` | None | `/connections` |
 | `connections show <connection>` | None | `/connections/<connection>` |
@@ -49,6 +49,8 @@ Logs require `--start` and `--end` together as ISO timestamps with an explicit t
 | `connections logpush-status <connection> <job>` | None | `/connections/<connection>/logpush-jobs/<job>/status` |
 | `connections worker-stats <connection> <job>` | None | `/connections/<connection>/worker-routes/<job>/stats` |
 
+Detections are configured per asset, and the API has no list for the whole tenant, so `--asset-id` is required; without it the CLI stops before any request. Take asset IDs from `security assets`.
+
 Graph `--hours` maps to `window_hours`; `--min-weight` maps to `min_weight`. Incident graphs use the incident window and reject `--hours`. IP lists retain enforcement verification and synchronization status. Connection health includes stored state, provider status, receipt health, and available warnings. Credential-bearing HEC profile retrieval is outside this command set.
 
 ## Analytics and Cloudflare security
@@ -97,7 +99,7 @@ Provider events map `--provider` to `provider_id`, `--dataset` to `dataset_id`,
 | `settings broadcast-emails` | None | `/settings/broadcast-emails` |
 | `settings applications` | None | `/integrations/grants` |
 
-Intel lookup input is trimmed and limited to 512 characters; the server validates the indicator and applies lookup quota. Personal settings show existing preferences and authorized application grants. They do not change preferences or revoke grants. Reports are fetched on demand; this CLI does not persist report or billing records.
+Intel lookup input is trimmed and limited to 512 characters; the server validates the indicator and applies lookup quota. Personal settings show existing preferences and authorized application grants. They do not change preferences or revoke grants. Personal settings and `notifications preferences` belong to each user: with `--customer-id` (View-as), a refusal prints `Request failed (HTTP 403).` with the hint `Personal settings belong to each user, so View-as (--customer-id) cannot read them.` Reports are fetched on demand; this CLI does not persist report or billing records.
 
 ## Limits and pagination
 

package/dist/cli.js

@@ -4,7 +4,7 @@ import { VigilbaseApiError, VigilbaseClient } from './lib/client.js';
 import { createConfig, createLocalCommandConfig } from './lib/config.js';
 import { renderBanner, shouldShowBanner } from './lib/banner.js';
 import { createWriter, formatError } from './lib/format.js';
-import { HELP_TAGLINE, HELP_TEXT, helpForCommand } from './lib/help.js';
+import { HELP_TAGLINE, HELP_TEXT, HELP_USAGE, helpForCommand, isCatalogTool } from './lib/help.js';
 import { wasRendered } from './lib/tui.js';
 import { getCommandHandler } from './commands/index.js';
 import { LocalCheckupError } from './local/cloudflare-checkup/errors.js';
@@ -183,7 +183,7 @@ export async function runCli(options = {}) {
             if (parsed.values.isVersion && parsed.positionals.length)
                 throw new Error('Usage: vigilbase --version');
             if (parsed.positionals[0] === 'help' && parsed.positionals.length > 2)
-                throw new Error('Usage: vigilbase help [command]');
+                throw new Error(HELP_USAGE);
         }
         if (parsed.values.isVersion) {
             if (mode === 'json') {
@@ -243,7 +243,10 @@ export async function runCli(options = {}) {
         const publicClient = new VigilbaseClient(config);
         const handler = getCommandHandler(command);
         if (!handler) {
-            throw new Error(`Unknown command "${command}". Run \`vigilbase help\` for usage.`);
+            // Tools are not commands of their own (no aliases): point to how they run.
+            throw new Error(isCatalogTool(command)
+                ? `Unknown command "${command}". Run the tool with \`vigilbase run ${command} <target>\`.`
+                : `Unknown command "${command}". Run \`vigilbase help\` for usage.`);
         }
         return await handler({
             command,

package/dist/commands/account.js

@@ -18,7 +18,7 @@ export const handleAccount = async (ctx) => {
         else if (action === 'create' || action === 'add') {
             if (ctx.values.email !== undefined && ctx.rest[2] !== undefined)
                 throw new Error('Specify the invite email either positionally or with --email, not both.');
-            validateArguments(ctx, ctx.values.email === undefined ? 3 : 2, ['email', 'role', 'isConfirm']);
+            validateArguments(ctx, ctx.values.email === undefined ? 3 : 2, ['email', 'role', 'isConfirm'], 'vigilbase account invites create <email> --confirm');
             invitation = invitationSchema.parse({ email: ctx.values.email ?? ctx.rest[2], role: ctx.values.role });
             if (!ctx.values.isConfirm)
                 throw new Error('Sending an organization invitation requires --confirm.');

package/dist/commands/auth.js

@@ -218,7 +218,6 @@ export const handleWhoami = async (ctx) => {
     if (ctx.rest.length)
         throw new Error('Usage: vigilbase whoami');
     assertCommandFlags(ctx, []);
-    const credentials = await readCredentials(ctx.config);
     const legacyIdentityFileIgnored = await hasIgnoredIdentityCredentials(ctx.config);
     const accessToken = await getOneAccessToken(ctx.config);
     let liveUser = null;
@@ -242,6 +241,8 @@ export const handleWhoami = async (ctx) => {
         }
     }
     const signedIn = Boolean(liveUser);
+    // Read after the token and session calls: either may have refreshed the sign-in, which saves a new expiry and scope.
+    const credentials = await readCredentials(ctx.config);
     const payload = {
         authenticated: signedIn,
         oneBaseUrl: ctx.config.oneBaseUrl,

package/dist/commands/cloudflare.d.ts

@@ -1,3 +1,3 @@
 import { type CommandHandler } from './helpers.js';
-export declare const CLOUDFLARE_HELP = "Usage: vigilbase cf <command> [options]\nAlias: vigilbase cloudflare\n\nInventory and workspace:\n  zones                         List zones (default); --customer-id, --account-id, --zone-id\n  zone <zone-id>                Zone detail; --customer-id selects live details, optional --account-id\n  accounts                      List accessible accounts; --customer-id, --account-id\n  account <account-id>          Stored account detail; --customer-id\n  workspace [section]           Workspace bootstrap or section; --customer-id, --account-id, --zone-id\n    Sections: overview, reports, zones, rule-analyzer, accounts, checkups, settings\n\nZone reads (optional --customer-id; IDs can use --zone-id):\n  dns <zone-id>                 DNS records, TTL and proxy state\n  waf <zone-id>                 WAF rules, expressions, analytics and suggestions\n  speed-settings <zone-id>      Performance settings (internal users only)\n\nAccount reads (optional --customer-id; IDs can use --account-id):\n  audit-logs <account-id>       Latest provider audit events (up to 100; service-read permission)\n  zero-trust <account-id>       Users, Access applications, tunnels and authentication analytics\n  developer-platform <account-id>\n                                Workers, Workers analytics and Pages\n  magic-transit <account-id>    Prefixes, routes and traffic analytics\n    Zero Trust, Developer Platform and Magic Transit require deployment-read permission.\n\nAnalytics and checkups:\n  analytics --customer-id <uuid> [--account-id <id> | --zone-id <id>] [--days 1..30]\n    Default 7 days; live zone analytics uses the most recent 23 hours.\n  checkup [status]              Latest completed checkup; --customer-id, --account-id\n  checkup start                 Start and persist a scan; --customer-id, --account-id\n  checkup progress <run-uuid>   Read saved progress once\n  checkup result <run-uuid>     Read the stored Cloudflare checkup result\n    checkups aliases checkup; list/show alias status; run aliases start.\n\nCommon options: --json, --one-url <origin>, --timeout <milliseconds>, --help\nCustomer IDs are UUIDs; account and zone IDs are 32 hexadecimal characters.\nOne login, tenant bindings and permissions apply to every command.\nCheckup start creates a scan run. These commands do not edit provider configuration.\nSee CLOUDFLARE.md for full grammar, API mapping, data limits and examples.";
+export declare const CLOUDFLARE_HELP = "Usage: vigilbase cf <command> [options]\nAlias: vigilbase cloudflare\n\nInventory and workspace:\n  zones                         List zones (default); --customer-id, --account-id, --zone-id\n  zone <zone-id>                Zone detail; --customer-id selects live details, optional --account-id\n  accounts                      List accessible accounts; --customer-id, --account-id\n  account <account-id>          Stored account detail; --customer-id\n  workspace [section]           Workspace bootstrap or section; --customer-id, --account-id, --zone-id\n    Sections: overview, reports, zones, rule-analyzer, accounts, checkups, settings\n\nZone reads (--customer-id <uuid> required; IDs can use --zone-id):\n  dns <zone-id>                 DNS records, TTL and proxy state\n  waf <zone-id>                 WAF rules, expressions, analytics and suggestions\n  speed-settings <zone-id>      Performance settings (internal users only)\n\nAccount reads (optional --customer-id; IDs can use --account-id):\n  audit-logs <account-id>       Latest provider audit events (up to 100; service-read permission)\n  zero-trust <account-id>       Users, Access applications, tunnels and authentication analytics\n  developer-platform <account-id>\n                                Workers, Workers analytics and Pages\n  magic-transit <account-id>    Prefixes, routes and traffic analytics\n    Zero Trust, Developer Platform and Magic Transit require deployment-read permission.\n\nAnalytics and checkups:\n  analytics --customer-id <uuid> [--account-id <id> | --zone-id <id>] [--days 1..30]\n    Default 7 days; live zone analytics uses the most recent 23 hours.\n  checkup [status]              Latest completed checkup; --customer-id, --account-id\n  checkup start                 Start and persist a scan; --customer-id, --account-id\n  checkup progress <run-uuid>   Read saved progress once\n  checkup result <run-uuid>     Read the stored Cloudflare checkup result\n    checkups aliases checkup; list/show alias status; run aliases start.\n\nCommon options: --json, --one-url <origin>, --timeout <milliseconds>, --help\nCustomer IDs are UUIDs; account and zone IDs are 32 hexadecimal characters.\nOne login, tenant bindings and permissions apply to every command.\nCheckup start creates a scan run. These commands do not edit provider configuration.\nSee CLOUDFLARE.md for full grammar, API mapping, data limits and examples.";
 export declare const handleCloudflare: CommandHandler;

package/dist/commands/cloudflare.js

@@ -14,7 +14,7 @@ Inventory and workspace:
   workspace [section]           Workspace bootstrap or section; --customer-id, --account-id, --zone-id
     Sections: overview, reports, zones, rule-analyzer, accounts, checkups, settings
 
-Zone reads (optional --customer-id; IDs can use --zone-id):
+Zone reads (--customer-id <uuid> required; IDs can use --zone-id):
   dns <zone-id>                 DNS records, TTL and proxy state
   waf <zone-id>                 WAF rules, expressions, analytics and suggestions
   speed-settings <zone-id>      Performance settings (internal users only)
@@ -111,7 +111,7 @@ export const handleCloudflare = async (ctx) => {
             throw new Error('The positional account ID and --account-id must match.');
         accountId = args[0] ?? scope.accountId;
         if (!accountId)
-            throw new Error(`Usage: vigilbase cf ${subcommand} <account-id> [--customer-id …] [--json]`);
+            throw new Error(`Missing <account-id>. Usage: vigilbase cf ${subcommand} <account-id> [--customer-id <uuid>] [--json]`);
         validate(cloudflareScopeSchema, { accountId });
     }
     else if (['dns', 'waf', 'zone', 'speed-settings'].includes(subcommand)) {
@@ -121,9 +121,12 @@ export const handleCloudflare = async (ctx) => {
         zoneId = args[0] ?? scope.zoneId;
         // Preserve the historical `cf zone` alias for the zone inventory.
         if (subcommand !== 'zone' && !zoneId)
-            throw new Error(`Usage: vigilbase cf ${subcommand} <zone-id> [--customer-id …] [--json]`);
+            throw new Error(`Missing <zone-id>. Usage: vigilbase cf ${subcommand} <zone-id> --customer-id <uuid> [--json]`);
         if (zoneId)
             validate(cloudflareScopeSchema, { zoneId });
+        // One answers 400 to every caller that leaves the customer out of a zone read.
+        if (subcommand !== 'zone' && !scope.customerId)
+            throw new Error(`cf ${subcommand} requires --customer-id <uuid>. Find it with \`vigilbase cf accounts --json\`.`);
     }
     else if (!['workspace', 'checkup', 'checkups'].includes(subcommand)) {
         noExtraArgs(0);
@@ -144,6 +147,8 @@ export const handleCloudflare = async (ctx) => {
     if (subcommand === 'checkup' || subcommand === 'checkups') {
         if (['progress', 'result'].includes(action)) {
             noExtraArgs(2, checkupUsage);
+            if (args[1] === undefined)
+                throw new Error(`Missing <run-uuid>. Usage: vigilbase cf checkup ${action} <run-uuid> [--json]`);
             runId = validate(z.string().uuid('A checkup run UUID is required.'), args[1]);
             if (scope.customerId || scope.accountId)
                 throw new Error(`cf checkup ${action} is scoped by run ID and does not accept --customer-id or --account-id.`);

package/dist/commands/legacy-validation.d.ts

@@ -1,6 +1,12 @@
 import { z } from 'zod';
 import { type CommandContext } from './helpers.js';
-export declare function validateArguments(ctx: CommandContext, count: number, flags?: readonly string[]): void;
+/**
+ * Exactly `count` positional arguments. When some are missing, they are named from the trailing `<placeholders>`
+ * of `usage` (for example `vigilbase run <tool> <target>`), so `usage` lists only positional placeholders.
+ */
+export declare function validateArguments(ctx: CommandContext, count: number, flags?: readonly string[], usage?: string): void;
+/** "Missing <target>. Usage: vigilbase headers <url>", or a pointer to --help without a usage. */
+export declare function missingArguments(command: string, missingCount: number, usage?: string): string;
 export declare function limitValue(raw: string | undefined, fallback: number, max: number): number;
 export declare const invitationSchema: z.ZodObject<{
     email: z.ZodString;

package/dist/commands/legacy-validation.js

@@ -1,10 +1,23 @@
 import { z } from 'zod';
 import { assertCommandFlags } from './helpers.js';
-export function validateArguments(ctx, count, flags = []) {
-    if (ctx.rest.length !== count)
+/**
+ * Exactly `count` positional arguments. When some are missing, they are named from the trailing `<placeholders>`
+ * of `usage` (for example `vigilbase run <tool> <target>`), so `usage` lists only positional placeholders.
+ */
+export function validateArguments(ctx, count, flags = [], usage) {
+    if (ctx.rest.length < count)
+        throw new Error(missingArguments(ctx.command, count - ctx.rest.length, usage));
+    if (ctx.rest.length > count)
         throw new Error(`Unexpected arguments. Run \`vigilbase ${ctx.command} --help\` for usage.`);
     assertCommandFlags(ctx, flags);
 }
+/** "Missing <target>. Usage: vigilbase headers <url>", or a pointer to --help without a usage. */
+export function missingArguments(command, missingCount, usage) {
+    const missing = usage?.match(/<[^>]+>/g)?.slice(-missingCount) ?? [];
+    if (!usage || missing.length !== missingCount)
+        return `Missing arguments. Run \`vigilbase ${command} --help\` for usage.`;
+    return `Missing ${missing.join(' and ')}. Usage: ${usage}`;
+}
 export function limitValue(raw, fallback, max) {
     if (raw === undefined)
         return fallback;

package/dist/commands/local.js

@@ -134,7 +134,8 @@ function parse(schema, value) {
 function parseLocalOptions(ctx, subcommand, args) {
     const takesFile = subcommand === 'inspect' || subcommand === 'submit';
     if (takesFile ? args.length !== 1 : args.length !== 0) {
-        throw new Error(takesFile ? `Usage: vigilbase cloudflare-checkup ${subcommand} <file>` : usage);
+        const fileUsage = `Usage: vigilbase cloudflare-checkup ${subcommand} <file>`;
+        throw new Error(!takesFile ? usage : args.length === 0 ? `Missing <file>. ${fileUsage}` : fileUsage);
     }
     const values = ctx.values;
     const requested = parse(z.enum(['auto', 'profile', 'env', 'default'], { message: '--cf-auth must be auto, profile, env or default.' }), values['cf-auth'] ?? (subcommand === 'run' ? 'auto' : 'profile'));