@vigilbase/cli 0.1.1 → 0.1.3

package/CLOUDFLARE.md

@@ -0,0 +1,112 @@
+# Cloudflare CLI reference
+
+`vigilbase cf` and `vigilbase cloudflare` use the authenticated Vigilbase One API. Run `vigilbase login` first. Your organization, permissions, customer links, and allowed zones determine access. The CLI never requires a Cloudflare API key.
+
+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. Analytics always requires it. Live zone detail requires it; zone detail without it uses the stored workspace inventory.
+
+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>]`, `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 --json
+vigilbase cf waf aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+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.
+
+## Verification
+
+`pnpm --filter @vigilbase/cli test` runs command contract tests, including tenant filters, exact paths, bearer authentication, rejected input, permission failures and terminal text handling. Cloudflare fixtures in `scripts/fixtures/cloudflare.mjs` cover every command and workspace section for the compiled CLI end-to-end harness. These fixtures execute against a local HTTP server; the checkup-start case never contacts production.

package/COMMANDS.md

@@ -0,0 +1,147 @@
+# Vigilbase CLI command reference
+
+The CLI uses public scanner APIs on `vigilbase.com` and authenticated APIs on
+`one.vigilbase.com`. Use `vigilbase <command> --help` or
+`vigilbase help <command>` for built-in help. Examples below omit optional
+`--json`, which every command supports.
+
+## References
+
+| Area | Complete command and API reference |
+| --- | --- |
+| Cloudflare | [CLOUDFLARE.md](./CLOUDFLARE.md) |
+| Security | [SECURITY.md](./SECURITY.md) |
+| Customers, organizations, monitoring, support | [ONE.md](./ONE.md) |
+| Authentication, setup, network troubleshooting | [README.md](./README.md) |
+
+The references identify supported operations, filters, response/pagination
+behavior, API endpoints, and access requirements. They describe the CLI's
+supported API surface, not every internal endpoint in the monorepo.
+
+## Global options
+
+| Flag | Meaning |
+| --- | --- |
+| `--json`, `-j` | JSON on stdout; progress/browser instructions on stderr |
+| `--help`, `-h` | Help for the named command; makes no API request |
+| `--version`, `-V` | Package version |
+| `--one-url <origin>` | One origin; default `https://one.vigilbase.com` |
+| `--base-url <origin>` | Public origin; default `https://vigilbase.com` |
+| `--timeout <ms>` | Per-request timeout, integer 1–2147483647; default 60000 |
+| `--client-id <id>` | Device authorization client; default `vigilbase-cli` |
+
+Origins must be HTTP(S) URLs without credentials, paths, query strings, or
+fragments. One requires HTTPS, except HTTP loopback development. `--customer-id` is a command-specific One customer UUID; it does not
+change the session's permissions. API-backed reads may still return 403 when the
+signed-in role lacks access. Unknown flags, unsupported command-specific flags
+(including scope flags), and extra positional arguments fail before API access.
+`--style` applies only to `badge`.
+
+## Authentication
+
+| Command | Options and behavior | One API |
+| --- | --- | --- |
+| `login` | Device authorization; `--no-open` for remote terminals | POST `/api/auth/device/code`, POST `/api/auth/device/token` |
+| `login --token-stdin` | Validate and save a token piped from a secret manager; input is bounded and never echoed | GET `/api/auth/get-session` |
+| `login --token <bearer>` | Legacy input; discouraged because arguments can appear in process lists/history. `VIGILBASE_ONE_TOKEN` is also supported; neither combines with `--token-stdin` | GET `/api/auth/get-session` |
+| `whoami` | Verify the saved session; signed-out is a successful status query | GET `/api/auth/get-session` when a usable token exists |
+| `logout` | Remove local credentials; does not revoke the server session | Local only |
+| `doctor` | Independently check public catalog and One session connectivity | GET `/api/agent/tools`, GET `/api/auth/get-session` |
+
+Tokens are saved atomically with owner-only file permissions and tied to their
+issuing One origin. See README for config directory overrides and certificate
+trust. Login polling handles pending approval, denial, expiry, and transient
+transport failures. Access tokens are never included in successful CLI output.
+
+## Public scanners and authenticated scans
+
+| Command | Options | API |
+| --- | --- | --- |
+| `list` (alias `tools`) | Lists the public catalog and authenticated scanner names | GET `/api/agent/tools` |
+| `run <tool> <target>` | `--via public\|one`; `--public` forces the public API | POST `/api/agent/tools/<tool>/execute` or One POST `/api/tools/<tool>/execute` |
+| `headers <url>` | Shortcut for `run security-headers`; same routing options | Same as `run` |
+| `email <domain>` | Shortcut for `run email-security`; same routing options | Same as `run` |
+| `describe <tool>` | `--no-skill` skips fetching skill Markdown | Catalog plus the tool's published skill URL |
+| `skill <tool>` | Prints the complete published skill; JSON includes URL/content | Catalog plus the tool's skill URL |
+| `badge <domain>` | `--style default\|compact\|mini` | Generates a public badge URL locally |
+
+Public tools: `security-headers`, `email-security`. Login-required tools:
+`website-security`, `react2shell`, `fortibleed-check`. Public scans stay on the
+public API unless explicitly routed to One. A saved login alone does not change
+that choice. `--public` and `--via one` cannot be combined.
+
+## Account and billing
+
+| Command | Aliases/options | One API |
+| --- | --- | --- |
+| `account` | `show`, `me`, `overview` | GET `/api/account` |
+| `account services` | `service` | GET `/api/account/services` |
+| `account org` | `organization`, `members` | GET `/api/account/organization` |
+| `account endpoints` | `endpoint` | GET `/api/account/endpoints` |
+| `account sessions` | `session` | GET `/api/account/sessions` |
+| `account invites` | `invitations`; optional `list` or `ls` | GET `/api/auth/orgs/invitations` |
+| `account invites create` | `add` alias; `--email <email>`, `--role <role>` (default member), required `--confirm` | POST `/api/auth/orgs/invite` |
+| `account billing` | Delegates to billing commands | Same as billing |
+| `billing` | `summary`, `show`, `status` | GET `/api/account/billing` |
+| `billing portal` | `open`; `--no-open` prints the portal URL without opening a browser | POST `/api/billing/portal` |
+
+Invitation creation sends an invitation; billing portal creation starts a Stripe
+portal session. These are explicit actions. Billing data comes from One's Stripe
+integration; the CLI does not persist invoices or payment information locally.
+
+Invitations validate the email and role locally and generate a fresh UUID
+`operationId` for each invocation. Accepted roles: `admin`, `member`, `readonly`,
+`partner_owner`, `partner_sales`, `partner_operations`, `partner_finance`,
+`partner_readonly`, `billing_only`, and `sales_only`. The API still checks whether
+the caller may assign the chosen role. `--confirm` is required.
+Portal URLs are validated against the HTTPS Stripe billing host before JSON
+output, printing, or opening; Windows requires manual opening.
+
+## Run history and account Watchdog
+
+| Command | Options/aliases | One API |
+| --- | --- | --- |
+| `runs` | `list`, `ls`; `--tool <name>`, `--limit <n>` (1–200, default 50) | GET `/api/tool-runs` |
+| `runs get <id>` | `show <id>` or `runs <UUID>` | GET `/api/tool-runs/<id>` |
+| `runhistory` | Alias of the entire `runs` group | Same as runs |
+| `watchdog` | `list`, `targets`, `status` | GET `/api/account/watchdog/targets` |
+| `watchdog scans` | `scan`; `--target-id <UUID>`, `--limit <n>` (1–100, default 20) | GET `/api/account/watchdog/scans` |
+
+Customer-specific Watchdog and monitoring views are documented in ONE.md.
+
+## Output, effects, and testing
+
+Exit codes: **0** success, **1** validation/API/network failure, **2** HTTP 429
+rate limiting. A completed scan whose result is unsuccessful also exits 1.
+`whoami` being signed out is not an API failure. A healthy `doctor` does not
+require login. API error JSON retains status, code, and retry delay when available.
+
+New security/customer operations preserve JSON response envelopes and pagination
+fields. Cloudflare inventory commands may apply the explicitly requested account
+or zone filter locally as well as sending it to One; zone detail returns the
+selected object. See each reference for details. Text output is for people; use
+JSON for automation and evidence export.
+
+Provider credentials, signed delegation claims, internal bearer tokens, and
+organization-authority overrides are never CLI inputs. New commands use named
+One routes. Webhooks, cron/admin repair endpoints, interactive OAuth handoffs,
+streaming/binary downloads, and endpoints that auto-provision on GET are outside
+this expansion. Remediation effects requiring durable approval/receipt workflows
+remain in their existing supported One/Vigil flows.
+
+```bash
+pnpm --filter @vigilbase/cli check
+# Includes typecheck, unit tests, production build, login lifecycle smoke,
+# and every fixture-listed command over HTTP in both JSON and text modes.
+
+VIGILBASE_BASE_URL=https://vigilbase.com \
+  VIGILBASE_SMOKE_ARTIFACTS="$PWD/.context/cli-live-smoke" \
+  pnpm --filter @vigilbase/cli smoke:e2e
+```
+
+The command suite uses temporary local HTTP fixtures and credentials; all writes
+stay local. It checks exact methods/paths/filters/bodies, bearer handling, output,
+permission failures, rate limits, malformed responses, and documentation presence.
+The live smoke separately checks public services and actual public scans. Real
+customer-data access additionally requires a valid One session and suitable role;
+local fixtures do not prove production provider configuration or data health.

