@vigilbase/cli 0.2.0 → 0.2.2

package/CLOUDFLARE.md

@@ -1,8 +1,8 @@
 # Cloudflare CLI reference
 
-`vigilbase cf` and `vigilbase cloudflare` use the authenticated Vigilbase One API. Run `vigilbase login` first. Your organization, permissions, customer links, and allowed zones determine access. The CLI never requires a Cloudflare API key.
+`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` (also shown at https://vigilbase.com/tools/cloudflare-checkup?mode=local), verifies your work email with a code, installs cf if needed, signs in read-only, collects and uploads after you confirm (see [LOCAL.md](./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
@@ -109,6 +109,3 @@ Checkup progress reads once and does not poll automatically. Run the command aga
 
 Malformed IDs, conflicting selections, extra positional arguments and unsupported scope combinations fail before a network request. Authentication, permission, HTTP and explicit `success:false` API failures return a nonzero exit status. Provider configuration writes, token management, cache purge, account deletion and DNS edits are not exposed by this command group.
 
-## Verification
-
-`pnpm --filter @vigilbase/cli test` runs command contract tests, including tenant filters, exact paths, bearer authentication, rejected input, permission failures and terminal text handling. Cloudflare fixtures in `scripts/fixtures/cloudflare.mjs` cover every command and workspace section for the compiled CLI end-to-end harness. These fixtures execute against a local HTTP server; the checkup-start case never contacts production.

package/COMMANDS.md

@@ -2,76 +2,146 @@
 
 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 optional
-`--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](./CLOUDFLARE.md) |
-| Security | [SECURITY.md](./SECURITY.md) |
-| Customers, organizations, monitoring, support | [ONE.md](./ONE.md) |
-| Local Cloudflare Checkup (cf on your machine) | [LOCAL.md](./LOCAL.md) |
-| Authentication, setup, network troubleshooting | [README.md](./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 identify supported operations, filters, response/pagination
-behavior, API endpoints, and access requirements. They describe the CLI's
-supported API surface, not every internal endpoint in the monorepo.
+The references list the supported operations, filters, response and pagination
+behaviour, API endpoints and access requirements of the CLI.
 
 ## Global options
 
 | Flag | Meaning |
 | --- | --- |
-| `--json`, `-j` | JSON on stdout; progress/browser instructions on stderr |
+| `--json`, `-j` | JSON on stdout; progress and browser instructions on stderr |
 | `--help`, `-h` | Help for the named command; makes no API request |
-| `--version`, `-V` | Package version |
+| `--version`, `-V` | The installed version: the banner in a terminal, only the version number when stdout is a pipe or a file, `{"name":"@vigilbase/cli","version":"…"}` with `--json` |
 | `--one-url <origin>` | One origin; default `https://one.vigilbase.com` |
-| `--auth-url <origin>` | Explicit registered issuer or loopback development issuer; One discovery chooses the active provider |
+| `--auth-url <origin>` | The Identity issuer to trust; default `https://auth.vigilbase.com`. Staging (`https://identity-staging.vigilbase.com`) or a loopback issuer is trusted only when set here or in `VIGILBASE_AUTH_URL` |
 | `--base-url <origin>` | Public origin; default `https://vigilbase.com` |
 | `--timeout <ms>` | Per-request timeout, integer 1–2147483647; default 60000 |
 | `--client-id <id>` | Device authorization client; default `vigilbase-cli` |
 
-Origins must be HTTP(S) URLs without credentials, paths, query strings, or
-fragments. One requires HTTPS, except HTTP loopback development. `--customer-id` is a command-specific One customer UUID; it does not
-change the session's permissions. API-backed reads may still return 403 when the
-signed-in role lacks access. Unknown flags, unsupported command-specific flags
-(including scope flags), and extra positional arguments fail before API access.
-`--style` applies only to `badge`.
+Origins must be HTTP(S) URLs without credentials, paths, query strings or
+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), 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
 
-| Command | Options and behavior | One API |
+Paths on One are relative to `--one-url`; Identity endpoints come from the
+issuer's `/.well-known/openid-configuration` (for production,
+`https://auth.vigilbase.com/api/auth/…`).
+
+| Command | Options and behaviour | Requests |
 | --- | --- | --- |
