# Cloudflare Checkup from the CLI

> Run the Cloudflare Checkup on your own machine with Cloudflare's cf CLI, see what is uploaded, and use the advanced subcommands.

Source: https://docs.vigilbase.com/tools/cli/cloudflare-checkup-cli

`vigilbase cloudflare-checkup` runs the [Cloudflare Checkup](https://docs.vigilbase.com/tools/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. vigilbase.com grades it with the same scanner as the browser checkup. Results are labelled **Self-reported**.

Local mode is in beta and works while vigilbase.com has it switched on. If it is off, the command stops with `Local checkups aren't available right now.` (code `LOCAL_MODE_DISABLED`) before it asks for your email. Run the checkup in your browser instead.

## Run it

```bash
npx @vigilbase/cli cloudflare-checkup
```

`vigilbase cloudflare-checkup` and `vigilbase local cloudflare-checkup` are the same command. It needs Node.js 22.18 or newer on macOS, Linux or Windows x64.

The command:

:::steps
1. **Checks availability.** It asks vigilbase.com whether local checkups are on and accept this CLI version. Nothing about you is sent.
2. **Verifies your email.** If you are signed in with `vigilbase login`, it uses your verified account and asks for nothing. Otherwise it asks for your work email and vigilbase.com emails you a 6-digit code to enter. Personal and disposable addresses are refused.
3. **Finds or installs cf.** If no usable `cf` is found, it offers to install the tested release just for Vigilbase. Your own `cf` is left alone.
4. **Signs in to Cloudflare read-only.** Your browser opens for a read-only `cf` login under the profile `vigilbase-checkup`. With `CLOUDFLARE_API_TOKEN` set in the shell, `cf` uses that token instead.
5. **Lets you choose the account.** One account is used as is; several get a list.
6. **Collects.** It runs read-only `cf` commands, at most 900 requests per 5 minutes by default.
7. **Saves and shows the snapshot.** The file goes to `~/.config/vigilbase/checkups/` with mode `0600`, and the CLI shows what it contains.
8. **Uploads it** and prints the results link, `https://vigilbase.com/tools/run/<id>`. It opens the link in your browser on macOS and Linux, and emails it to your verified address.
:::

If something fails, fix it and run the same command again; each run verifies your email and starts a new checkup.

## What leaves your machine

`cf` owns your Cloudflare login. The Vigilbase CLI never reads, prints, stores or uploads a Cloudflare credential.

Only two things go to vigilbase.com: your email address and code for verification, and the snapshot file. The snapshot keeps only what the scanner reads, such as account and zone settings, ruleset markers and DNS hostnames. DNS A and AAAA records have pseudonymised IP addresses: the network prefix is kept and the host part is replaced by a counter. The snapshot holds no credentials, cf profile names, file paths or details of your machine, and is checked for credential-like values before it is written and again before upload.

Inspect a snapshot at any time:

```bash
npx @vigilbase/cli cloudflare-checkup inspect ~/.config/vigilbase/checkups/<file>.json
```

## What is not collected locally

`cf` has no command for some inputs, so they are shown as **Not collected locally** and never scored as passing: legacy Firewall Rules, legacy Filters, previous-version WAF packages and Rate Limiting, WAF traffic analytics, plan add-ons and Smart Shield. Run the checkup in your browser to include them. Local collection supports accounts with up to 100 zones.

## Options

| Option | Meaning |
| --- | --- |
| `--email <address>` | Send results to this address. A different address from your sign-in needs email verification. |
| `--account-id <id>` | Skip the account picker. |
| `--out <file>` | Write the snapshot here; `--overwrite` replaces an existing file. |
| `--yes` | Install `cf` without asking. Needed without a terminal. |
| `--no-open` | Print the results link without opening a browser. |
| `--cf-auth auto\|profile\|env\|default` | How `cf` signs in. `auto` uses `CLOUDFLARE_API_TOKEN` when it is set, otherwise the profile. |
| `--profile <name>` | The `cf` profile; default `vigilbase-checkup`. |
| `--max-requests-per-5min <100..1100>` | Cloudflare request budget; default 900. |
| `--json` | One JSON object on stdout. |

## Run it in a script

Without a terminal, add `--yes`, sign in to Cloudflare first (run `cloudflare-checkup login` in a terminal, or set `CLOUDFLARE_API_TOKEN`) and pass `--account-id`. The CLI reads the email address (unless you pass `--email`) and then the code from stdin, one line each, after it prints `Code from the email:`.

## Advanced subcommands

| Command | What it does |
| --- | --- |
| `cloudflare-checkup login` | Signs `cf` in read-only under the checkup profile. |
| `cloudflare-checkup doctor` | Checks Node, `cf` and the `cf` login. |
| `cloudflare-checkup accounts` | Lists the accounts `cf` can read. |
| `cloudflare-checkup collect --out <file>` | Collects a snapshot without uploading it. `--dry-run` prints the `cf` commands it would run. |
| `cloudflare-checkup inspect <file>` | Validates a snapshot and shows what it contains. |
| `cloudflare-checkup submit <file>` | Verifies your email and uploads a snapshot collected earlier. Snapshots are accepted for 24 hours. |
| `cloudflare-checkup logout` | Deletes the read-only `cf` login and the `cf` that Vigilbase installed. |

## Clean up

```bash
npx @vigilbase/cli cloudflare-checkup logout
rm ~/.config/vigilbase/checkups/cloudflare-checkup-*.json
```

The snapshots are yours; delete them when you are done.

## Checkups through Vigilbase One

`vigilbase cf checkup start` is a different command: it runs the checkup on Vigilbase One's servers with the Cloudflare credentials stored in One, and needs `vigilbase login`.

For error codes, see [Troubleshooting](https://docs.vigilbase.com/tools/cli/troubleshooting#cloudflare-checkup-errors).