package/ONE.md

@@ -0,0 +1,99 @@
+# Vigilbase One CLI reference
+
+Log in with `vigilbase login`. These command groups use the configured One origin (`--one-url`, `VIGILBASE_ONE_URL`, default `https://one.vigilbase.com`) and the saved device-login credential. Every operation in this reference sends GET. Customer, organization, role, and integration access remains enforced by One; selecting an ID never grants access.
+
+Use `--json` to retain the complete API response and pagination metadata. Plain/pretty output shows all fields as an indented tree, including null/unknown metrics, degraded status, totals, and cursors. `--timeout <milliseconds>` controls request timeouts. No command automatically follows pagination. Only documented flags are accepted; unrelated flags fail before authentication or network requests.
+
+```sh
+vigilbase customers list --json
+vigilbase customers summary CUSTOMER_UUID
+vigilbase customers services CUSTOMER_UUID
+vigilbase monitoring status CUSTOMER_UUID --light
+vigilbase monitoring history CUSTOMER_UUID --range 7d --region ams
+vigilbase orgs members
+vigilbase support tickets --all --limit 100
+```
+
+Replace uppercase placeholders with IDs from the corresponding list. Customer, report, Vigil investigation, and monitoring target IDs must be UUIDs. Organization IDs may contain letters, digits, underscores, and hyphens (maximum 256 characters).
+
+## Customers
+
+For partner-linked customers, invoice and subscription reads are restricted to
+subscription IDs on that customer's own or linked revenue-active contracts.
+Sibling customers never receive the partner's account-wide Stripe list. Missing
+contract scope fails closed; no allowed subscriptions returns an empty list.
+
+`vigilbase customers` defaults to `list`; `ls` is an alias for `list`. Pass customer IDs positionally for this group, rather than `--customer-id`. The table's `C` prefix means `/api/customers/{customer-id}`.
+
+| Command after `vigilbase customers` | Flags | One GET endpoint |
+| --- | --- | --- |
+| `list` | None | `/api/customers` |
+| `show <customer-id>` | None | `C` |
+| `summary <customer-id>` | None | `C/summary` |
+| `services <customer-id>` | None | `C/service-records` |
+| `endpoints <customer-id>` | None | `C/endpoints` |
+| `contacts <customer-id>` | None | `C/contacts` |
+| `organization <customer-id>` | None | `C/organization` |
+| `watchdog-targets <customer-id>` | None | `C/watchdog/targets` |
+| `watchdog-scans <customer-id>` | `--limit 1..100`, `--offset 0..1000000`, `--target-id UUID` | `C/watchdog/scans?limit=&offset=&target_id=` |
+| `reports <customer-id>` | `--limit 1..100` | `C/recon/reports?limit=` |
+| `report <customer-id> <report-id>` | None | `C/recon/reports/{report-id}` |
+| `investigations <customer-id>` | `--limit 1..100`, `--cursor TEXT`, `--before ISO`, `--issue-id TEXT` | `C/vigil/investigations?limit=&cursor=&before=&issueId=` |
+| `investigation <customer-id> <investigation-id>` | `--revision 1..2147483647` | `C/vigil/investigations/{investigation-id}?revision=` |
+| `contracts <customer-id>` | `--status draft\|pending\|active\|expired\|terminated` | `C/contracts?status=` |
+| `billing <customer-id>` | None | `C/billing` |
+| `invoices <customer-id>` | `--limit 1..100`, `--status draft\|open\|paid\|uncollectible\|void` | `C/stripe/invoices?limit=&status=` |
+| `subscriptions <customer-id>` | None | `C/stripe/subscriptions` |
+| `projects <customer-id>` | None | `C/projects` |
+
+Unspecified query parameters are omitted. API defaults: Watchdog scans limit 20/offset 0, Recon reports limit 12, investigations limit 50, invoices limit 50. For Watchdog scans, advance `--offset` using the response's `total`. For investigations, pass `data.nextCursor` back to `--cursor` (maximum 512 characters); `--before` must be an ISO timestamp with timezone and `--issue-id` is at most 256 characters. `--before` and `--cursor` are mutually exclusive. The API validates opaque cursors. Omitting `--revision` loads the latest investigation revision. Invoice responses preserve `has_more`, but this One endpoint has no cursor option; the CLI cannot fetch subsequent invoice pages beyond the requested limit.
+
+Customer discovery follows the API's internal, customer, and partner visibility. Detail/summary/contact/organization/Recon reads require customer read access; endpoints/services require service read access. Watchdog routes require monitoring/tool permissions as enforced by the API. Contracts and billing reads require their respective permissions. Linked project reads are restricted to internal operators with service read access. Vigil investigation reads require internal Vigil investigation permission and the Vigil UI feature to be enabled; disabled deployments return 404. Stripe resources are fetched by One from Stripe and are not persisted by the CLI.
+
+The service command uses the dashboard's `/service-records` API. `/customers/{id}/services` and `/customers/search` require a separate Vigil machine credential and are intentionally not exposed. The customer bootstrap `/customers/me` endpoint can provision a customer, so use existing `vigilbase account` to inspect the current customer's context. Generating Watchdog AI insights, re-running investigations, syncing providers, creating reports, and other effectful APIs are not invoked by these read commands.
+
+## Organizations
+
+`vigilbase orgs` defaults to `list`; `ls` is an alias.
+
+| Command after `vigilbase orgs` | One GET endpoint | Access |
+| --- | --- | --- |
+| `list` | `/api/user/organizations` | Current user's organization memberships |
+| `show <organization-id>` | `/api/organizations/{id}` | Internal `read:admin` |
+| `members` | `/api/auth/orgs/members` | Current organization; organization permission checks |
+| `members <organization-id>` | `/api/organizations/{id}/members` | Internal `read:admin` |
+| `roles` | `/api/auth/orgs/permission-roles` | Current organization management access |
+
+No operation-specific flags. `roles` returns assignable role templates and permission groups; it does not list each member's roles (use `members`). These commands do not change the active organization attached to the login session. Selecting an organization ID requires the explicit internal API permission above.
+
+## Monitoring
+
+`vigilbase monitoring` defaults to `health`. All endpoints require `read:monitoring`; customer routes and metric IDs also undergo tenant access checks.
+
+| Command after `vigilbase monitoring` | Flags | One GET endpoint |
+| --- | --- | --- |
+| `health` | None | `/api/monitoring/health` |
+| `probes` | None | `/api/monitoring/probes` |
+| `probe-health` | None | `/api/monitoring/probes/health` |
+| `metrics <target-id>...` | None; 1..50 UUID arguments | `/api/monitoring/metrics?target_ids=UUID,UUID` |
+| `targets <customer-id>` | None | `/api/customers/{id}/monitoring/targets` |
+| `status <customer-id>` | `--light` | `/api/customers/{id}/monitoring/status?light=true` |
+| `history <customer-id>` | `--range 24h\|7d\|30d`, `--region CODE`, `--target-id UUID` | `/api/customers/{id}/monitoring/history?range=&region=&target_id=` |
+
+`probes` exposes the internal fleet inventory and requires internal operator access. `probe-health` reports observed health with database fallback. Duplicate metrics target IDs are removed; all requested targets must pass One's access checks. `--light` skips latency and SSL provider reads in status. History defaults to `7d`. Supported regions: `ams nyc lon sgp iad sfo fra dub tok syd cpt gru dxb ewr lhr jnb atl blr bom cdg del dfw hnl icn itm lax mad man mel mex mia mxp nrt ord sao scl sea sjc sto tlv waw yto`.
+
+A successful health response may describe an unconfigured backend or unknown probes. Inspect `configured`, `connected`, `status`, `metrics_error`, `has_data`, and `partial`; exit zero means the API request succeeded, not that infrastructure is healthy. Provider-unavailable HTTP errors remain failures with nonzero exit status.
+
+## Support
+
+```sh
+vigilbase support tickets [--all] [--limit 1..100] [--json]
+```
+
+`vigilbase support` also defaults to `tickets`. Maps to GET `/api/support/tickets?includeAll=true&limit=N`; omitted flags omit their query parameters. Requires `support:access`. The API identifies the current organization and its Pylon account. Open tickets are returned by default; `--all` includes closed tickets. Limit defaults to 50. An unlinked account returns an empty list with the API's explanation. `hasMore` is preserved, but this API exposes no cursor pagination. The API may rate-limit requests or return 503 when Pylon is unavailable.
+
+## Related commands and validation
+
+See [README.md](README.md) for login, account, billing, public scanners, run history, Watchdog, Cloudflare (`cf`/`cloudflare`), and security command references. The read operations above do not replace the existing explicitly confirmed write commands.
+
+The test suite validates argument rejection, auth failures, tenant ID encoding, API errors, response rendering, and read transport. `pnpm --filter @vigilbase/cli smoke:commands` builds the actual binary and exercises each named operation against independently authored local HTTP fixtures in `scripts/fixtures/one.mjs`. This verifies the binary, argument parser, credential store, HTTP request, and JSON/text output without writing production data. These fixtures do not assert deployed provider availability or that a particular production user has permissions.

