@vigilbase/cli 0.1.4 → 0.2.1

package/LOCAL.md

@@ -0,0 +1,721 @@
+# Local Cloudflare Checkup reference
+
+`vigilbase cloudflare-checkup` runs the Vigilbase Cloudflare Checkup in local
+mode: it collects your Cloudflare configuration **on your own machine** with
+Cloudflare's own CLI, `cf`, writes a minimised snapshot you can inspect, and
+uploads exactly that file to vigilbase.com after you confirm. vigilbase.com
+evaluates it with the same scanner as the checkup in your browser, which uses a
+read-only Cloudflare API token instead. Results are labelled **self-reported**;
+they go to your verified work email, and the results page opens in your
+browser.
+
+Local mode is available while vigilbase.com has it switched on. The CLI checks
+before it asks for your email; when local mode is off it stops with
+`Local checkups aren't available right now.` and points you to the checkup in
+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));
+`vigilbase cloudflare-checkup` runs on your machine and needs no Vigilbase
+login.
+
+## Quick start: one command
+
+Run this in a terminal (while local mode is on, the checkup page at
+<https://vigilbase.com/tools/cloudflare-checkup> shows the same command):
+
+```bash
+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`.
+
+The command does everything, in this order, and stops at the first problem
+before any slower step:
+
+1. Checks Node.js (22.18 or newer; macOS, Linux or Windows x64).
+2. Asks vigilbase.com whether local checkups are available and accept this CLI
+   version (nothing about you is sent). If not, it stops here, before asking
+   for your email.
+3. Asks for your work email (`Work email for your results:`), and
+   vigilbase.com emails you a 6-digit code. You enter it at
+   `Code from the email:` (`123456`, `123 456` and `123-456` all work), and
+   the CLI prints `✓ Verified j***@acme.com`.
+4. Finds Cloudflare's `cf`. If none is usable (including a newer cf that
+   renamed a command the checkup needs), it offers to install the tested
+   release for Vigilbase (asks first; `--yes` answers for you). Your own cf is
+   left alone.
+5. Signs in to Cloudflare with a **read-only** cf login (your browser opens) if
+   the cf profile `vigilbase-checkup` is missing or expired. With
+   `CLOUDFLARE_API_TOKEN` set in the shell, cf uses that token instead and the
+   browser sign-in is not offered: unset the variable, or add
+   `--cf-auth profile`, to sign in with your browser.
+6. Lets you choose the account (one account is used as is; several get a
+   list to choose from).
+7. Collects with read-only cf commands, at most 900 requests per 5 minutes.
+8. Saves the snapshot to `~/.config/vigilbase/checkups/…` (mode 0600) and
+   shows what it contains.
+9. Asks `Results go to j***@acme.com. Upload 182 KB to https://vigilbase.com? [y/N]`
+   and uploads exactly that file only after an explicit `y`.
+10. Prints the results link and opens it in your browser.
+
+In a terminal, the steps show as an interactive timeline (see
+[Terminal UI and plain output](#terminal-ui-and-plain-output)):
+
+```
+$ npx @vigilbase/cli cloudflare-checkup
+◆  Vigilbase Cloudflare Checkup
+│
+◇  Work email › j***@acme.com
+◇  Code sent to j***@acme.com › ●●●●●●  ✓ verified
+│
+◇  cf is not installed. Install it for Vigilbase? › Yes
+◇  Installed cf 1.0.0-beta.13
+◇  Cloudflare sign-in  ✓ read-only profile "vigilbase-checkup"
+◇  Account  Acme Corp  0123…cdef
+│
+◇  610 reads · 580 ok · 30 not collectable
+│  Saved ~/.config/vigilbase/checkups/cloudflare-checkup-0123cdef-20261009T101233Z.json (182 KB) · 12 zones · no credentials
+│  Contains 14 member emails · 22 DNS names · 5 pseudonymised IPs
+│  Inspect it:
+   npx @vigilbase/cli cloudflare-checkup inspect ~/.config/vigilbase/checkups/cloudflare-checkup-0123cdef-20261009T101233Z.json
+│
+◇  Upload 182 KB to vigilbase.com? › Yes
+│
+└  ✓ Done. 31 passed · 6 warnings · 4 failed · 30 reads not collected locally
+   Results: https://vigilbase.com/tools/run/0b7f3c1e-1d2a-4c55-9e1a-8d3f2b6c9a10 (opening in your browser)
+   A link has also been emailed to j***@acme.com.
+   Remove the read-only Cloudflare login and the cf Vigilbase installed later with:
+   npx @vigilbase/cli cloudflare-checkup logout
+```
+
+In pipes, scripts and CI (and with `TERM=dumb` or `--json`) the same run prints
+plain lines:
+
+```
+$ npx @vigilbase/cli cloudflare-checkup
+Vigilbase Cloudflare Checkup · collects on this machine with Cloudflare's cf CLI
+Work email for your results: jane@acme.com
+We emailed a 6-digit code to j***@acme.com (valid until 10:42). Check spam if it doesn't arrive.
+Code from the email: 482913
+✓ Verified j***@acme.com
+Cloudflare's cf CLI (cf@1.0.0-beta.13, about 75 MB) is not installed. Install it for Vigilbase now? [Y/n]
+✓ Installed cf 1.0.0-beta.13
+Signing in to Cloudflare with a read-only login. Your browser will open…
+✓ Signed in · cf profile "vigilbase-checkup" · read-only · expires 11:02
+cf can read 2 Cloudflare accounts:
+  1) Acme Corp   0123…cdef
+  2) Acme Labs   4567…89ab
+Account number (1-2): 1
+Account 0123…cdef · 12 zones · ~420 cf requests at ≤900 per 5 min (~3 min)
+✓ Saved ~/.config/vigilbase/checkups/cloudflare-checkup-0123cdef-20261009T101233Z.json (182 KB)
+  12 zones · 610 reads (580 ok, 30 not collectable with cf) · 14 member emails · 22 DNS names · 5 pseudonymised IPs
+  No credentials. Inspect it: npx @vigilbase/cli cloudflare-checkup inspect /home/jane/.config/vigilbase/checkups/cloudflare-checkup-0123cdef-20261009T101233Z.json
+Results go to j***@acme.com. Upload 182 KB to https://vigilbase.com? [y/N] y
+✓ Uploaded. Free summary: 31 passed · 6 warnings · 4 failed · 30 reads not collected locally
+Results: https://vigilbase.com/tools/run/0b7f3c1e-1d2a-4c55-9e1a-8d3f2b6c9a10
+A link has also been emailed to j***@acme.com.
+Remove the read-only Cloudflare login and the cf Vigilbase installed later with: npx @vigilbase/cli cloudflare-checkup logout
+```
+
+On Windows the saved path is printed in full (cmd and PowerShell do not expand
+`~`), so it can be passed to `submit` as shown.
+
+If something fails, fix it and **run the same command again**; each run
+verifies your email and starts a new checkup. When you are done:
+
+```bash
+npx @vigilbase/cli cloudflare-checkup logout   # deletes the cf profile and the cf Vigilbase installed
+```
+
+`vigilbase cloudflare-checkup` (top-level), `vigilbase local cloudflare-checkup`
+and `vigilbase local cloudflare-checkup run` are the same command.
+
+### Options
+
+| Option | Meaning |
+| --- | --- |
+| `--email <address>` | Your work email; without it, the CLI asks for it. |
+| `--account-id <id>` | Skip the account picker (32 hex characters). |
+| `--out <file>` | Write the snapshot here instead of the default path; `--overwrite` replaces an existing file. |
+| `--yes` | Answer yes to installing cf and to the upload question. |
+| `--confirm` | Answer yes to the upload question only (kept from earlier releases). |
+| `--no-open` | Print the results link without opening a browser. |
+| `--cf-auth auto\|profile\|env\|default` | `auto` (default): `env` when `CLOUDFLARE_API_TOKEN` is set in this shell, otherwise `profile` (an explicit `--profile` also means `profile`). |
+| `--profile <name>` | The cf profile (default `vigilbase-checkup`; letters, digits, `_` and `-`, not starting with `-`). |
+| `--cf-bin <path>` | Absolute path to the cf package directory or its `bin/cf`; never replaced by an install. |
+| `--max-requests-per-5min <100..1100>` | Cloudflare request budget (default 900). |
+| `--base-url <origin>` | Only `https://vigilbase.com` or a loopback origin (local testing). |
+| `--timeout <ms>` | Timeout for each vigilbase.com request. |
+| `--json` | One JSON object on stdout; status lines and prompts go to stderr. |
+
+Before anything slow, the command checks every flag (no I/O, and `--email`
+only for its shape), that its questions can be answered (on a terminal, or
+with `--yes` without one; `--confirm` answers only the upload question, not
+installing cf), then Node, then that `--out` is writable, then that
+vigilbase.com has local checkups on and accepts this CLI. So no code is emailed
+for a run that could not install cf, confirm the upload or be accepted. It
+verifies your email before cf runs, and checks that the snapshot location is
+writable before collecting, so a long collection is never wasted.
+
+Two problems can show only once cf runs, after the email was verified: without
+a terminal, a missing cf login (`CF_AUTH_REQUIRED`) and several accounts
+without `--account-id` (`ACCOUNT_SELECTION_REQUIRED`). Running the command
+again with the same address then waits for vigilbase.com's 8 minutes per
+address (the hint says so). In scripts, sign in first (run
+`npx @vigilbase/cli cloudflare-checkup login` in a terminal, or set
+`CLOUDFLARE_API_TOKEN`) and pass `--account-id`.
+
+**Without a terminal** (scripts, CI), add `--yes`. The prompts still go to
+stderr, and the answers are read from stdin, one line each: the address
+(unless `--email` is given) and then the code. Each prompt reads exactly one
+line and leaves the rest for the next one, so a script can write the code once
+it sees `Code from the email:` (an `expect`-style script), or pipe both lines
+when it already knows them. The account picker and the cf install question are
+never answered from stdin: use `--account-id` and `--yes`.
+
+## Terminal UI and plain output
+
+In a terminal, the one command and `submit` show their steps as a timeline on
+stderr (◆ the current step, ◇ a finished one, │ notes, ▲ a warning, ■ the error
+that stopped the run, └ the result). Spinners run while the CLI checks that
+local checkups are available, while vigilbase.com sends or checks the code,
+while the session is checked, while cf is found, checked and installed, and
+while the upload is scored; a progress bar runs while
+collecting (zones done, cf reads done of the estimate, and the time left, from
+the request budget and the pace so far). Everything is redrawn in place and fits
+the terminal width, also after a resize.
+
+| Question | Keys |
+| --- | --- |
+| Work email | Type it; Backspace, Ctrl-U (clear) and Ctrl-W (last word) edit; Enter sends it. |
+| Code from the email | Type or paste the 6 digits (spaces and dashes are skipped); it is sent at the sixth digit. |
+| Account | ↑/↓ (or j/k), Home/End, Enter. Every account cf can read is listed. |
+| Install cf, upload | ←/→ choose, Enter answers, `y` or `n` answer at once. The install question starts on **Yes**; the upload question starts on **No**, so Enter alone never uploads. |
+
+- Once sent, the typed address is replaced by the masked address vigilbase.com
+  returns, and the code by `●●●●●●`.
+- A refused address and a wrong code are asked for again in place, with the
+  reason. When vigilbase.com rate-limits the code request, the refusal does not
+  say which limit was reached (per address: one checkup every 8 minutes and 3
+  codes an hour, `+tag` variants included; per domain: 30 codes an hour; per
+  network; overall). The CLI says so, shows when to try
+  again (from the response) and asks `Use a different work email?`, which
+  starts on **No** (not asked with `--email`).
+- Commands to copy (`inspect`, `submit <saved file>`, `logout`) are printed on
+  lines of their own, indented and never wrapped or cut, with the path quoted
+  for the shell (a leading `~/` stays outside the quotes).
+- On a narrow terminal, account names in the picker are cut in the middle so
+  each masked account ID stays visible, and an input's title is cut before
+  what you type.
+- If the Cloudflare sign-in fails or is cancelled, it asks `Try signing in
+  again?`, up to twice more. While cf signs in, the terminal belongs to cf, so
+  its own messages appear between the steps.
+- The results link is underlined, and clickable (an OSC 8 link) in terminals
+  known to support it (`FORCE_HYPERLINK=0` turns that off, `1` turns it on).
+  When stdout is not a terminal (`> results.txt`), the plain result lines go to
+  stdout as well.
+- Ctrl-C at any point gives the terminal back (raw mode off, cursor shown),
+  says what happened (for example `Cancelled. Nothing was uploaded.`) and
+  exits 130. Errors and SIGTERM give the terminal back too.
+
+The plain output (the second transcript in the quick start: the
+`Work email for your results:`, `Code from the email:` and
+`Account number (1-2):` prompts, the `[Y/n]` and `[y/N]` questions, a one-line
+spinner) is used when any of these holds:
+
+- stdin or stderr is not a terminal (pipes, a redirected stderr, scripts);
+- `TERM=dumb`;
+- `CI` is set (to anything but `0` or `false`);
+- `--json`.
+
+`NO_COLOR` (any non-empty value) or `FORCE_COLOR=0` keeps the timeline without
+colours or text styles. Legacy Windows consoles (no Windows Terminal and no
+`TERM_PROGRAM`) and the Linux console get ASCII only: the symbols (`*`, `o`,
+`|`, `+`, `!`, `x`), `...` for `…` (also in masked IDs, `0123...cdef`) and `-`
+between the items of a summary line, in every step, spinner and message.
+
+## Email verification and the checkup session
+
+The CLI verifies your email itself; there is no browser step and no bot check
+on this path.
+
+- **Availability first.** Before asking for your email, the one command and
+  `submit` send `GET …/local-session/availability`, with no email, no
+  credentials and no body. If local checkups are switched off, the command
+  stops with `LOCAL_MODE_DISABLED`: `Local checkups aren't available right now.`
+  and the hint
+  `Run the Cloudflare Checkup in your browser instead: https://vigilbase.com/tools/cloudflare-checkup`.
+  Nothing is emailed and cf is not touched. If vigilbase.com needs a newer CLI
+  or doesn't accept this snapshot format, it stops with `CLI_UPGRADE_REQUIRED`.
+  If vigilbase.com doesn't answer the check (for example a network error or a
+  timeout, after 10 seconds or `--timeout`), the command goes on, and the same
+  checks happen when the checkup starts.
+- **What vigilbase.com receives.** Your email address goes to vigilbase.com
+  (`POST …/local-session/request`) so it can send you the code, together with
+  the email language (`en`, `pt-PT` or `ar`, from `LC_ALL`, `LC_MESSAGES` or
+  `LANG`). The code goes back with the verification token
+  (`POST …/local-session/verify`). Only business addresses are accepted;
+  personal and disposable ones are refused (`EMAIL_INVALID`; the CLI asks for
+  another address, up to 3, or stops at once with `--email`).
+- **Codes.** A wrong code is asked for again, up to 5 tries in total (after 5
+  wrong codes vigilbase.com closes the checkup: `VERIFICATION_EXPIRED`). An
+  expired code stops with `VERIFICATION_EXPIRED`; run the command again for a
+  new one. A code check that vigilbase.com does not answer (a network error, a
+  timeout or a 503) is sent once more after 2 seconds with the same code; on a
+  terminal the CLI then asks for the same code again (twice at most), which
+  does not use one of the 5 tries. Otherwise it stops with `SUBMIT_FAILED`.
+  vigilbase.com limits code requests per mailbox (3 an hour; `jane+x@` counts
+  as `jane@`), per domain (30 an hour), per IP address (an IPv6 /64 counts as
+  one) and overall; a limit stops with `VIGILBASE_RATE_LIMITED` and the time
+  to wait (exit 2).
+- **The session.** The verification answers with a session code for this one
+  checkup. It lives only in the CLI's memory and is sent only as the
+  `Authorization` header of `GET …/local-session` and
+  `POST …/local-session/snapshot`. If it expires while you collect (a large
+  account) or while the upload question waits, the CLI renews it once with
+  the token and code it still holds (`✓ Renewed the checkup session, which had
+  expired`); vigilbase.com then issues the next session code for the same
+  checkup. If the code can no longer renew it, the command stops with
+  `SESSION_EXPIRED` and names `submit <saved file>` to upload the saved
+  snapshot without collecting again.
+- **Never shown or stored.** The CLI never prints, logs, writes to disk, puts in
+  JSON output or a URL, or passes to cf or npm your address, the code, the
+  verification token or the session code. It shows only the masked address
+  vigilbase.com returns (`j***@acme.com`). A checkup accepts one snapshot; its
+  results go to the verified address.
+
+Outside the CLI's control: with `--email`, the address is part of the command
+line, so it is in your shell history and in npm's debug log when run through
+npx (`~/.npm/_logs`); omit `--email` and type it at the prompt to avoid that.
+(Any environment variable naming `--email`, a session code or a token is
+removed from npm's environment when the CLI installs cf.)
+
+## Trust model
+
+- **cf owns your Cloudflare login.** The Vigilbase CLI never reads, prints,
+  stores or uploads a Cloudflare credential. It runs `cf` as a separate process
+  (`node <cf entry> …`, no shell) and reads only cf's JSON output.
+- **`CLOUDFLARE_API_TOKEN`** (`--cf-auth env`, or `auto` when it is set): cf
+  reads it itself. The vigilbase process holds the variable only as part of its
+  own environment and copies it by name to cf's API reads. It never prints,
+  stores, inspects or uploads it.
+- **The only Vigilbase requests** go to
+  `https://vigilbase.com/api/v1/tools/cloudflare-checkup/local-session`:
+  `GET …/availability` (no body, no credential), `POST …/request` and
+  `POST …/verify` (the email verification, JSON bodies, no credential), then
+  `GET` of the session and `POST …/snapshot`, authorised by the session code
+  the verification returned. The upload is the exact bytes
+  of the file you can inspect; the CLI re-reads and re-hashes it and checks the
+  server's echoed SHA-256.
+- **Installing cf** contacts only the npm registry your npm is configured for,
+  with a pinned version and integrity (see below).
+- **The results link.** The upload response names the checkup's results page
+  (`https://vigilbase.com/tools/run/<id>`). The CLI prints it, and opens it in
+  your browser only when it is on the upload origin (never with `--no-open`,
+  `--json`, in CI or without a display). The same link is emailed to the
+  verified address.
+
+## Installing cf
+
+When no usable cf is found (none at all, a different program named `cf`, an
+unsupported version, or a release whose offline `--dry-run` mapping shows it
+renamed a command the checkup needs) and `--cf-bin` was not given, the command
+asks (after saying why the cf it found cannot be used):
+`Cloudflare's cf CLI (cf@1.0.0-beta.13, about 75 MB) is not installed. Install it for Vigilbase now? [Y/n]`
+(Enter means yes; `--yes` answers yes; without a terminal and without `--yes`
+it stops with `CF_NOT_FOUND`).
+
+- **Location:** `<config dir>/cf/1.0.0-beta.13/` (0700), where the config dir is
+  `VIGILBASE_CONFIG_DIR`, `$XDG_CONFIG_HOME/vigilbase` or `~/.config/vigilbase`.
+  It is used before any cf on `PATH`, and only by Vigilbase.
+- **npm:** the `npm-cli.js` named by `npm_execpath` (as set by npm/npx), or the
+  npm bundled beside this Node. It runs as
+  `node <npm-cli.js> install --prefix <staging> --no-audit --no-fund --ignore-scripts --omit=optional cf@1.0.0-beta.13`
+  without a shell, from a fresh private staging directory, with your
+  environment (your npmrc, proxy and CA settings apply) minus every `CF_*` and
+  `CLOUDFLARE_*` variable and any variable carrying a session code, a
+  verification token or `--email`. npm's output
+  is shown only if it fails (the last 20 lines, without lines that could carry
+  a registry credential).
+- **Integrity:** the staging lockfile must record `node_modules/cf` at exactly
+  version `1.0.0-beta.13` with npm's `dist.integrity`
+  `sha512-dCjpzCJvjudIu8IQbXCJfy9diFoyHU84D/30K4lJp7jUaBgvjJypsMFzLqvUFOuwhF1ggR/igsLqXyehAOR2FQ==`,
+  and the installed package.json must agree. Otherwise the staging directory is
+  deleted (`CF_INSTALL_FAILED`). Only a verified install is renamed into place,
+  so a half-finished one is never used; the usual identity checks (below) still
+  apply.
+- **`--ignore-scripts`:** cf's `--version`, `--dry-run` and API reads need no
+  lifecycle scripts.
+- **`--omit=optional`:** cf's optional dependencies are the workerd and sharp
+  platform binaries (about 150 MB of the 225 MB default install). In cf
+  1.0.0-beta.13 the modules that load `miniflare`, `workerd` or `sharp` are
+  reachable only from `--local` mode (which the CLI never passes) and from the
+  `workers`, `deploy` and `previews` command trees; no module statically
+  reachable from cf's entry imports them, and there are no computed imports.
+  The checkup runs none of those commands, so the install is about 75 MB.
+- **Failures:** no npm → `CF_INSTALL_FAILED` with the manual
+  `npm install --global cf@1.0.0-beta.13` fallback; then run the command again.
+- **Interruptions:** Ctrl-C while npm runs stops npm and deletes the staging
+  directory. A staging directory left by a crash or a closed terminal is
+  deleted by the next install once it is older than npm's 10-minute timeout,
+  and by `logout`.
+
+`logout` removes `<config dir>/cf` again.
+
+## Signing in to Cloudflare
+
+With a cf profile (the default when `CLOUDFLARE_API_TOKEN` is not set), the
+command first runs one serial `cf auth whoami --profile vigilbase-checkup`. If
+the profile is missing, expired or revoked and a terminal is available, it
+prints `Signing in to Cloudflare with a read-only login. Your browser will open…`
+and runs `cf auth create vigilbase-checkup --scopes …` interactively (the read
+scopes below), then checks `whoami` once more. Without a terminal it stops with
+`CF_AUTH_REQUIRED`. cf keeps the login in its own config directory.
+
+OAuth from a datacenter or VPN address may be challenged by Cloudflare; use a
+read-only API token there (servers, CI):
+
+```bash
+read -rs CLOUDFLARE_API_TOKEN && export CLOUDFLARE_API_TOKEN      # input hidden
+npx @vigilbase/cli cloudflare-checkup
+# PowerShell 7.1+: $env:CLOUDFLARE_API_TOKEN = Read-Host -MaskInput 'Cloudflare API token'
+```
+
+## Choosing the account and where the snapshot goes
+
+The account is chosen in the CLI: `--account-id` if given; otherwise the
+accounts cf can read: one is used as is, several get a numbered picker (name
+and masked ID, up to 20 shown) on a terminal (an arrow-key list of every
+account in the terminal UI), and without a terminal
+`ACCOUNT_SELECTION_REQUIRED` lists the full IDs for `--account-id`. The
+uploaded snapshot binds the checkup to its account. (A checkup vigilbase.com
+reports as already bound to an account is collected for that account, and an
+`--account-id` that differs stops with `ACCOUNT_MISMATCH` before cf runs.)
+
+Without `--out`, the snapshot is written to
+`<config dir>/checkups/cloudflare-checkup-<first 8 of the account ID>-<UTC yyyymmddThhmmssZ>.json`
+(`-2`, `-3`, … if a run in the same second already used the name). The
+directory is created 0700 and never through a symbolic link; the file is 0600,
+written to a hidden temp file first and then given its name, so it never holds
+a partial snapshot. `--out` must name a new file in an existing, writable
+directory (or an existing regular file with `--overwrite`). The file is yours:
+it stays after the upload, and `inspect` shows what it contains.
+
+The snapshot is kept whatever happens to the upload: when it cannot go ahead
+(`SESSION_*`, `VERIFICATION_*`, `SUBMIT_FAILED`, `VIGILBASE_*`,
+`LOCAL_MODE_DISABLED`), the command prints, next to the error,
+`npx @vigilbase/cli cloudflare-checkup submit <saved file>` to upload it
+later without collecting again (it verifies your email again). When the run
+used a loopback `--base-url`, that command ends with the same `--base-url`.
+
+## Advanced commands
+
+| Command | Flags | Network |
+| --- | --- | --- |
+| `login` | `--profile`, `--cf-bin`, `--no-open`, `--dry-run` | cf OAuth only |
+| `doctor` | `--profile`, `--cf-auth`, `--cf-bin`, `--json` | `cf auth whoami` |
+| `accounts` | `--profile`, `--cf-auth`, `--cf-bin`, `--json` | Cloudflare via cf |
+| `collect` | `--out` (required), `--account-id`, `--overwrite`, `--dry-run`, `--max-requests-per-5min`, `--profile`, `--cf-auth`, `--cf-bin`, `--json` | Cloudflare via cf |
+| `inspect <file>` | `--json` | none |
+| `submit <file>` | `--email`, `--yes`/`--confirm`, `--no-open`, `--base-url`, `--timeout`, `--json` | vigilbase.com |
+| `logout` | `--profile`, `--cf-bin`, `--json` | none from the CLI (cf may revoke its own token) |
+
+All are `vigilbase cloudflare-checkup <command>` or
+`vigilbase local cloudflare-checkup <command>`. They keep their own defaults
+(`--cf-auth profile`, no cf install, no sign-in). They find a cf installed by
+the one command. `collect --dry-run` prints every cf command with
+`<ZONE_ID>`/`<RULESET_ID>` placeholders, the child-environment variable names
+(never values), the not-collected list and the request formula; it makes no
+Cloudflare and no Vigilbase requests. `submit` checks the file, checks that
+vigilbase.com has local checkups on, verifies your email like the one command,
+then uploads a snapshot collected earlier (accepted for 24 hours) and prints
+the results link.
+
+`logout` runs `cf auth delete <profile>` through the cf it finds (an
+interactive passthrough, so cf's own message is shown; cf 1.0.0-beta.13 takes
+only the profile name, refuses `--profile` and a set `CLOUDFLARE_API_TOKEN`,
+which the CLI never passes to it, and fails for a profile that does not exist),
+then removes `<config dir>/cf`. It prints what it removed; a profile cf
+declines to delete (usually one that does not exist) is reported, not an error,
+so `logout` can be repeated. A cf that cannot run at all is an error (exit 1,
+`success: false`), because the login may still be on disk. The cf Vigilbase
+installed is then kept (`managedCf.kept`), since it is usually the only cf that
+can delete the login, and the hint says how: run `logout` again under Node.js
+22.18 or newer, or, when the installed cf itself is damaged, install cf with
+`npm install --global cf@1.0.0-beta.13` and run
+`logout --cf-bin "$(npm root -g)/cf"`, which deletes the login and then removes
+the damaged copy. Without any cf, logout says the profile could not be checked
+(it does not claim that there is none).
+
+`--base-url` accepts only `https://vigilbase.com` or a loopback origin
+(`http(s)://localhost`, `127.0.0.0/8`, `[::1]`) for local testing.
+`VIGILBASE_BASE_URL`, `VIGILBASE_API_URL`, `VIGILBASE_PUBLIC_URL`,
+`VIGILBASE_ONE_URL` and `VIGILBASE_AUTH_URL` are ignored. A redirect from
+vigilbase.com is never followed; the request fails (`SUBMIT_FAILED`) without a
+retry. `VIGILBASE_CONFIG_DIR` is read only for the managed cf and the default
+snapshot path (`inspect` never reads it).
+
+## Locating cf
+
+The CLI looks for `--cf-bin`, then the Vigilbase-managed install
+(`<config dir>/cf/1.0.0-beta.13`, only if its lockfile still matches the pin),
+then absolute `PATH` entries holding `cf` and then `cloudflare`
+(`cf.cmd`/`cloudflare.cmd` on Windows), then pnpm
+(`$PNPM_HOME/global/*/node_modules/cf`) and Volta
+(`$VOLTA_HOME/tools/image/packages/cf/…`) global directories, without running a
+package manager. A candidate is used only if its `package.json` has
+`name: "cf"`, a repository on `github.com/cloudflare/cf` and a `bin.cf` entry
+matching the file found; the Cloud Foundry CLI (also `cf`) is skipped. cf is run
+as `node <bin.cf entry>`, never through a shim or shell, and its `--version`
+output must match its package version.
+
+Supported: `cf >= 1.0.0-beta.13` and `< 2.0.0`; `1.0.0-beta.13` is tested.
+Untested versions in range produce a warning and are used only when every
+command template's offline mapping verifies. Fallbacks: `--cf-bin "$(npm root -g)/cf"` (npm),
+`--cf-bin "$(pnpm root -g)/cf"` (pnpm), or Volta's package directory next to
+`volta which cf`.
+
+## The allowlist and what the preflight proves
+
+cf runs only these argv (plus `--quiet`, and `--profile <p>` in profile mode),
+with `CLOUDFLARE_ACCOUNT_ID=<account>` set on every account- and zone-scoped
+call (not on `accounts list` or `auth whoami`, which run before an account is
+chosen). Interpolated values are
+re-validated: 32-hex IDs, the 19 fixed zone setting IDs and integer pages. No
+confirmation-skipping, local-mode, project-mode or request-body flag is ever
+passed.
+
+| Read | cf argv | Paging |
+| --- | --- | --- |
+| account selection | `accounts list --per-page 50 --page N` | until an empty page |
+| account | `accounts get` | single |
+| zones | `zones list --account-id A --per-page 50 --page N` | until an empty page |
+| members | `accounts members list --per-page 50 --page N` | until an empty page |
+| account rulesets | `rulesets list --per-page 100` | one call |
+| account access rules | `firewall access-rules list --per-page 50 --page N` | until an empty page |
+| Access apps, IdPs, service tokens | `zero-trust access applications list`, `zero-trust identity-providers list`, `zero-trust access service-tokens list` (`--per-page 50 --page N`) | until an empty page |
+| Gateway rules, locations | `zero-trust gateway rules list`, `zero-trust gateway locations list` | single |
+| tunnels | `tunnels list --tun-types cfd_tunnel --is-deleted false --per-page 50 --page N` | until an empty page |
+| zone settings (×19) | `zones settings get S --zone Z` | single |
+| DNSSEC | `dns dnssec get --zone Z` | single |
+| DNS records | `dns records list --zone Z --per-page 100 --page N` | until an empty page (cap 100) |
+| Universal SSL, Total TLS | `ssl universal settings get --zone Z`, `acm total-tls get --zone Z` | single |
+| zone rulesets | `rulesets list --zone Z --per-page 100` | one call |
+| ruleset detail | `rulesets get R --zone Z` | single |
+| zone access rules | `firewall access-rules list --zone Z --per-page 100 --page N` | until an empty page |
+| page rules, bot management, page shield | `page-rules list --zone Z`, `bot-management get --zone Z`, `client-side-security settings get --zone Z` | single |
+| API Shield | `api-security schema-validation settings get --zone Z`, `api-security schema-validation schemas list --zone Z --omit-source --per-page 100 --page N` | single / until an empty page |
+
+The only other cf argv are `--version`, `auth whoami`, `auth create <p> --scopes …`
+(sign-in, interactive) and `auth delete <p>` (logout, interactive).
+
+Before collecting (the one command, `collect`, `collect --dry-run`) and in `doctor`, every template
+runs once with `--dry-run` and placeholder IDs (no credentials, no network);
+`accounts` checks only the `accounts list` mapping, so use `doctor` to verify
+the full mapping. The printed
+request must be `GET` with exactly the expected path and query. In cf beta.13
+that object is a literal printed by each command, so the preflight is a
+**command-name → API-path mapping check only**: it detects renamed or remapped
+commands, but it does not prove where cf would really send a request. Removing
+base-URL variables from cf's environment is the control for that (below). A
+template that does not map is recorded as `collection_failed/command_unavailable`;
+for `accounts list`, `accounts get` or `zones list` the run stops with
+`CF_ALLOWLIST_MISMATCH`.
+
+cf strips pagination metadata, so lists are paged until a page comes back empty
+(one extra call per list, immune to server-side page clamps). A page whose first
+item repeats the previous page's is `invalid_output` (cf ignoring `--page`). The
+rulesets lists are cursor-only and the cursor is not printed: 100 or more items
+are recorded as `possibly_truncated`.
+
+## Process and environment policy
+
+- cf runs from a private, empty `0700` temporary directory that is removed
+  afterwards (and on Ctrl-C). Your project's `.env`, `.env.local`,
+  `cloudflare.config.ts`, directory profile bindings and cf's account cache never
+  apply. `CF_DELEGATION=1` stops cf from handing off to a project-local cf.
+- cf's environment is built from an empty object. Copied by name if present:
+  `PATH HOME USER LOGNAME USERPROFILE APPDATA LOCALAPPDATA SystemRoot WINDIR`,
+  `XDG_CONFIG_HOME XDG_CACHE_HOME XDG_DATA_HOME XDG_STATE_HOME XDG_RUNTIME_DIR`,
+  `TMPDIR TMP TEMP LANG LC_ALL LC_CTYPE TZ`, the `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY`
+  variables (both cases), `NODE_EXTRA_CA_CERTS SSL_CERT_FILE SSL_CERT_DIR
+  DBUS_SESSION_BUS_ADDRESS CLOUDFLARE_AUTH_USE_KEYRING`.
+- Forced: `CI=1 NO_COLOR=1 FORCE_COLOR=0 CF_QUIET=1 CF_SEND_TELEMETRY=false
+  DO_NOT_TRACK=1 CF_DELEGATION=1` (telemetry off, no prompts, no update checks).
+- `CLOUDFLARE_API_TOKEN` is passed only with `--cf-auth env`, and only to API
+  reads (absent → `CF_AUTH_REQUIRED`). In profile and default modes it is removed,
+  because it would override `--profile`; a notice says so.
+- Never passed, by construction: `CLOUDFLARE_API_BASE_URL`, `CF_API_BASE_URL`
+  (the primary control against redirecting your token), `CLOUDFLARE_COMPLIANCE_REGION`,
+  `CLOUDFLARE_CLIENT_ID`, `CLOUDFLARE_ZONE_ID`, `CLOUDFLARE_ACCESS_CLIENT_ID/SECRET`,
+  `CLOUDFLARE_API_KEY`, `CLOUDFLARE_EMAIL`, `WRANGLER_*`, `VIGILBASE_*`,
+  `NODE_OPTIONS`, `NODE_PATH`, `NODE_TLS_REJECT_UNAUTHORIZED`, `npm_config_*`,
+  `DEBUG` and agent-harness markers (`CLAUDECODE`, `CODEX_*`, `CURSOR_*`).
+  FedRAMP and compliance-region accounts are not supported.
+- cf output is capped (stdout 8 MiB, 16 MiB for `rulesets get`; stderr 64 KiB)
+  and each call times out after 45 s. stderr is never shown: it is reduced to a
+  classification (unknown command, authentication, HTTP status, network).
+
+**Requests and pacing.** Four cf processes run at once within a budget of 900
+requests per rolling 5 minutes (Cloudflare allows 1,200 per user, shared with
+your dashboard). A collection needs about 19 + extra pages + zones × (33 +
+rulesets per zone) requests; 100 zones take about 25 minutes. Accounts over 100
+zones or 6,000 requests are refused (`ACCOUNT_TOO_LARGE`). 5xx, network errors
+and timeouts are retried twice (1 s, 3 s). A 401 pauses all calls for one serial
+`cf auth whoami`, then retries once. A 429 pauses all calls for 30 s and retries
+once; a second 429 stops with `CF_RATE_LIMITED` (exit 2) and no file. Before the
+OAuth token expires, dispatch pauses, in-flight calls finish, and one serial
+`whoami` performs cf's single refresh; cf beta.13 prints the pre-refresh expiry
+from that call, so a second serial `whoami` reads the new one. This repeats
+before every expiry in a long run.
+
+## Scopes
+
+The sign-in (and `login`) requests these read scopes (names verified against
+cf 1.0.0-beta.13):
+
+`account:read account-settings.read memberships.read user:read user-details.read
+zone:read zone.read zone-settings.read dns.read dns_records:read
+ssl-and-certificates.read zone-waf.read account-waf.read account-rulesets.read
+http-ddos-managed-ruleset.read firewall-services.read
+account-firewall-access-rules.read page-rules.read bot-management.read
+page-shield.read domain-page-shield.read api-gateway.read access.read access:read
+access-app.read access-idp.read access-service-token.read teams.read teams:read
+argotunnel.read teams-connector-cloudflared.read`
+
+`doctor` lists missing recommended scopes and counts write scopes in profile and
+default modes. API token permissions cannot be introspected, so with
+`--cf-auth env` it reports scopes as unknown. A denied read is recorded as
+`http_error 403` and the affected checks are skipped, never scored as passing.
+
+## What leaves your machine
+
+For the email verification, your work email address and the code from the
+email (see "Email verification and the checkup session"). Otherwise only the
+snapshot file, and only after you confirm the upload (the one command or
+`submit`).
+Each cf response is projected immediately and the raw text discarded. The file
+(`vigilbase.cloudflare-checkup.snapshot/1`) keeps only what the scanner reads:
+
+- account `id, name, type`, 2FA enforcement; zone `id, name, status, paused,
+  type, development_mode, plan name, account`;
+- members: pending or 2FA-off markers, and the e-mail address of at most 8
+  pending and 8 2FA-off members;
+- access rules: the first 5 broad rules' `mode, target, value` (later broad
+  rules keep only what makes them broad; other rules are counted);
+- counts only for Access apps, Gateway locations, schemas and account rulesets;
+  IdP types, service-token expiry, Gateway rule `enabled:false` and filters,
+  tunnel status;
+- zone settings' values, DNSSEC status/algorithm, Universal SSL/Total TLS/page
+  shield `enabled`;
+- DNS A/AAAA records with **pseudonymised IPs** (the first two IPv4 or three IPv6
+  groups are kept, the host part becomes a per-prefix counter); names only for
+  non-proxied records;
+- ruleset `id, phase`, `name: 'ddos'` markers, and rules reduced to action,
+  `enabled:false`, a `true`/geo-block expression marker, managed-ruleset IDs and
+  name keywords; IDs and descriptions only on disabled managed rules and
+  block-everything rules; identical rules run-length encoded;
+- legacy page-rule action IDs, bot-management and schema-validation settings.
+
+No credentials, scopes, cf profile names, e-mail of the cf user, file paths or
+hostnames of your machine. Collector metadata is the CLI and cf version, the auth
+**kind** (`cf_profile`, `cf_env_token`, `cf_default_profile`), the OS family,
+timestamps and the cf call count. Before writing and again before uploading, the
+file is validated and checked for credential-shaped values (session codes,
+verification tokens, API tokens, JWTs, PEM blocks, bearer strings). `inspect` shows counts of every
+free-text category.
+
+**Projection predicates (disclosure).** To minimise uploads, the projections
+encode selection rules that mirror some checks: which rules count as issue
+rules, the geo-block marker, what makes an access rule broad, the legacy
+page-rule actions, the pending/2FA-off member selection, and the public managed
+ruleset IDs and name keywords. These ship in this MIT package. No scoring,
+deductions, severities, report copy or grade logic ship in the CLI.
+
+## Not collected locally
+
+cf 1.0.0-beta.13 has no command for five checks per zone: legacy Firewall Rules,
+legacy Filters, previous-version WAF packages, previous-version Rate Limiting,
+and WAF traffic analytics (GraphQL). They are recorded as `not_collected`, shown
+as **Not collected locally** and never scored as passing.
+
+The plan and add-on review is not collected either: the snapshot has no entry
+for add-on entitlements or the Smart Shield setting. The PDF report shows each
+zone's plan from the zone list and lists Advanced Bot Management, Advanced Rate
+Limiting, API Shield, Page Shield (advanced) and Smart Shield as **Not
+collected**. Run the token-based checkup in the browser to include them.
+
+## Error codes and exit codes
+
+Exit codes: **0** success (any grade, replay, file written, dry run, healthy
+doctor), **1** any other error, **2** `CF_RATE_LIMITED` or a vigilbase.com 429
+(`VIGILBASE_RATE_LIMITED`), **130** cancelled with Ctrl-C. Errors print `code` and a `hint`; JSON errors are
+`{success:false, error, code, status?, retryAfterSec?, hint?}`. Server messages
+are never echoed.
+
+| Code | Fix |
+| --- | --- |
+| `NODE_UNSUPPORTED` | Install Node.js 22.18 or newer from https://nodejs.org, then run the same command again. |
+| `CF_NOT_FOUND` | Run the same command again in a terminal and let it install cf (or add `--yes`), or `npm install --global cf@1.0.0-beta.13`. |
+| `CF_WRONG_BINARY` | Another `cf` (Cloud Foundry, or a pnpm/Volta shim) was found; run the command without `--cf-bin` and let it install cf, or pass `--cf-bin`. |
+| `CF_UNSUPPORTED_VERSION` | Run the same command again without `--cf-bin` and let it install the tested cf. |
+| `CF_ALLOWLIST_MISMATCH` | This cf release renamed a required command; run the same command again without `--cf-bin` and let it install the tested cf for Vigilbase (your own cf is left alone). |
+| `CF_INSTALL_FAILED` | npm is missing or failed, or the download did not match the pinned integrity; `npm install --global cf@1.0.0-beta.13`, then run the same command again. |
+| `CF_AUTH_REQUIRED` | Run the same command again in a terminal to sign in (read-only), or set `CLOUDFLARE_API_TOKEN` first. With the token set (env mode), set a valid read-only token, or unset it (or use `--cf-auth profile`) to sign in with your browser. |
+| `CF_PERMISSION_DENIED` | Your Cloudflare login cannot read the zones; check its permissions, then run the same command again. With `CLOUDFLARE_API_TOKEN` set (env mode), add the read permissions to the token, or unset it (or use `--cf-auth profile`) to sign in with your browser. |
+| `CF_RATE_LIMITED` | Wait 5 minutes, then run the same command again; add `--max-requests-per-5min 600` if it repeats. |
+| `CF_ERROR` | Run the same command again in a few minutes. |
+| `ACCOUNT_SELECTION_REQUIRED` | Run the same command again in a terminal to choose, or add `--account-id <ACCOUNT_ID>` (listed in the error). |
+| `ACCOUNT_NOT_VISIBLE` | Check that your Cloudflare user can read the account and its zones. |
+| `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_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. |
+| `EMAIL_CODE_INVALID` | Five codes were wrong or not 6 digits; run the same command again for a new code. |
+| `VERIFICATION_INVALID` / `VERIFICATION_EXPIRED` | The code expired, was tried too often, or the checkup closed; run the same command again for a new code. |
+| `SESSION_INVALID` / `SESSION_EXPIRED` | Run the same command again to verify your email and start a new checkup. An expired session is renewed once first; after collection, upload the saved file with `submit`. |
+| `SESSION_USED` / `SESSION_CLOSED` | Run the same command again to start a new checkup. |
+| `SESSION_BUSY` | A snapshot for this checkup is still being processed; wait for the results email, or run the same command again. |
+| `SUBMIT_ORIGIN_UNTRUSTED` | Upload only to https://vigilbase.com (or loopback for testing). |
+| `CONFIRMATION_REQUIRED` | Run the command in a terminal, or add `--yes` (and, without `--email`, pipe the address and the code to stdin). |
+| `CLI_UPGRADE_REQUIRED` | vigilbase.com needs a newer CLI (checked before your email is asked for). Run `npx @vigilbase/cli@latest cloudflare-checkup`, or `npm install --global @vigilbase/cli@latest`. |
+| `LOCAL_MODE_DISABLED` | Local checkups aren't available right now. Run the Cloudflare Checkup in your browser instead: https://vigilbase.com/tools/cloudflare-checkup. |
+| `VIGILBASE_RATE_LIMITED` | Wait as long as the error says (`retryAfterSec` in JSON), then run the same command again. |
+| `VIGILBASE_CHALLENGED` | vigilbase.com challenged the request; try another network or contact help@vigilbase.com. |
+| `SUBMIT_FAILED` | Run the same command again later. |
+
+JSON success payloads (stdout):
+
+- `collect`: `{success, snapshot:{path,bytes,sha256,schemaVersion,accountId,zoneCount,entries:{total,ok,httpError,notCollected,collectionFailed}}, cf:{version,authSource}, cfInvocations, durationMs, warnings:[{code,message}]}`
+- `collect --dry-run`: `{success, dryRun:true, cf:{version,path,tested}, plan:{accountSelection,account,perZone,perRuleset,notCollected}, verified:{commands,mismatched}, childEnv, requestFormula, warnings}`
+- `inspect`: `{success, snapshot:{path,bytes,sha256,schemaVersion,accountId,accountName,zoneCount,collectedAt,collector}, entries:{byKind}, dataCategories:{memberEmails,accessRuleValues,dnsHostnames,pseudonymizedIps,ruleDescriptions}}`
+- `submit`: `{success, replayed, snapshotSha256, provenance, report, resultsUrl?}`; `resultsUrl` is the results page when vigilbase.com returned one; never the email address, a code, a token or the session code
+- the one command (`cloudflare-checkup`, `run`): the `submit` fields plus `snapshot` (as in `collect`) and `warnings`
+- `logout`: `{success, profile:{name,removed,problem?}, managedCf:{path,removed,kept?}, warnings, hint?}`; `success` is false (exit 1) when cf could not run (`problem`)
+- `doctor`: `{success, node:{version,supported}, cf:{found,path,version,supported,tested,identityVerified}, auth:{source,profile,authenticated,expiresAt?,scopes,missingRecommendedScopes?,writeScopeCount?}, commands:{verified,mismatched}, warnings, problems}`
+- `accounts`: `{success, accounts:[{id,name}]}`
+
+## Windows, pnpm and Volta
+
+Windows x64 is supported as beta without CI coverage: cf runs via
+`process.execPath` with the entry beside `cf.cmd` (npm's global layout), never
+through `cmd.exe`; and the managed install uses the `npm-cli.js` beside
+`node.exe`. The results page is not opened on Windows (the link is printed).
+Windows on ARM is not supported. The checkup needs no Vigilbase sign-in, so it
+works on Windows even though `vigilbase login` doesn't yet. pnpm and Volta
+global installs are found automatically; otherwise pass `--cf-bin` as above.
+
+## Cleanup
+
+```bash
+npx @vigilbase/cli cloudflare-checkup logout   # cf auth delete vigilbase-checkup, then removes <config dir>/cf
+rm ~/.config/vigilbase/checkups/cloudflare-checkup-*.json   # the snapshots are yours; delete them when done
+```
+