@vigilbase/cli/ONE.md

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

# Vigilbase One CLI reference

Log in with `vigilbase login` (signing in isn't supported on Windows yet). These command groups use the configured One origin (`--one-url`, `VIGILBASE_ONE_URL`, default `https://one.vigilbase.com`) and your saved sign-in. 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
vigilbase support tickets --customer-id CUSTOMER_UUID
```

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] [--customer-id <uuid>] [--json]
```

`vigilbase support` also defaults to `tickets`. Maps to GET `/api/support/tickets?includeAll=true&limit=N&customerId=UUID`; omitted flags omit their query parameters. Requires `support:access`. Without `--customer-id`, the API uses the current organization's customer and its Pylon account. Vigilbase staff must choose the customer with `--customer-id <uuid>` (a UUID from `vigilbase customers list`); One checks your access to it. Without it, One answers HTTP 400 and the CLI prints `Request failed (HTTP 400).` with the hint `Vigilbase staff: add --customer-id <uuid>.` Open tickets are returned by default; `--all` includes closed tickets. Limit defaults to 50. An account with no customer or no Pylon link 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](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/README.md) for sign-in and configuration, [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/COMMANDS.md) for account, billing, public scanners, run history and Watchdog, [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/CLOUDFLARE.md) for `cf`/`cloudflare`, and [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/SECURITY.md) for security commands. The read operations above do not replace the existing explicitly confirmed write commands.