package/README.md

@@ -1,89 +1,223 @@
 # @vigilbase/cli
 
-Terminal client for Vigilbase — public scanners and tools without login, plus Vigilbase One after device authorization.
+Vigilbase public scanners and Vigilbase One customer, security, Cloudflare,
+monitoring, organization, and support operations from the terminal.
 
-Binary name: **`vigilbase`**
+## Install and sign in
 
-```bash
-vigilbase help
-vigilbase run security-headers https://vigilbase.com
-vigilbase login
-vigilbase account --json
-```
-
-## Install
+Node 20+ is required. Node 22.19+ or Node 24.5+ enables automatic system
+certificate trust.
 
 ```bash
 npm install -g @vigilbase/cli
-# or
-pnpm add -g @vigilbase/cli
-
+# or: pnpm add -g @vigilbase/cli
 vigilbase help
-vigilbase list --json
+vigilbase login
+vigilbase whoami
 ```
 
-Without a global install:
+Without global installation: `npx @vigilbase/cli help`. From this monorepo:
+`pnpm vigilbase help`; build with `pnpm build:cli` and link with
+`pnpm link:vigilbase`.
 
-```bash
-npx @vigilbase/cli help
-npx @vigilbase/cli run email-security vigilbase.com --json
-```
+Local link/unlink scripts only recognize symlinks resolving to this checkout's
+`dist/bin.js`. Regular binaries, foreign installations, and dangling links are
+preserved; resolve a conflicting installation yourself before linking.
 