-| `login` | Device authorization; `--no-open` for remote terminals | One protected-resource discovery; legacy device endpoints or Identity device code + form token exchange |
-| `login --token-stdin` | Validate and save a token piped from a secret manager; input is bounded and never echoed | GET `/api/auth/get-session` |
-| `login --token <bearer>` | Legacy input; discouraged because arguments can appear in process lists/history. `VIGILBASE_ONE_TOKEN` is also supported; neither combines with `--token-stdin` | GET `/api/auth/get-session` |
-| `whoami` | Verify the saved session; signed-out is a successful status query | Legacy session or Identity userinfo when a usable grant exists |
-| `logout` | Revoke Identity refresh grant, then remove local credentials; legacy logout stays local | Identity revocation, when using v2 credentials |
-| `doctor` | Independently check public catalog and One session connectivity | GET `/api/agent/tools`, GET `/api/auth/get-session` |
-
-Tokens are saved atomically with owner-only file permissions and tied to their
-issuing One origin and, for Identity grants, issuer/client/resource. Rotating
-refresh tokens are coordinated across CLI processes. See README for config directory overrides and certificate
-trust. Login polling handles pending approval, denial, expiry, and transient
-transport failures. Access tokens are never included in successful CLI output.
+| `login` | Device sign-in; `--no-open` for remote terminals. Signing in again with Identity first revokes and removes the sign-in it replaces (before the new device code), unless that one's last refresh had an uncertain result | One `GET /.well-known/oauth-protected-resource`. Identity: discovery, `POST /api/auth/device/code`, polling the token endpoint, then userinfo; you approve at `https://auth.vigilbase.com/device`. Legacy: One `POST /api/auth/device/code`, `POST /api/auth/device/token`, `GET /api/auth/get-session`; you approve at One's `/device` |
+| `login --token-stdin` | Check and save a token piped from a secret manager; the input is bounded and never echoed. A saved Identity sign-in is revoked and removed before the token is saved | One `GET /api/auth/get-session`; Identity revocation when a sign-in is saved |
+| `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/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
+sessions, shared with CLI 0.1.x), and are tied to the One origin and, for
+Identity, the issuer, client and One resource they were issued for. Rotating
+refresh tokens are coordinated across CLI processes by `credentials.json.lock`.
+Login polling handles pending approval, denial, expiry and short network
+failures. Access tokens never appear in CLI output. Signing in isn't supported
+on Windows yet. The README covers the files, CLI 0.1.x/0.2.0 compatibility,
+logout, directory checks and the config directory.
+
+`doctor` JSON has `checks.publicApi`, `checks.one` and `checks.signIn`, each
+`{ok, url?, error?, status?, code?}`. `checks.one.url` is the endpoint it
+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 authenticated scanner names | GET `/api/agent/tools` |
-| `run <tool> <target>` | `--via public\|one`; `--public` forces the public API | POST `/api/agent/tools/<tool>/execute` 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 |
-| `skill <tool>` | Prints the complete published skill; JSON includes URL/content | Catalog plus the tool's skill URL |
-| `badge <domain>` | `--style default\|compact\|mini` | Generates a public badge URL locally |
+| `skill <tool>` | Prints the complete published skill; JSON includes URL and content | Catalog plus the tool's skill URL |
+| `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`. 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.
+Without one they stop with this error:
+
+```
+Error: This tool needs a Vigilbase One sign-in: run `vigilbase login`.
+```
+
+Other sign-in errors keep their own message, with that sentence as the hint
+unless the message already says to run `vigilbase login`.
 
-Public tools: `security-headers`, `email-security`. Login-required tools:
-`website-security`, `react2shell`, `fortibleed-check`. Public scans stay on the
-public API unless explicitly routed to One. A saved login alone does not change
-that choice. `--public` and `--via one` cannot be combined.
+`list` reads your saved sign-in from disk only (no refresh, no network, no wait
+for the lock). In JSON, `authenticated` says whether it looks usable and
+`oneExecutableTools` follows it. If it can't be used, `list` still prints the
+catalog, shows you as signed out and prints one stderr line per run:
+``Couldn't use your saved sign-in (<reason>); running anonymously. Run `vigilbase login` to fix.``
+For an unsafe config path or credentials file, which `login` would refuse too,
+the line ends with the fix instead, for example
+``Couldn't use your saved sign-in (/tmp is a symbolic link); running anonymously. Set VIGILBASE_CONFIG_DIR to a private directory without symbolic links in its path.``
+`list` and `doctor` ignore a config path that fails the checks when no
+credentials file is there.
+
+When a public scan fails and vigilbase.com explains why with a known error
+code, the CLI prints `Error: <message> (<code>)` (JSON: `error`, `code`,
+`status`), with the message cleaned to one line of at most 300 characters.
+Otherwise it prints `Request failed (HTTP <status>).`
 
 ## Account and billing
 
@@ -84,21 +154,22 @@ that choice. `--public` and `--via one` cannot be combined.
 | `account sessions` | `session` | GET `/api/account/sessions` |
 | `account invites` | `invitations`; optional `list` or `ls` | GET `/api/auth/orgs/invitations` |
 | `account invites create` | `add` alias; `--email <email>`, `--role <role>` (default member), required `--confirm` | POST `/api/auth/orgs/invite` |
-| `account billing` | Delegates to billing commands | Same as billing |
+| `account billing` | Same as the billing commands | Same as billing |
 | `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` |
 
-Invitation creation sends an invitation; billing portal creation starts a Stripe
-portal session. These are explicit actions. Billing data comes from One's Stripe
-integration; the CLI does not persist invoices or payment information locally.
+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.
 
-Invitations validate the email and role locally and generate a fresh UUID
-`operationId` for each invocation. Accepted roles: `admin`, `member`, `readonly`,
+Invitations check the email and role locally and send a fresh UUID
+`operationId` each time. Accepted roles: `admin`, `member`, `readonly`,
 `partner_owner`, `partner_sales`, `partner_operations`, `partner_finance`,
-`partner_readonly`, `billing_only`, and `sales_only`. The API still checks whether
-the caller may assign the chosen role. `--confirm` is required.
-Portal URLs are validated against the HTTPS Stripe billing host before JSON
-output, printing, or opening; Windows requires manual opening.
+`partner_readonly`, `billing_only` and `sales_only`. One still checks whether
+you may assign the role. `--confirm` is required. Portal URLs must be HTTPS on
+Stripe's billing host before they are printed, opened or put in JSON.
 
 ## Run history and account Watchdog
 
@@ -106,79 +177,89 @@ output, printing, or opening; Windows requires manual opening.
 | --- | --- | --- |
 | `runs` | `list`, `ls`; `--tool <name>`, `--limit <n>` (1–200, default 50) | GET `/api/tool-runs` |
 | `runs get <id>` | `show <id>` or `runs <UUID>` | GET `/api/tool-runs/<id>` |
-| `runhistory` | Alias of the entire `runs` group | Same as runs |
+| `runhistory` | Alias of the whole `runs` group | Same as runs |
 | `watchdog` | `list`, `targets`, `status` | GET `/api/account/watchdog/targets` |
 | `watchdog scans` | `scan`; `--target-id <UUID>`, `--limit <n>` (1–100, default 20) | GET `/api/account/watchdog/scans` |
 
-Customer-specific Watchdog and monitoring views are documented in ONE.md.
+Customer-specific Watchdog and monitoring views are in ONE.md.
 
-## Local Cloudflare Checkup (no login)
+## Local Cloudflare Checkup (no sign-in)
+
+All vigilbase.com paths below are under
+`https://vigilbase.com/api/v1/tools/cloudflare-checkup/local-session`.
 
 | Command | Options | Requests |
 | --- | --- | --- |
