Navigation
VigilbaseDocs

    Type at least two letters.

    Open Vigilbase One

    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.

    View as Markdown
    On this page
    1. Run it
    2. What leaves your machine
    3. What is not collected locally
    4. Options
    5. Run it in a script
    6. Advanced subcommands
    7. Clean up
    8. Checkups through Vigilbase One

    vigilbase cloudflare-checkup runs the 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:

    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

    OptionMeaning
    --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.
    --yesInstall cf without asking. Needed without a terminal.
    --no-openPrint the results link without opening a browser.
    --cf-auth auto|profile|env|defaultHow 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.
    --jsonOne 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

    CommandWhat it does
    cloudflare-checkup loginSigns cf in read-only under the checkup profile.
    cloudflare-checkup doctorChecks Node, cf and the cf login.
    cloudflare-checkup accountsLists 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 logoutDeletes 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.