-## Public tools (no auth)
+## Complete command documentation
 
-| Command | Purpose |
+| Reference | Coverage |
 | --- | --- |
-| `vigilbase list` | Public catalog + auth-required tool names |
-| `vigilbase run <tool> <target>` | Execute a scan |
-| `vigilbase headers <url>` | Shortcut for `security-headers` |
-| `vigilbase email <domain>` | Shortcut for `email-security` |
-| `vigilbase describe` / `skill` | Tool metadata + skill markdown |
-| `vigilbase badge <domain>` | Public badge URL |
-| `vigilbase doctor` | Connectivity + auth status |
+| [COMMANDS.md](./COMMANDS.md) | Core commands, aliases, global flags, API mappings, authentication, output, testing |
+| [CLOUDFLARE.md](./CLOUDFLARE.md) | Accounts, zones, DNS, WAF, analytics, Zero Trust, Workers/Pages, audit, checkups |
+| [SECURITY.md](./SECURITY.md) | Incidents, logs, intelligence, analytics, assets, connections, policies, notifications, reports |
+| [ONE.md](./ONE.md) | Customer records/billing/reports/investigations, organizations, monitoring, support |
+
+These references ship with the npm package. Built-in help is available through
+`vigilbase <command> --help` or `vigilbase help <command>`.
 
