# Cloudflare CLI reference

`vigilbase cf` and `vigilbase cloudflare` use the authenticated Vigilbase One API. Run `vigilbase login` first (signing in isn't supported on Windows yet). Your organization, permissions, customer links, and allowed zones determine access. The CLI never requires a Cloudflare API key.

`cf checkup` runs on One's servers. `cloudflare-checkup` (also `local cloudflare-checkup`) runs on your machine with Cloudflare's own `cf` CLI and needs no Vigilbase login: one command, `npx @vigilbase/cli cloudflare-checkup`, verifies your work email with a code, installs cf if needed, signs in read-only, collects, shows what it saved and uploads it (`collect` alone never uploads). It works while vigilbase.com has local checkups switched on; otherwise it says so before asking for your email and points you to the checkup in your browser at https://vigilbase.com/tools/cloudflare-checkup (see [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.10/files/LOCAL.md)).

Customer provider access requires an `active` or `trialing` Cloudflare service
entitlement for the selected account. Historical/inactive rows and legacy account
pointers cannot grant live access. Historical restrictions on the same customer
and account still tighten zone allowlists. Internal administrative access remains
subject to its existing permission checks.

All commands support `--json`, `--one-url <origin>`, `--timeout <milliseconds>`, and `--help`. JSON mode preserves API response envelopes except inventory filtering and account/zone detail extraction described below. Terminal mode displays IDs for follow-up commands and removes terminal control characters from provider data.

## Selecting a customer, account, or zone

Customer IDs are UUIDs. Cloudflare account and zone IDs are 32 hexadecimal characters. Find these with:

```bash
vigilbase cf accounts
vigilbase cf zones
vigilbase cf workspace --json
```

`--customer-id` explicitly selects a customer; it never grants access to that customer. Customer users can usually omit it when their organization identifies the customer. Internal users should select it for customer-specific operations: One answers accounts, workspace and checkup reads without it with HTTP 400. Analytics, DNS, WAF and speed settings always require it, for every user: One refuses these reads without it, so the CLI stops before sending them. Live zone detail requires it; zone detail without it uses the stored workspace inventory. When One answers 400 to accounts, workspace or checkup reads because the customer is missing, the CLI adds the hint `Vigilbase staff: add --customer-id <uuid>.`

An account or zone positional ID can instead be supplied using `--account-id` or `--zone-id` for commands that take that kind of ID. Supplying both requires identical values. Account-resource commands reject `--zone-id`; DNS, WAF, and speed-settings reject `--account-id` because those APIs scope by zone. `--days` is accepted only for analytics.

## Command grammar

In this table, `C` means `[--customer-id <uuid>]`, `C!` means a required `--customer-id <uuid>`, `A` means `[--account-id <hex-id>]`, and `Z` means `[--zone-id <hex-id>]`. Every command also accepts the common options above.

| Command | Selection | Result |
| --- | --- | --- |
| `cf` / `cf zones` | C A Z | Stored zone inventory; exact account and zone filters |
| `cf zone` | C A Z | Historical alias for inventory when no zone ID is given |
| `cf zone <zone-id>` | C A | Zone detail; live when C is supplied, otherwise stored inventory |
| `cf accounts` | C A | Accessible account inventory including customer and service IDs |
| `cf account <account-id>` | C | One stored account summary |
| `cf workspace [section]` | C A Z | Workspace bootstrap or section data |
| `cf dns <zone-id>` | C! | DNS record IDs, types, names, contents, TTL and proxy state |
| `cf waf <zone-id>` | C! | Rules, expressions, analytics availability and suggestions |
| `cf speed-settings <zone-id>` | C! | Current performance settings; internal access required |
| `cf audit-logs <account-id>` | C | Most recent provider audit events, up to 100 |
| `cf zero-trust <account-id>` | C | Users, Access applications, tunnels and authentication analytics |
| `cf developer-platform <account-id>` | C | Workers, Workers analytics and Pages projects |
| `cf magic-transit <account-id>` | C | Prefixes, routes and traffic analytics |
| `cf analytics --customer-id <uuid>` | A or Z, `[--days <1..30>]` (whole days, digits only; other forms give `--days must be an integer.`) | Usage and traffic analytics; default 7 days |
| `cf checkup [status]` | C A | Setup state and latest completed checkup |
| `cf checkup start` | C A | Starts a persisted account security checkup |
| `cf checkup progress <run-uuid>` | None | Persisted progress events, percentage and status |
| `cf checkup result <run-uuid>` | None | Run details and stored result |

`checkups` aliases `checkup`; `list` and `show` alias checkup `status`; `run` aliases checkup `start`. Progress/result commands use the run UUID's server-enforced access scope and reject customer/account filters.

Workspace sections are `overview`, `reports`, `zones`, `rule-analyzer`, `accounts`, `checkups`, and `settings`. Omitting the section returns customer/service metadata, accessible accounts, selected account/zone and navigation. Available sections depend on server permissions. `settings` is workspace selection/configuration context, not a claim about live zone security settings.

Workspace account/zone arguments select context; a workspace section can still include other accessible inventory. Use `cf zones --account-id ... --zone-id ...` for exact inventory filtering. `cf account` refuses ambiguous account links across customers until `--customer-id` is supplied; it prefers active/trialing service rows among historical duplicates for the same customer. Account and inventory zone detail return `{ "success": true, "data": <selected item> }`.

## Examples

Replace example IDs with IDs from your account inventory:

```bash
vigilbase cf account bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
vigilbase cf zone aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --customer-id cb156546-b6ba-42a9-bdd0-4a09cb156546
vigilbase cf dns aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --customer-id cb156546-b6ba-42a9-bdd0-4a09cb156546 --json
vigilbase cf waf aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --customer-id cb156546-b6ba-42a9-bdd0-4a09cb156546
vigilbase cf zero-trust bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb --json
vigilbase cf developer-platform bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
vigilbase cf magic-transit bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
vigilbase cf audit-logs bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
vigilbase cf workspace reports --customer-id cb156546-b6ba-42a9-bdd0-4a09cb156546
vigilbase cf analytics --customer-id cb156546-b6ba-42a9-bdd0-4a09cb156546 --account-id bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb --days 14
vigilbase cf checkup start --account-id bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb --json
vigilbase cf checkup progress d047b25a-2410-42a0-94f3-a8d6a249ad2b
vigilbase cf checkup result d047b25a-2410-42a0-94f3-a8d6a249ad2b --json
```

## API mapping and effects

Every path below is relative to the configured One origin. `customerId`, `accountId`, and `zoneId` query parameters are omitted when the corresponding optional selection is absent.

| Command | Method and endpoint | Effect |
| --- | --- | --- |
| Unfiltered `zones` | `GET /api/account/cloudflare/zones` | Read stored inventory |
| Filtered `zones`, inventory zone detail | `GET /api/services/cloudflare/workspace/zones?customerId=C&account=A&zone=Z` | Read scoped inventory; CLI applies exact filters |
| Live zone detail | `GET /api/customers/C/cloudflare/zones/Z` | Read provider zone |
| `accounts`, `account`, workspace bootstrap | `GET /api/services/cloudflare/workspace?customerId=C&account=A` | Read workspace |
| Workspace section | `GET /api/services/cloudflare/workspace/SECTION?customerId=C&account=A&zone=Z` | Read section |
| `dns`, `waf` | `GET /api/services/cloudflare/zones/Z/dns` or `/waf`, query `customerId=C` | Read provider records/rules |
| `speed-settings` | `GET /api/cloudflare/zones/Z/speed-settings?customerId=C` | Read provider settings; internal permission checks |
| `audit-logs`, `zero-trust`, `developer-platform`, `magic-transit` | `GET /api/cloudflare/accounts/A/RESOURCE?customerId=C` | Read provider account resource |
| `analytics` | `GET /api/services/cloudflare/analytics?days=N&customerId=C&accountId=A` or `zoneId=Z` | Read usage/provider analytics |
| Checkup status | `GET /api/services/cloudflare/checkups?customerId=C&accountId=A` | Read completed checkup/configuration; `report` is deprecated, read `latestRun.results` |
| Checkup start | `POST /api/services/cloudflare/checkups/start`, JSON `{customerId?, accountId?}` | Starts scanner and persists a run; no DNS/WAF configuration edits |
| Checkup progress | `GET /api/services/cloudflare/checkups/progress?toolRunId=ID` | Read up to 500 persisted events per response |
| Checkup result | `GET /api/tool-runs/ID` | Read stored run; server may claim eligible run ownership for the organization |
| (no command) Checkup PDF | `GET /api/services/cloudflare/checkups/report?toolRunId=ID`, or `?customerId=C&accountId=A` for the latest completed run | Read stored run as the shared PDF report; never starts a scan |

Account audit logs require service-read permissions. Zero Trust, Developer Platform and Magic Transit require deployment-read permissions. Speed settings require internal access plus service/deployment read permissions. One verifies tenant/account/zone bindings for these reads; account-wide reads may be unavailable for grants restricted to individual zones.

## Data availability and failures

The API may return empty audit logs, WAF rules, speed settings or other account data when provider permissions, plan features or provider availability prevent collection. Empty lists do not establish absence of activity or protection. Audit logs use the endpoint's fixed latest-100 window; no CLI pagination or date filtering is offered for that route.

Analytics prefers scoped stored usage when available and otherwise uses provider analytics. Live zone analytics covers the most recent 23 hours regardless of `--days`; account analytics uses the requested period. Zero-valued results can represent unavailable data. JSON mode preserves the API's shape, including either `analytics` or `bandwidth`.

In text mode, `cf checkup result` and `cf checkup` print a readable summary of the stored result instead of its raw fields: the grade and score, the check counts, the account's domains (worst score first, up to 15, with plan, grade and failed, warning and passed counts), the top 8 priorities (each check once, failed before warnings, then by the severity the scanner gave it, with the number of domains it affects and the first line of its recommendation) and the full report link when the result has one. Longer lists end with how many more there are and where to see them, for example `… 94 more findings in the full report (--json lists them all)` (without a report link: `… 94 more findings (--json lists them all)`). These caps are the ones the web report, the PDF and the emails use. On a terminal, the grade, counts and a bar of the checks are coloured and lines fit the width; `NO_COLOR` or `FORCE_COLOR=0` turns colours off. `--json` returns the API envelope unchanged, with every check and field.

The `cf checkup --json` envelope (`GET /api/services/cloudflare/checkups`) carries the latest completed run as `latestRun`, with the stored Cloudflare Checkup result in `latestRun.results`. Its `report` field is deprecated and kept only for scripts written against the earlier envelope; responses name it in the `X-Vigilbase-Deprecated-Fields: report` header. Use `latestRun.results`. `report` is now derived from that stored result: the account, `generatedAt` (the scan time), the grade and score (unlocked results only), `scope` on a zone-scoped checkup, the old `summary` counts, `metadata.dnssecEnabled` and `metadata.wafEnabled`, and per zone its status, plan, grade, score, check counts, `dnssec` and `waf` when those checks ran, and its issues. Each issue keeps `id` (the check ID), `severity` (`critical`, `warning` or `info`, mapped as before), `title`, `description` and `recommendation`, and adds the check's `status` and the scanner's own `checkSeverity`. Checks that could not run are not issues. Fields the stored result cannot answer are omitted rather than estimated: per-zone `dnsRecords`, `firewall`, `paused` and `developmentMode`, and `metadata.firewallProtected` and `metadata.apexConfigured`. `report` is `null` when there is no completed run.

The same run is available as the shared PDF report from `GET /api/services/cloudflare/checkups/report?toolRunId=ID`, or for an account's latest completed run from `GET /api/services/cloudflare/checkups/report?customerId=C&accountId=A` (account administrators). The account form never starts a scan: without a completed run it answers 404 `No completed checkup for this account; start one via POST /checkups/start`. `POST /api/services/cloudflare/checkups/analyze` takes `{ "toolRunId": ID }`; the earlier body, a checkup report, is refused with 400.

Checkup progress reads once and does not poll automatically. Run the command again to refresh. Status describes the latest completed run; use its returned run ID or the ID from `start` with `progress` to inspect an in-progress scan. `result` verifies that the selected run is a Cloudflare checkup and reports when no result is available yet.

Malformed IDs, conflicting selections, extra positional arguments and unsupported scope combinations fail before a network request. Authentication, permission, HTTP and explicit `success:false` API failures return a nonzero exit status. Provider configuration writes, token management, cache purge, account deletion and DNS edits are not exposed by this command group.