-| `cloudflare-checkup` (≡ `local cloudflare-checkup [run]`) | `--email`, `--account-id`, `--out`, `--overwrite`, `--yes`, `--confirm`, `--no-open`, `--cf-auth auto\|profile\|env\|default` (default `auto`), `--profile`, `--cf-bin`, `--max-requests-per-5min`, `--base-url` (vigilbase.com or loopback), `--timeout` | POST `/api/v1/tools/cloudflare-checkup/local-session/request` and `…/verify` (email verification), GET `…/local-session` (before cf runs and again before the upload), allowlisted read-only cf commands, POST `…/local-session/snapshot` after an explicit confirmation; npm only to install the pinned cf when none is usable (asks first) |
+| `cloudflare-checkup` (≡ `local cloudflare-checkup [run]`) | `--email`, `--account-id`, `--out`, `--overwrite`, `--yes`, `--confirm`, `--no-open`, `--cf-auth auto\|profile\|env\|default` (default `auto`), `--profile`, `--cf-bin`, `--max-requests-per-5min`, `--base-url` (vigilbase.com or loopback), `--timeout` | In order: GET `…/availability` (before the email is asked for), POST `…/request` and `…/verify` (email verification), GET `…/local-session` (before cf runs), allowlisted read-only cf commands, GET `…/local-session` again and POST `…/local-session/snapshot` after you confirm. npm only to install the pinned cf when none is usable (asks first) |
 | `cloudflare-checkup login` | `--profile`, `--no-open`, `--dry-run`, `--cf-bin` | Runs `cf auth create <profile> --scopes …` interactively |
 | `cloudflare-checkup doctor` | `--cf-auth`, `--profile`, `--cf-bin` | Offline cf mapping check, one `cf auth whoami` |
 | `cloudflare-checkup accounts` | `--cf-auth`, `--profile`, `--cf-bin` | `cf accounts list` (all pages) |
 | `cloudflare-checkup collect` | `--out` (required), `--account-id`, `--overwrite`, `--dry-run`, `--max-requests-per-5min`, cf options | Allowlisted read-only cf commands; writes the snapshot |
 | `cloudflare-checkup inspect <file>` | — | None |