-Public allowlist: `security-headers`, `email-security`.
+## Examples
 
-## Auth-required tools (after login)
+Public tools require no login:
 
 ```bash
-vigilbase login
-vigilbase run website-security vigilbase.com
-vigilbase run react2shell https://app.example.com
-vigilbase run fortibleed-check example.com
+vigilbase list
+vigilbase headers https://vigilbase.com
+vigilbase email vigilbase.com --json
+vigilbase describe security-headers
+vigilbase badge vigilbase.com --style compact
 ```
 
-## Account & One management (login required)
+Public scanners are `security-headers` and `email-security`. Authenticated
+scanners are `website-security`, `react2shell`, and `fortibleed-check`:
 
 ```bash
+vigilbase run website-security example.com --json
 vigilbase account
-vigilbase account services
-vigilbase account org
-vigilbase account endpoints
-vigilbase account sessions
-vigilbase account invites
-vigilbase account invites create --email user@example.com --confirm
-vigilbase billing summary
-vigilbase billing portal
+vigilbase customers list --json
+vigilbase customers summary <customer-uuid>
+vigilbase orgs list
+vigilbase monitoring health
+vigilbase support tickets
 vigilbase runs list
-vigilbase runs get <id>
+```
+
+Cloudflare IDs come from the accessible inventory:
+
+```bash
+vigilbase cf accounts
 vigilbase cf zones
-vigilbase cf checkup status
-vigilbase watchdog list
+vigilbase cf dns <zone-id>
+vigilbase cf waf <zone-id> --json
+vigilbase cf zero-trust <account-id>
+vigilbase cf developer-platform <account-id>
+vigilbase cf analytics --customer-id <customer-uuid> --zone-id <zone-id> --days 7
+vigilbase cf checkup progress <run-uuid>
+```
+
+Security uses the same tenant and permission boundary as One's dashboard:
+
+```bash
+vigilbase security
+vigilbase security incidents --severity high --json
+vigilbase security incidents show <incident-uuid>
+vigilbase security logs --search 'failed login' --limit 50
+vigilbase security assets
+vigilbase security intel ip 203.0.113.8
+vigilbase security analytics security-analysis --hours 24
+vigilbase security zero-trust device-health --hours 24
+vigilbase security notifications
+vigilbase security audit --limit 50
 ```
 
