@vigilbase/cli/LOCAL.md

Vigilbase CLI — security scanners, agent tools, and Vigilbase One from the terminal.

# 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.3/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; use `npx` (see
[Troubleshooting](https://app.unpkg.com/@vigilbase/cli@0.2.3/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. 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). When `inspect` or `submit` finds no file at the path, check the path, or collect one with `npx @vigilbase/cli cloudflare-checkup collect --out <file>`. |
| `SNAPSHOT_TOO_LARGE` | Run the checkup in your browser instead, https://vigilbase.com/tools/cloudflare-checkup. |
| `SNAPSHOT_STALE` | Snapshots are accepted for 24 hours; run the same command again. |
| `EMAIL_INVALID` | Use your work email (personal and disposable addresses are refused), then run the same command again. |
| `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
```