@vigilbase/cli/CLOUDFLARE.md

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

# 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 and uploads after you confirm. 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.3/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>]` | 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 |
| 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 |

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`.

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.