-| `cloudflare-checkup submit <file>` | `--email`, `--yes`/`--confirm`, `--no-open`, `--base-url`, `--timeout` | POST `…/local-session/request` and `…/verify`, GET `…/local-session`, POST `…/local-session/snapshot` |
+| `cloudflare-checkup submit <file>` | `--email`, `--yes`/`--confirm`, `--no-open`, `--base-url`, `--timeout` | After checking the file: GET `…/availability`, POST `…/request` and `…/verify`, GET `…/local-session`, POST `…/local-session/snapshot` |
 | `cloudflare-checkup logout` | `--profile`, `--cf-bin` | Runs `cf auth delete <profile>` interactively, then removes the cf Vigilbase installed |
 
-Each subcommand also works as `local cloudflare-checkup <subcommand>`. The one
-command and `submit` verify your work email first: the CLI asks for it (or
-takes `--email`), vigilbase.com emails a 6-digit code, and the CLI asks for the
-code (without a terminal, both are read from stdin, one line each; add
-`--yes`). In a terminal both show an interactive timeline on stderr (inputs,
-arrow-key questions, spinners, a collection progress bar); pipes, CI,
-`TERM=dumb` and `--json` keep the plain lines and prompts. Ctrl-C exits 130. The address, the code and the session code are never echoed, logged,
-stored or passed to cf or npm. cf output and stderr are never echoed; failures
-carry a stable `code` and `hint` that point at running the same command again.
-See [LOCAL.md](./LOCAL.md) for the email verification, the managed cf install,
-the allowlist, environment policy, uploaded data and error codes.
-
-## Output, effects, and testing
-
-Exit codes: **0** success, **1** validation/API/network failure, **2** HTTP 429
-rate limiting. A completed scan whose result is unsuccessful also exits 1.
-`whoami` being signed out is not an API failure. A healthy `doctor` does not
-require login. API error JSON retains status, code, and retry delay when available.
-
-New security/customer operations preserve JSON response envelopes and pagination
-fields. Cloudflare inventory commands may apply the explicitly requested account
-or zone filter locally as well as sending it to One; zone detail returns the
-selected object. See each reference for details. Text output is for people; use
-JSON for automation and evidence export.
-
-Provider credentials, signed delegation claims, internal bearer tokens, and
-organization-authority overrides are never CLI inputs. New commands use named
-One routes. Exceptions: local provider reads and the two named vigilbase.com
-local-session routes. `vigilbase cloudflare-checkup` runs Cloudflare's own
-`cf` CLI on your machine with a fixed allowlist of read-only commands; cf owns
-your Cloudflare login, and the Vigilbase CLI never reads, prints, stores or
-uploads it. Its only Vigilbase requests are `GET /api/v1/tools/cloudflare-checkup/local-session`
-and, after you confirm, `POST /api/v1/tools/cloudflare-checkup/local-session/snapshot`
-with the exact snapshot file, authorised by the code the page minted for your
-verified email (see [LOCAL.md](./LOCAL.md)). Webhooks, cron/admin repair endpoints, interactive OAuth handoffs,
-streaming/binary downloads, and endpoints that auto-provision on GET are outside
-this expansion. Remediation effects requiring durable approval/receipt workflows
-remain in their existing supported One/Vigil flows.
-
-```bash
-pnpm --filter @vigilbase/cli check
-# Includes typecheck, unit tests, production build, login lifecycle smoke,
-# every fixture-listed command over HTTP in both JSON and text modes, and the
-# local checkup smoke (fake cf on a restricted PATH, a fake npm for the managed
-# cf install, loopback local-session routes).
-
-VIGILBASE_BASE_URL=https://vigilbase.com \
-  VIGILBASE_SMOKE_ARTIFACTS="$PWD/.context/cli-live-smoke" \
-  pnpm --filter @vigilbase/cli smoke:e2e
-```
+Each subcommand also works as `local cloudflare-checkup <subcommand>`.
+
+The one command and `submit` first ask vigilbase.com whether local checkups are
+available (no email, no credentials). When they are switched off, the command
+stops before asking for your email with
+`Local checkups aren't available right now.` and the hint
+`Run the Cloudflare Checkup in your browser instead: https://vigilbase.com/tools/cloudflare-checkup`
+(`LOCAL_MODE_DISABLED`). When vigilbase.com needs a newer CLI, it stops with
+`CLI_UPGRADE_REQUIRED`, also before any email. If vigilbase.com doesn't answer
+the check, the command goes on.
+
+Then they verify your work email: the CLI asks for it (or takes `--email`),
+vigilbase.com emails a 6-digit code, and the CLI asks for the code (without a
+terminal, both are read from stdin, one line each; add `--yes`). In a terminal
+both show an interactive timeline on stderr (inputs, arrow-key questions,
+spinners, a collection progress bar); pipes, CI, `TERM=dumb` and `--json` keep
+plain lines and prompts. Ctrl-C exits 130. The address, the code and the
+session code are never echoed, logged, stored or passed to cf or npm. cf output
+and stderr are never echoed; failures carry a stable `code` and a `hint` that
+usually says to run the same command again. See LOCAL.md for the email
+verification, the managed cf install, the allowlist, the environment policy,
+the uploaded data and the error codes.
+
+## Output and effects
+
+Exit codes: **0** success, **1** validation, API, network or sign-in failure,
+**2** HTTP 429 rate limiting. A completed scan whose result is unsuccessful
+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
+selected object. Text output is for people; use JSON for automation and
+evidence export.
 
