@vigilbase/cli
Version:
Vigilbase CLI — security scanners, agent tools, and Vigilbase One from the terminal.
872 lines • 57.6 kB
Markdown
# 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 once it is saved and shown. 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.10/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`. With
Yarn 4.15+ or pnpm 11+, `yarn dlx` and `pnpm dlx` run an older release for a
day after each release, and pnpm 10.16+ with `minimumReleaseAge` set refuses
the new version; use `npx` (see
[Troubleshooting](https://app.unpkg.com/@vigilbase/cli@0.2.10/files/README.md#troubleshooting)).
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. Uses your verified Vigilbase CLI login without email prompts or codes.
If signed out, 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, or was signed in
by an older release without every read scope this one needs (without a
terminal that is a `CF_SCOPES_MISSING` warning and those reads are
refused; run `cloudflare-checkup login` to fix it). 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. Uploads exactly that file automatically (`Uploading 182 KB to
https://vigilbase.com. Results go to j***@acme.com.`). To collect without
uploading, use [`collect`](#advanced-commands) instead.
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
│
◇ Uploading 182 KB to vigilbase.com
│ Results go to j***@acme.com
│
└ ✓ Done. 31 passed · 6 warnings · 4 failed · 30 reads not collected locally
████████████████████████░░░░░░░░ 31 of 41 free checks passed
Top findings
✗ critical Account MFA Enforcement account-wide
✗ high DNSSEC on 3 domains
▲ medium Always Use HTTPS on 6 domains
+412 more checks in the full report
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
Uploading 182 KB to https://vigilbase.com. Results go to j***@acme.com.
✓ 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.
Top findings:
✗ critical Account MFA Enforcement · account-wide
✗ high DNSSEC · on 3 domains
▲ medium Always Use HTTPS · on 6 domains
+412 more checks in the full report
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>` | Override the signed-in address; a different address requires email verification. Signed out, the CLI asks when omitted. |
| `--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. |
| `--confirm` | Accepted but no longer needed: the upload is not a question (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` does not answer the cf install
question), then Node. Then, before it contacts vigilbase.com at all, it
checks what it can locally:
- with `--cf-auth env`, that `CLOUDFLARE_API_TOKEN` is set
(`CF_AUTH_REQUIRED`);
- `--out`: a directory gives `OUTPUT_EXISTS` with
`--out names a directory; it must name a regular file. Nothing was collected.`,
and any existing entry, a dangling symbolic link included, gives
`OUTPUT_EXISTS` without `--overwrite`. With `--overwrite` a symbolic link is
replaced, never followed, unless it points to a directory;
- without `--out`, that `<config dir>/checkups` can be created (it isn't
created yet, so a run that stops here writes nothing);
- a given `--cf-bin` exists and is Cloudflare's cf (`CF_NOT_FOUND`,
`CF_WRONG_BINARY`; nothing is run).
Only then does it ask whether vigilbase.com has local checkups on and accepts
this CLI. So no code is emailed for a run that could not install cf, write
the snapshot 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. `submit` checks the file first, and after the
availability answer, before it asks for the email, refuses a snapshot over the
size or zone limit vigilbase.com announced (`SNAPSHOT_TOO_LARGE`).
Two problems can show only once cf runs, after the email was verified: without
a terminal, a missing cf login in profile mode (`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 (`Checking vigilbase.com`, or the host of a
loopback `--base-url` such as `Checking 127.0.0.1:3001`), 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 | ←/→ choose, Enter answers, `y` or `n` answer at once. The question starts on **Yes**. |
- 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 result ends with a short card from vigilbase.com's free report: a bar
of the free checks (green passed, yellow warnings, red failed; without
colour, the share that passed), up to five top findings (failed before
warnings, then by the severity vigilbase.com gave them; each check once, with
the number of domains it affects, never their names; any more are counted:
`… 2 more findings on the results page`) and how many more checks the full
report has. Long names are cut to the terminal width.
- 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.
- In the plain output, the `✓ Uploaded. Free summary: …`, `Results: …` and
email lines come first and keep their wording, so scripts can match them;
the top findings (`Top findings:`, one indented line each and, past five,
`… N more findings on the results page`) and the
`+N more checks in the full report` line follow them.
- 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. While cf or npm runs, Ctrl-C, SIGTERM and SIGHUP stop them and
exit 130, 143 and 129. 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]` question, 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
Snapshot uploads retry network failures and HTTP 503 responses twice using
the same bytes and session. A 503's `retryAfterSec` or `Retry-After` delay is
honoured up to 60 seconds per retry; longer delays stop with retry guidance.
Without a server delay, retries wait 2 seconds, then 5 seconds. Challenges and
the local-mode kill switch are never retried. The saved snapshot remains
available for a later `submit` if these attempts fail.
When you are signed in with `vigilbase login`, both the one command and
`submit` use your verified account identity and skip email prompts and codes.
The CLI sends its login token only to One's
`POST /api/tools/cloudflare-checkup/local-identity`. One checks the live
identity and verified mailbox, then signs a proof valid for at most two minutes
and tied to this checkup's run ID. The CLI exchanges that proof at
`POST …/local-session/identity` for an upload session. vigilbase.com never
receives the login token. Session renewal obtains a fresh proof for the same
run; it does not send an email or create a second checkup. Proofs and session
codes stay in memory and are never printed or passed to cf or npm.
A missing, expired or rejected login uses the email flow below. `--email`
matching the live identity also skips verification; a different address must
verify by email. Signed-in users may use their verified account mailbox even
when it is a personal address; signed-out email verification still requires a
business address. Availability, rate limits and Cloudflare's own sign-in
apply to both paths.
The CLI verifies signed-out users' 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`:
`vigilbase.com requires @vigilbase/cli <version> or newer for this snapshot.`
(the hint names `@latest`), or
`vigilbase.com does not accept snapshots in the <schemaVersion> format.`
with the hint
``Collect a fresh snapshot with the latest CLI: `npx @vigilbase/cli@latest cloudflare-checkup`.``
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 by the time of the upload, 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 (or SIGTERM or SIGHUP) while npm runs kills npm,
deletes the staging directory and exits 130 (143, 129). 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`, `--no-open`, `--base-url`, `--timeout`, `--json` (`--yes`/`--confirm` are accepted but not needed) | 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. A flag a subcommand doesn't take fails with
`--<flag> is not supported for cloudflare-checkup <subcommand>.` before
anything runs. `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. It warns as a real collect would: in env
mode without `CLOUDFLARE_API_TOKEN` it warns with code `CF_AUTH_REQUIRED`
(`… Without it, a real collect would stop here.`, exit 0), and in profile or
default mode with the variable set it warns `ENV_TOKEN_NOT_USED`.
`login --dry-run --cf-bin <path>` checks the path (`CF_NOT_FOUND`,
`CF_WRONG_BINARY`) without running cf. `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.
`inspect` validates a snapshot and shows what it contains. When the snapshot
can no longer be uploaded it adds `Upload no longer accepted (collected more than 24 hours ago)`
or `Upload not accepted (dated in the future)`, and above 4 MiB it warns
`The snapshot is larger than 4 MiB, the default upload limit.` Control
characters in a file name are shown as escapes (`\n`, `\u001b`) in the
`Snapshot` line of `inspect` and `submit`.
`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 50` | 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 50` | 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 |
| Edge certificate packs | `ssl certificate-packs list --zone Z --status all --per-page 50 --page N` | until an empty page |
| Uploaded custom certificates | `custom-certificates list --zone Z --per-page 50 --page N` | until an empty page |
| API operation enforcement | `web-assets operations list --zone Z --feature schema_info --per-page 50 --page N` | until an empty page |
The only other cf argv are `--version`, `auth whoami`,
`auth create <p> [--no-browser] --scopes …` (sign-in, interactive;
`--no-browser` comes from `login --no-open`) 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: 50 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, SIGTERM or SIGHUP: cf children get SIGTERM, then
SIGKILL after 2 s). A cancelled run never prints a result, and never writes
or uploads a snapshot. 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 (`ENV_TOKEN_NOT_USED`).
`collect --dry-run` lists it in `childEnv` only when it is set.
- 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 sanitize.read dynamic-redirect.read
config-settings.read zone-transform-rules.read cache-settings.read origin.read
response-compression.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`
Cloudflare permissions ruleset details per phase, so the rule-phase scopes
(Normalization, Single Redirects, Configuration, Transform, Cache, Origin and
Compression rules) are needed to read every ruleset a zone lists.
`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, uploaded automatically once it is saved and shown (the one
command or `submit`); `collect` never uploads.
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,
`per_prefix_sequential/1`); DNS hostnames, including proxied CNAMEs without their targets;
- certificate status, covered hostnames and expiry; API operation schema IDs and
mitigation actions, without API endpoint paths, schema source or certificate keys;
- ruleset `id, phase, kind`, `name: 'ddos'` markers, and rules reduced to action,
`enabled:false`, a `true`/`false`/geo-block expression marker, execution target 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.
The pseudonymisation is checked, not just claimed: `inspect` and `submit`
refuse a file whose DNS record contents are not numbered 1, 2, 3… within each
prefix without gaps (`SNAPSHOT_INVALID`, issue `ip_not_pseudonymized`), and vigilbase.com
refuses such an upload too. A real address that looks like the first
pseudonym of its prefix (for example `10.0.0.1`) can't be told apart.
**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.
Effective managed WAF scope and overrides are also explicitly not collected:
V1 projections omit account ruleset details, scope expressions and customer
overrides. They cannot establish effective coverage, even when basic deployment
evidence is present. Certificate and API-operation inputs are optional additions;
older V1 snapshots remain valid and report those missing inputs rather than
assuming protection. Browser scans include the full effective WAF checks and
bounded analytics, with Free-plan restrictions and sampling labeled separately.
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 (SIGINT), **143**
cancelled by SIGTERM, **129** cancelled by SIGHUP (a closed terminal). Errors
print `code` and a `hint`. Plain-text errors end with the code in parentheses,
for example
`Error: Local checkups aren't available right now. (LOCAL_MODE_DISABLED)`,
followed by `Hint: …`. JSON errors are
`{success:false, error, code, status?, retryAfterSec?, hint?}`; a cancelled
command prints
`{"success":false,"error":"Cancelled.","code":"CANCELLED","hint":"Nothing was uploaded. Run the same command again when you are ready."}`.
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. |
| `CWD_UNAVAILABLE` | The current directory no longer exists or cannot be read. Change to a directory that exists and that you can read (for example `cd ~`), then run the same command again. |
| `CF_NOT_FOUND` | From the one command: run it again in a terminal and let it install cf (add `--yes` when no terminal is available), or `npm install --global cf@1.0.0-beta.13`. From `login`, `doctor`, `accounts`, `collect`, `logout`, and from `run` with `--cf-bin`: run `npx @vigilbase/cli cloudflare-checkup` without `--cf-bin` (it can install cf), install cf with `npm install --global cf@1.0.0-beta.13`, or pass `--cf-bin <path>` to a cf package. |
| `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 "$(npm root -g)/cf"`. When the cf package was found but `cf --version` fails, the message is `cf --version failed; the package may be damaged.`: reinstall cf with `npm install --global cf@1.0.0-beta.13`, or run `npx @vigilbase/cli cloudflare-checkup` without `--cf-bin` and let it install the tested cf. |
| `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. |
| `CANCELLED` | Cancelled with Ctrl-C (or SIGTERM or SIGHUP). Nothing was uploaded. Run the same command again when you are ready. |
| `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` | Local collection supports up to 100 zones. Run the Cloudflare 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`. A directory (or other special file) as `--out` can't be replaced: name a regular file. |
| `SNAPSHOT_INVALID` | From `run` or `collect`: run the same command again to collect a fresh one. From `inspect`, `submit` (and the re-read before the one command uploads): the file is not a valid snapshot; collect a fresh one with `npx @vigilbase/cli cloudflare-checkup` (or `npx @vigilbase/cli cloudflare-checkup collect --out <file>`). `The snapshot file does not exist.` or `The snapshot path is a symbolic-link loop.`: check the path, or collect one with `collect --out <file>`. `The snapshot file cannot be read (permission denied).`: check the permissions of the file and of its directories, or copy it somewhere you can read it. |
| `SNAPSHOT_SECRET_LIKE_VALUE` | From `run` or `collect`: remove it from your Cloudflare settings (a name, description or other text field), then run the same command again. From a file: remove the credential-like value from your Cloudflare settings and collect a fresh snapshot. |
| `SNAPSHOT_TOO_LARGE` | The snapshot is over the upload limit. Run the Cloudflare Checkup in your browser instead: https://vigilbase.com/tools/cloudflare-checkup |
| `SNAPSHOT_STALE` | Snapshots are accepted for 24 hours. From `run`, run it again; from `submit`, collect a fresh one with `npx @vigilbase/cli cloudflare-checkup`. |
| `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` to install cf without asking (and, without `--email`, pipe the address and the code to stdin). |
| `CLI_UPGRADE_REQUIRED` | vigilbase.com needs a newer CLI, or doesn't accept the snapshot's format (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,uploadable,notUploadableReason?}, entries:{byKind}, dataCategories:{memberEmails,accessRuleValues,dnsHostnames,pseudonymizedIps,ruleDescriptions}, warnings}`; `notUploadableReason` (`older_than_24_hours` or `dated_in_the_future`) only when `uploadable` is false; `warnings` may hold `SNAPSHOT_OVER_DEFAULT_UPLOAD_LIMIT`
- `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,checked,expiresAt?,scopes,missingRecommendedScopes?,writeScopeCount?}, commands:{verified,mismatched}, warnings, problems}`; `auth.checked` is false (and `authenticated` false) when cf was not found or could not run, and the text says `not checked (cf not found)` or `not checked (cf could not run)`
- `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.
## Report analytics
Unlocked results and PDFs include check outcomes, evaluation coverage, category
findings and domain comparisons from the same evaluator used by browser scans.
Local reports remain labelled self-reported. Traffic analytics are not collected
by the CLI: reports say so explicitly rather than showing unmeasured zeroes.
Older V1 snapshots remain accepted; optional inputs absent from them produce
coverage gaps, not passing results. No additional upload fields or permissions
are required for the configuration charts.
## 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
```