-Every command supports `-j` / `--json`. Async work shows a spinner on TTY (disabled for `--json`, CI, and non-TTY).
+Customer users inherit their organization scope. Internal operators must add
+`--customer-id <customer-uuid>` for security views. Cloudflare analytics requires
+that customer ID as well. Other customer-specific groups use positional customer
+UUIDs. Flags select records; One still decides whether the session can access them.
 
-## Agent-friendly mode
+After reviewing an incident, a status update is available explicitly:
 
 ```bash
-vigilbase list --json
-vigilbase run security-headers https://vigilbase.com --json
-vigilbase account --json
-vigilbase runs list --json
+vigilbase security incidents update <incident-uuid> acknowledged \
+  --note 'Investigating with the customer' --confirm
 ```
 
+Other status updates are `mitigating`, `resolved`, and `false_positive`.
+`--confirm` acknowledges the caller's intent; it does not grant permission or
+approve provider remediation. API mutations are not automatically retried.
+See command references for the other explicit effects (invitation creation,
+billing portal sessions, scans, and checkup starts).
+
+## Automation and output
+
+Every command supports `-j` / `--json`. JSON goes to stdout; progress and browser
+instructions go to stderr. Progress animations are disabled for JSON, CI, and
+non-TTY output. Preserve JSON pagination fields when fetching subsequent pages;
+list commands do not silently fetch every page. New text views display complete
+identifiers. All human-readable output removes terminal control sequences and
+bidirectional overrides, including identities, tool results, skills, and errors.
+JSON preserves successful response data with control characters escaped. Default
+errors omit server response bodies and messages, retaining safe status, error
+code, and retry metadata.
+
 | Exit code | Meaning |
 | --- | --- |
