@vigilbase/cli/README.md

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

# @vigilbase/cli

Vigilbase public security scanners, the Cloudflare Checkup, and Vigilbase One
customer, security, Cloudflare, monitoring, organization and support operations
from the terminal.

## Install

Node.js 20 or newer is required. `cloudflare-checkup` needs Node.js 22.18 or
newer, because it runs Cloudflare's `cf` under the same Node. Node 22.19+ and
24.5+ also trust your operating system's certificates automatically (see
[Troubleshooting](#troubleshooting)).

```bash
npm install -g @vigilbase/cli     # or: pnpm add -g @vigilbase/cli
vigilbase help
```

Without installing: `npx @vigilbase/cli help`. If you see
`Unknown command "cloudflare-checkup"`, an older global install is answering
instead (see [Troubleshooting](#troubleshooting)).

Public tools and the Cloudflare Checkup work without signing in. Vigilbase One
commands need `vigilbase login` (see [Sign-in](#sign-in)). Signing in isn't
supported on Windows yet; public tools and `cloudflare-checkup` still work there.

## Documentation

| Reference | Covers |
| --- | --- |
| [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/COMMANDS.md) | Core commands, aliases, global options, API mapping, sign-in, output |
| [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/CLOUDFLARE.md) | Accounts, zones, DNS, WAF, analytics, Zero Trust, Workers/Pages, audit, checkups |
| [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/SECURITY.md) | Incidents, logs, intelligence, analytics, assets, connections, policies, notifications, reports |
| [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/ONE.md) | Customer records, billing, reports, investigations, organizations, monitoring, support |
| [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/LOCAL.md) | `cloudflare-checkup`: verifies your work email, collects your Cloudflare configuration on your machine with Cloudflare's `cf` and uploads it after you confirm |

These files ship with the package. Built-in help: `vigilbase <command> --help`
or `vigilbase help <command>`; `vigilbase help <tool>` shows how to run a tool.

## Examples

Public tools, no sign-in:

```bash
vigilbase list
vigilbase headers https://vigilbase.com
vigilbase email vigilbase.com --json
vigilbase describe security-headers
vigilbase badge vigilbase.com --style compact
```

The public scanners are `security-headers` and `email-security`.
`website-security`, `react2shell` and `fortibleed-check` run through Vigilbase
One and need a sign-in:

```bash
vigilbase login
vigilbase run website-security example.com --json
vigilbase account
vigilbase customers list --json
vigilbase customers summary <customer-uuid>
vigilbase orgs list
vigilbase monitoring health
vigilbase support tickets
vigilbase runs list
```

Cloudflare IDs come from the inventory you can access:

```bash
vigilbase cf accounts
vigilbase cf zones
vigilbase cf dns <zone-id> --customer-id <customer-uuid>
vigilbase cf waf <zone-id> --customer-id <customer-uuid> --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
```

Customer users inherit their organization's scope. Internal operators add
`--customer-id <customer-uuid>` for security views and support tickets.
Everyone adds it to `cf analytics`, `cf dns`, `cf waf` and `cf speed-settings`.
Other customer-specific commands take the customer UUID as an argument.
Flags select records; One still decides whether your session can see them.

After reviewing an incident, you can update its status explicitly:

```bash
vigilbase security incidents update <incident-uuid> acknowledged \
  --note 'Investigating with the customer' --confirm
```

Other statuses are `mitigating`, `resolved` and `false_positive`. `--confirm`
states your intent; it does not grant permission or approve provider
remediation. API changes are never retried automatically. The references list
the other explicit actions (sending invitations, opening a billing portal
session, running scans and starting checkups).

## Cloudflare Checkup on your machine

```bash
npx @vigilbase/cli cloudflare-checkup
```

This one command (also `vigilbase cloudflare-checkup` or
`vigilbase local cloudflare-checkup`) runs the Vigilbase Cloudflare Checkup
on your machine with Cloudflare's own `cf` CLI. It needs no Vigilbase sign-in.
It asks for your work email and vigilbase.com emails you a 6-digit code to
enter. It then installs cf if needed (it asks first), signs in to Cloudflare
read-only, lets you choose the account, collects, and uploads the snapshot only
after you confirm. It prints the results link and opens it in your browser on
macOS and Linux; the results also go to your verified email.

cf owns your Cloudflare login: this CLI never reads, prints, stores or uploads
it. Your email address goes to vigilbase.com only so it can send the code; the
CLI never prints, logs or stores it and shows only the masked `j***@acme.com`.
In a terminal the steps show as an interactive timeline; pipes, CI,
`TERM=dumb` and `--json` get plain lines.

Local checkups work while vigilbase.com has them switched on. The CLI checks
before it asks for your email. When they are off, it stops with
`Local checkups aren't available right now.` and points you to the checkup in
your browser, <https://vigilbase.com/tools/cloudflare-checkup>, which uses a
read-only Cloudflare API token instead. When you are done:

```bash
npx @vigilbase/cli cloudflare-checkup logout   # removes the read-only cf login and the cf it installed
```

See [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/LOCAL.md) for
every step, what is uploaded and the error codes.

## Public tools and sign-in

- **Public scans never depend on your sign-in.** `headers`, `email` and
  `run security-headers|email-security` call the public API anonymously and
  never read your saved sign-in, so an expired, broken or unreachable sign-in
  cannot make them fail. `--public` and `--via public` force the public API for
  any tool.
- **One-only scans need a sign-in.** `website-security`, `react2shell`,
  `fortibleed-check` and any run with `--via one` go through Vigilbase One.
  Without a usable sign-in they stop with
  ``This tool needs a Vigilbase One sign-in: run `vigilbase login`.``
- **`list`** reads your saved sign-in from disk only (no refresh, no network,
  no waiting for another command) to show which tools you can run. If it can't
  use it, it lists the tools as signed out and prints one line on stderr:
  ``Couldn't use your saved sign-in (<reason>); running anonymously. Run `vigilbase login` to fix.``
  When the reason is an unsafe config path or credentials file, the line ends
  with its fix instead (see [Directory checks](#directory-checks)).
- **`doctor`** reports a sign-in problem as its own failed `signIn` check.

## Automation and output

Every command supports `-j` / `--json`. JSON goes to stdout; progress and
browser instructions go to stderr. Progress animations are off for JSON, CI and
output that isn't a terminal. List commands never fetch every page on their
own: keep the JSON pagination fields to fetch the next page. Text output shows
complete identifiers. Human-readable output removes terminal control sequences
and bidirectional overrides from everything it prints, including names, tool
results, skills and errors. JSON keeps successful response data, with control
characters escaped.

`vigilbase --version` prints the banner in a terminal and only the version
number when stdout is a pipe or a file, so `v=$(vigilbase --version)` works in
scripts. With `--json` it prints `{"name":"@vigilbase/cli","version":"…"}`.

| Exit code | Meaning |
| --- | --- |
| `0` | Success (including a signed-out `whoami`) |
| `1` | Validation, API, network or sign-in error, or an unsuccessful scan result |
| `2` | Rate limited (`HTTP 429`) |

Errors keep a safe status, error code and retry delay. When a public scan
fails and vigilbase.com explains why, the CLI shows that reason:
`Error: <message> (<code>)` in text, and `error` plus `code` in JSON. The
reason is shown only when vigilbase.com sends it as a known error code, and it
is cleaned to one line of at most 300 characters. Anything else, and every
Vigilbase One error, prints a message the CLI wrote (for example
`You don't have access to this.` or `Request failed (HTTP <status>).`), never
the server's text. The exception is a One scan the scanner couldn't assess
(for example a bot verification challenge): the CLI prints the scanner's
reason, cleaned the same way. Hints (`Hint: …`, `hint` in JSON) are always written by the
CLI; COMMANDS.md lists the One errors that get one.

Commands use named One APIs and One's own authorization. They never take
Cloudflare or other provider secrets, delegated identity claims or an arbitrary
upstream URL. Billing records are fetched on demand and never stored by the
CLI.

## Sign-in

### Logging in

`vigilbase login` opens a browser and waits for you to approve the device code.
On a remote terminal, run `vigilbase login --no-open` and open the printed URL
in a signed-in browser.

The CLI reads One's protected-resource metadata to choose the sign-in:

- **Vigilbase Identity** (one.vigilbase.com uses it). You approve at
  <https://auth.vigilbase.com/device> and choose the organization the sign-in
  is for. `whoami` and `doctor` check the session at Identity.
- **Legacy One sign-in**, for a One that doesn't advertise Identity. You
  approve at that One's `/device` page.

The CLI builds the approval URL itself from the issuer (or One) origin; it
never opens a URL the server sends.

To save an existing One session token instead, pipe it from your secret
manager into `vigilbase login --token-stdin`. The input must hold one token and
is never echoed. `--token <bearer>` and `VIGILBASE_ONE_TOKEN` also work, but
command arguments can show up in process listings and shell history; neither
combines with `--token-stdin`. Login checks the token with One before saving
it.

### Where credentials are stored

Credentials live in the config directory: `VIGILBASE_CONFIG_DIR` if set,
otherwise `$XDG_CONFIG_HOME/vigilbase`, otherwise `~/.config/vigilbase`.
`VIGILBASE_CONFIG_DIR` must be an absolute path; a relative `XDG_CONFIG_HOME`
is ignored.

| File | Holds |
| --- | --- |
| `identity-credentials.json` | Your Vigilbase Identity sign-in: issuer, client, One origin, organization and the rotating refresh token. CLI 0.1.x never reads it. |
| `credentials.json` | A legacy One session (version 1), shared with CLI 0.1.x: written by `--token`, `--token-stdin`, `VIGILBASE_ONE_TOKEN` and legacy device sign-in. |
| `credentials.json.lock` | One lock for both files, also used by CLI 0.2.0. |

Files are written atomically with mode `0600`. A saved session is only sent to
the One origin it was issued for (a legacy file without an origin counts as
production). With both files present, the Identity sign-in is used, and a
`credentials.json` that can't be parsed is ignored. Logging in replaces a file
that passes the [directory checks](#directory-checks) but can't be parsed.

### Using CLI 0.1.x or 0.2.0 too

- CLI 0.2.0 kept its Identity sign-in in `credentials.json`, which CLI 0.1.x
  cannot read. The first command of 0.2.1 or later that reads your sign-in
  moves it to `identity-credentials.json` (under the lock), unless that file
  already exists. From then on `credentials.json` is either absent or a legacy
  session that 0.1.x can use.
- If 0.2.0 later saves a new `credentials.json` while
  `identity-credentials.json` exists, 0.2.1 and later ignore it. `whoami`
  notes it (`legacyIdentityFileIgnored` in JSON), and `vigilbase logout`
  revokes and removes it.
- An Identity login leaves a legacy `credentials.json` alone. A token login or
  a legacy device login first revokes and removes any Identity sign-in, so the
  new session is the one in use; if that revocation fails, login stops and
  nothing changes.
- Logging in again with Identity first revokes and removes the sign-in it
  replaces, before asking for a new device code, so cancelling that login
  leaves you signed out. If the revocation fails, the CLI warns that the old
  sign-in will expire on its own and carries on. A sign-in whose last refresh
  had an uncertain result isn't revoked: Identity may have replaced its token
  already, and presenting that token again can end every CLI sign-in of yours.
  It expires on its own.
- Sign out with 0.2.1 or later: CLI 0.1.x's `logout` only deletes
  `credentials.json` and does not touch your Identity sign-in.

### Logging out

`vigilbase logout`:

1. Revokes every saved Identity refresh token, in `identity-credentials.json`
   and in a `credentials.json` left by CLI 0.2.0. A sign-in Identity has
   already ended (after a browser sign-out, for example) counts as revoked. If
   revocation fails otherwise, it keeps every file and stops with
   `Identity revocation failed, so your saved sign-in was kept. Try again later.`
2. Signs a legacy session out at the One that issued it. If that fails, it
   warns and goes on; the session expires on its own.
3. Deletes the credential files. A file that passes the
   [directory checks](#directory-checks) but can't be parsed is removed with a
   warning, without being revoked; an unsafe file stops logout and stays in
   place.

Saved Identity credentials belong to one issuer, client and One. If you signed
in with `--auth-url`, `--one-url` or `--client-id`, log out with the same
options; otherwise logout stops, before revoking anything, with
`Saved credentials belong to a different issuer, resource, or client. Use the matching configuration to log out.`

### Refresh and the credentials lock

Identity access tokens last five minutes. The CLI refreshes within 60 seconds
of expiry, or once after a 401. The lock coordinates CLI processes, and each
holder rereads the file before rotating the refresh token. If a refresh may
have been used but its answer was lost, the CLI marks it and asks you to run
`vigilbase login` again rather than retrying it. A command waits up to 15
seconds (or `--timeout`, if shorter) for the lock, then stops with
`Credentials are locked by another command. …`. `login` and `logout` may
remove a lock left by a process that has exited, but never one held by a
running process. If a damaged lock can't be recovered, stop every `vigilbase`
process, delete `credentials.json.lock` and log in again. Never reuse a refresh
token by hand.

### Directory checks

Commands that read or write credentials (`login`, `logout`, `whoami`, every One
command, `--via one` and the One-only scans) check the whole config path first:

- no component of the path may be a symbolic link;
- every parent directory must be owned by you or root, and not writable by its
  group or by others unless it has the sticky bit;
- the config directory must be owned by you with mode `0700`;
- credential files must be regular files owned by you, with one hard link and
  mode `0600`.

Each error names the path that failed and how to fix it, for example:

```
Error: /tmp is a symbolic link. Set VIGILBASE_CONFIG_DIR to a private directory without symbolic links in its path.
Error: /Users/jane/.config/vigilbase must have mode 0700. Run chmod 700 /Users/jane/.config/vigilbase, or set VIGILBASE_CONFIG_DIR to another directory.
```

On macOS `/tmp` and `/var` are symbolic links, and dotfiles managers often make
`~/.config` one. Fix the mode with the `chmod` the error names, or point
`VIGILBASE_CONFIG_DIR` at a private directory of its own, for example:

```bash
export VIGILBASE_CONFIG_DIR="$(cd ~ && pwd -P)/.vigilbase"
```

Don't use a directory inside a dotfiles repository or a synced folder (resolving
a symlinked `~/.config` with `pwd -P` usually leads there): the credential
files hold your refresh token.

Public commands don't need these checks: public scans, `describe`, `skill` and
`badge` never open the config directory, and work even when
`VIGILBASE_CONFIG_DIR` isn't absolute. `list` and `doctor` never create or open
anything in a directory that fails them, and only treat it as a problem when a
credentials file may be there: `list` then shows you as signed out with one
warning, and `doctor` reports it in its `signIn` check. With no saved sign-in,
both carry on as usual.

### Windows

Signing in isn't supported on Windows yet, because the CLI can't yet protect
credential files there. `login`, `logout`, `whoami`, the One commands,
`--via one` and the One-only scans stop with
`Signing in isn't supported on Windows yet; public tools and cloudflare-checkup still work.`
(code `SIGN_IN_UNSUPPORTED`) before touching the disk or the network. Public
tools, `list`, `doctor`, `describe`, `skill`, `badge` and `cloudflare-checkup`
work and ignore any saved credentials.

## Configuration

| Option | Environment variable | Default |
| --- | --- | --- |
| `--base-url <origin>` | `VIGILBASE_BASE_URL` | `https://vigilbase.com` |
| `--one-url <origin>` | `VIGILBASE_ONE_URL` | `https://one.vigilbase.com` |
| `--auth-url <origin>` | `VIGILBASE_AUTH_URL` | `https://auth.vigilbase.com` |
| `--client-id <id>` | `VIGILBASE_CLIENT_ID` | `vigilbase-cli` |
| `--timeout <ms>` | — | `60000` per request |

Origins are HTTP(S) URLs without credentials, paths, queries or fragments. One
needs HTTPS; HTTP is allowed only for loopback development (`localhost`,
`127.0.0.0/8` or `[::1]`). This applies to device sign-in, tokens and saved
sessions. `VIGILBASE_API_URL` and `VIGILBASE_PUBLIC_URL` are older names for
the public origin, used after `VIGILBASE_BASE_URL` when no flag is given.
`VIGILBASE_CLI_NO_OPEN=1` stops the CLI from opening a browser, and
`VIGILBASE_CLI_NO_BANNER=1` hides the banner.

**Identity issuer.** The CLI trusts one Identity issuer: `--auth-url` /
`VIGILBASE_AUTH_URL` when set, otherwise `https://auth.vigilbase.com`. The
issuer One names must be exactly that origin, or sign-in stops before any
request to it. `--auth-url` accepts `https://auth.vigilbase.com`,
`https://identity-staging.vigilbase.com`, or a loopback origin when `--one-url`
is loopback too; staging is trusted only when you pass it. Saved Identity
credentials from another issuer count as signed out.

Billing portal URLs must use HTTPS on `billing.stripe.com`. Skill downloads are
limited to HTTPS `vigilbase.com/agent-skills/<name>.md` (or
`www.vigilbase.com`), whatever origin you configure. Every DNS answer must be a
public address, the TLS connection is pinned to a checked address, and
redirects are refused. Skill documents are limited to 256 KiB and API responses
to 8 MiB; timeouts cover reading the body.

## Troubleshooting

**Check connectivity.** `vigilbase doctor` (add `--json` for details) runs
three checks on their own and exits 1 if any fails:

- `publicApi`: `GET https://vigilbase.com/api/v1/agent/tools`.
- `one`: your session. Signed out or with a legacy session,
  `GET https://one.vigilbase.com/api/auth/get-session`; a signed-out answer
  counts as reachable. With an Identity sign-in, the issuer's
  `/.well-known/openid-configuration` and then the userinfo endpoint it names
  (`https://auth.vigilbase.com/api/auth/oauth2/userinfo`).
- `signIn`: whether your saved sign-in works, including a refresh if one is
  due.

DNS, TLS, connection and timeout failures name the endpoint and the cause.
Use `--base-url`, `--one-url`, `--auth-url` and `--timeout` to check other
environments.

**`Unknown command "cloudflare-checkup"`.** An older global install (0.1.x)
takes priority over a bare `npx @vigilbase/cli`. Update it with
`npm install -g @vigilbase/cli@latest`, or run the latest release once with
`npx @vigilbase/cli@latest cloudflare-checkup`. `vigilbase --version` shows
which version answers.

**`yarn dlx` or `pnpm dlx` runs an older version.** Yarn 4.15 and later and
pnpm 11 and later skip releases published in the last 24 hours by default
(Yarn's `npmMinimalAgeGate`, pnpm's `minimumReleaseAge`). For a day after a
release, `yarn dlx @vigilbase/cli` and `pnpm dlx @vigilbase/cli` run an
older release, and Yarn refuses the new version by number
(`All versions satisfying "…" are quarantined`). Use `npx @vigilbase/cli`, or
wait a day.

**`Device sign-in isn't available at <origin> right now.`** Login got a 404
from that origin. If you set `--one-url` or `--auth-url`, check it; otherwise
try again later or email help@vigilbase.com. Public tools work without signing
in.

**`… is a symbolic link`, `… must have mode 0700` and similar.** See
[Directory checks](#directory-checks).

**`A previous refresh has an uncertain result.`** Run `vigilbase login` again.

**Certificates.** On Node 22.19+ and 24.5+ the CLI adds your operating
system's trusted certificates, keeping Node's bundled roots and
`NODE_EXTRA_CA_CERTS`. This covers private CAs trusted in the macOS Keychain or
the system trust store. See
[Node's TLS documentation](https://nodejs.org/docs/latest-v22.x/api/tls.html#tlssetdefaultcacertificatescerts).
On an older Node 22, `fetch failed` or `SELF_SIGNED_CERT_IN_CHAIN` can be
worked around with:

```bash
NODE_OPTIONS="${NODE_OPTIONS:+$NODE_OPTIONS }--use-system-ca" vigilbase login
```

For a private CA outside the system store, set
`NODE_EXTRA_CA_CERTS=/path/to/trusted-ca.pem` before starting the CLI.
Certificate checks always stay on.

**Timeouts.** Use `--timeout` for slower queries; some security analytics APIs
take longer than the default.

**Help.** Email help@vigilbase.com or visit <https://vigilbase.com/help>.