-The command suite uses temporary local HTTP fixtures and credentials; all writes
-stay local. It checks exact methods/paths/filters/bodies, bearer handling, output,
-permission failures, rate limits, malformed responses, and documentation presence.
-The live smoke separately checks public services and actual public scans. Real
-customer-data access additionally requires a valid One session and suitable role;
-local fixtures do not prove production provider configuration or data health.
+Provider credentials, signed delegation claims, internal bearer tokens and
+organization overrides are never CLI inputs. Commands use named One routes,
+with two exceptions. Local provider reads: `vigilbase cloudflare-checkup` runs
+Cloudflare's own `cf` CLI on your machine with a fixed allowlist of read-only
+commands; cf owns your Cloudflare login, and the Vigilbase CLI never reads,
+prints, stores or uploads it. And the vigilbase.com local-session routes, which
+are the checkup's only Vigilbase requests: GET `…/availability`, POST
+`…/request` and POST `…/verify` without a credential, then GET `…/local-session`
+and, after you confirm, POST `…/local-session/snapshot` with the exact snapshot
+file, both authorized by the session code the email verification returned (see
+LOCAL.md). Webhooks, cron and admin repair endpoints, interactive OAuth
+handoffs, streaming or binary downloads, and endpoints that create records on
+GET are not exposed. Remediation that needs durable approval and receipts stays
+in its existing One and Vigil flows.