-| `0` | Success |
-| `1` | Error |
+| `0` | Success (including a signed-out `whoami`) |
+| `1` | Validation, API, network, or unsuccessful scan result |
 | `2` | Rate limited (`HTTP 429`) |
+
+Commands use named One APIs and existing server authorization. They do not accept
+Cloudflare/provider secrets, delegated identity claims, or an arbitrary upstream
+URL. Billing records are fetched on demand and not persisted by the CLI.
+
+## Login and configuration
+
+`login` opens a browser and waits for device approval. On remote terminals, run
+`vigilbase login --no-open`, then open the displayed URL in a signed-in browser.
+For an existing One session token, pipe it from your secret manager into
+`vigilbase login --token-stdin`. Input must contain one token and is never echoed.
+The older `--token <bearer>` and `VIGILBASE_ONE_TOKEN` inputs remain supported;
+command arguments may be visible in process listings or shell history. Do not
+combine either with `--token-stdin`. Login validates the token before saving it.
+
+The credential directory must be an absolute path, owned by the current user,
+and mode `0700`; `credentials.json` must be an owned regular file with mode
+`0600`. Symlinks, hard links, and unsafe parent directories are rejected. Existing
+files with broader permissions require `chmod 700 <config-directory>` and
+`chmod 600 <config-directory>/credentials.json`. Only the access token and session
+metadata are saved; unused refresh tokens are never persisted.
+
+Credentials are stored atomically in `~/.config/vigilbase/credentials.json` with
+owner-only file permissions. `XDG_CONFIG_HOME` or `VIGILBASE_CONFIG_DIR` can change
+the location. Tokens are restricted to their issuing One origin. Legacy credential
+files remain valid for production only; re-login for a custom One origin.
+`whoami` validates the live session. `logout` removes the local credential file.
+
+| Option | Environment variable | Default |
+| --- | --- | --- |
+| `--base-url <origin>` | `VIGILBASE_BASE_URL` | `https://vigilbase.com` |
+| `--one-url <origin>` | `VIGILBASE_ONE_URL` | `https://one.vigilbase.com` |
+| `--client-id <id>` | `VIGILBASE_CLIENT_ID` | `vigilbase-cli` |
+| `--timeout <ms>` | — | `60000` per request |
+
+Origins must be HTTP(S) URLs without paths, credentials, or queries. Authenticated
+One origins require HTTPS. HTTP is allowed only for loopback development
+(`localhost`, `127.0.0.0/8`, or `::1`). This applies to device authorization,
+explicit tokens, and saved sessions. API redirects are refused.
+`VIGILBASE_API_URL` and `VIGILBASE_PUBLIC_URL` are legacy public-origin aliases,
+used after `VIGILBASE_BASE_URL` when no explicit flag is supplied.
+`VIGILBASE_CLI_NO_OPEN=1` disables automatic browser opening.
+
+Billing portal URLs must use HTTPS on `billing.stripe.com`. Windows prints URLs
+for manual opening; URL data never passes through `cmd /c start`. Device login
+always uses the configured One origin's `/device` page.
+
+Catalog skill downloads are restricted to HTTPS
+`vigilbase.com/agent-skills/<name>.md` (also `www.vigilbase.com`). Custom API
+origins cannot expand this allowlist. DNS results must all be public; the TLS
+connection is pinned to a checked address. Redirects are refused. Skill documents
+are limited to 256 KiB; API response bodies are limited to 8 MiB, with timeouts
+covering body reads.
+
+## Troubleshooting
+
+`vigilbase doctor --json` independently checks the public catalog and One session
+endpoint. A signed-out One response counts as reachable; failed checks identify
+the endpoint and cause a nonzero exit. DNS, TLS, connection, and timeout failures
+include actionable diagnostics.
+
+The executable automatically adds OS-trusted certificates on Node 22.19+ and
+Node 24.5+ while preserving bundled roots and `NODE_EXTRA_CA_CERTS`. This supports
+private CAs trusted in macOS Keychain or the system trust store. See
+[Node's TLS documentation](https://nodejs.org/docs/latest-v22.x/api/tls.html#tlssetdefaultcacertificatescerts).
+
+For an older installed CLI reporting `fetch failed` / `SELF_SIGNED_CERT_IN_CHAIN`,
+a recent Node 22 runtime supports this workaround:
+
+```bash
+NODE_OPTIONS="${NODE_OPTIONS:+$NODE_OPTIONS }--use-system-ca" vigilbase login
+```
+
+For a private CA outside the system store, configure
+`NODE_EXTRA_CA_CERTS=/path/to/trusted-ca.pem` before launch. Certificate validation
+remains enabled. Use `--timeout` for slower queries; some security analytics APIs
+have a longer server budget than the default CLI timeout.
+
+## Development and verification
+
+```bash
+pnpm --filter @vigilbase/cli check
+pnpm --filter @vigilbase/cli smoke:commands
+```
+
+`check` runs typecheck, unit tests, production build, the device-login lifecycle
+suite, the compiled-command HTTP suite, and security subprocess regressions. Fixtures cover every supported
+operation in both JSON and text, with exact methods, paths, query filters, bearer
+headers, bodies, error exits, and included documentation. Fixtures use temporary
+credentials and a loopback server; simulated mutations never touch production.
+
+The separate `smoke:e2e` script runs real public scanners. Configure
+`VIGILBASE_BASE_URL` and `VIGILBASE_SMOKE_ARTIFACTS` as shown in COMMANDS.md.
+Authenticated production verification requires a valid One session and appropriate
+permissions. A passing local fixture does not establish provider availability or
+production customer-data health.