@vigilbase/cli 0.2.0 → 0.2.1

package/README.md

@@ -1,46 +1,45 @@
 # @vigilbase/cli
 
-Vigilbase public scanners and Vigilbase One customer, security, Cloudflare,
-monitoring, organization, and support operations from the terminal.
+Vigilbase public security scanners, the Cloudflare Checkup, and Vigilbase One
+customer, security, Cloudflare, monitoring, organization and support operations
+from the terminal.
 
-## Install and sign in
+## Install
 
-Node 20+ is required. Node 22.19+ or Node 24.5+ enables automatic system
-certificate trust. `cloudflare-checkup` needs Node 22.18+, because it runs
-Cloudflare's `cf` under the same Node.
+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
+npm install -g @vigilbase/cli     # or: pnpm add -g @vigilbase/cli
 vigilbase help
-vigilbase login
-vigilbase whoami
 ```
 
-Without global installation: `npx @vigilbase/cli help`. From this monorepo:
-`pnpm vigilbase help`; build with `pnpm build:cli` and link with
-`pnpm link:vigilbase`.
+Without installing: `npx @vigilbase/cli help`. If you see
+`Unknown command "cloudflare-checkup"`, an older global install is answering
+instead (see [Troubleshooting](#troubleshooting)).
 
-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 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.
 
-## Complete command documentation
+## Documentation
 
-| Reference | Coverage |
+| Reference | Covers |
 | --- | --- |
-| [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 |
-| [LOCAL.md](./LOCAL.md) | `cloudflare-checkup`: one command that verifies your work email, collects Cloudflare config on your machine with Cloudflare's `cf` and uploads it after you confirm |
+| [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/COMMANDS.md) | Core commands, aliases, global options, API mapping, sign-in, output |
+| [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/CLOUDFLARE.md) | Accounts, zones, DNS, WAF, analytics, Zero Trust, Workers/Pages, audit, checkups |
+| [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/SECURITY.md) | Incidents, logs, intelligence, analytics, assets, connections, policies, notifications, reports |
+| [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/ONE.md) | Customer records, billing, reports, investigations, organizations, monitoring, support |
+| [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/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 references ship with the npm package. Built-in help is available through
-`vigilbase <command> --help` or `vigilbase help <command>`.
+These files ship with the package. Built-in help: `vigilbase <command> --help`
+or `vigilbase help <command>`.
 
 ## Examples
 
-Public tools require no login:
+Public tools, no sign-in:
 
 ```bash
 vigilbase list
@@ -50,10 +49,12 @@ vigilbase describe security-headers
 vigilbase badge vigilbase.com --style compact
 ```
 
-Public scanners are `security-headers` and `email-security`. Authenticated
-scanners are `website-security`, `react2shell`, and `fortibleed-check`:
+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
@@ -64,7 +65,7 @@ vigilbase support tickets
 vigilbase runs list
 ```
 
-Cloudflare IDs come from the accessible inventory:
+Cloudflare IDs come from the inventory you can access:
 
 ```bash
 vigilbase cf accounts
@@ -92,184 +93,349 @@ vigilbase security notifications
 vigilbase security audit --limit 50
 ```
 
-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.
+Customer users inherit their organization's scope. Internal operators add
+`--customer-id <customer-uuid>` for security views; Cloudflare analytics needs
+it too. 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, a status update is available explicitly:
+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 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).
+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.1/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 disabled for JSON, CI, and
-non-TTY output. Preserve JSON pagination fields when fetching subsequent pages;
-list commands do not silently fetch every page (local collection pages through
-every list by design). 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.
+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 unsuccessful scan result |
+| `1` | Validation, API, network or sign-in error, or an 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.
-
-Exception: `vigilbase cloudflare-checkup` (also `local cloudflare-checkup`) runs
-Cloudflare's own `cf` CLI on your machine with a fixed allowlist of read-only
-commands. cf owns your Cloudflare login; the Vigilbase CLI never reads, prints,
-stores or uploads it. Its only Vigilbase requests are the email verification
-and the explicit upload of a snapshot file you can inspect, after you confirm.
-The command asks for your work email, and vigilbase.com emails you a 6-digit
-code to enter; it then installs cf if needed (asks first), signs in read-only,
-lets you choose the account, collects, uploads and prints the results link
-(opening it in your browser on macOS and Linux).
-Results go to the verified address. Your email address goes to vigilbase.com
-only so it can send the code; the CLI never prints, logs or stores it (it shows
-the masked `j***@acme.com`). In a terminal the steps show as an interactive
-timeline with arrow-key questions; pipes, CI, `TERM=dumb` and `--json` get
-plain lines. See [LOCAL.md](./LOCAL.md).
+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 only `Request failed (HTTP <status>).` without the
+server's text. Hints (`Hint: …`, `hint` in JSON) are always written by the CLI.
+
+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 0.2.1 command 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 ignores 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
-npx @vigilbase/cli cloudflare-checkup          # also shown at https://vigilbase.com/tools/cloudflare-checkup?mode=local
-npx @vigilbase/cli cloudflare-checkup logout   # later: remove the read-only cf login and the cf it installed
+export VIGILBASE_CONFIG_DIR="$(cd ~ && pwd -P)/.vigilbase"
 ```
 
-## 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`. Legacy manual/session credentials contain only access-token metadata. Identity
-credentials use version 2 and store the rotating refresh token with its issuer,
-client and One resource binding.
-
-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.
-`login` reads One's protected-resource discovery at runtime. Until cutover, One
-advertises its legacy device flow (missing metadata also retains that flow).
-After cutover it advertises Identity, which grants a token for the organization
-you choose during device approval. `whoami` and `doctor` use Identity userinfo
-for these grants. `logout` revokes the Identity refresh token before removing the
-local file; legacy logout remains local. Network failures retain the file for retry.
-
-Identity access tokens last five minutes. Refresh starts within 60 seconds of
-expiry, or once after One returns 401. An exclusive credentials lock coordinates
-independent CLI processes; each holder rereads the file before rotating. A durable
-pending marker prevents retry after an uncertain token exchange. Run `login`
-again after an uncertain refresh. Fresh login/logout may retire a dead process's
-owned lock, but never steal a live process lock. If a damaged lock cannot be
-recovered, stop all CLI processes before removing `credentials.json.lock` and
-logging in again. Never reuse the refresh token manually.
+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` | issuer selected by One discovery |
+| `--auth-url <origin>` | `VIGILBASE_AUTH_URL` | `https://auth.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. Identity issuer and endpoint origins are
-restricted to `auth.vigilbase.com` and `identity-staging.vigilbase.com`; local
-Identity requires explicit `--auth-url` and a loopback One origin. Arbitrary
-issuers, endpoints, and 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.
+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
 
-`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
+**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/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.
+
+**`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).
-
-For an older installed CLI reporting `fetch failed` / `SELF_SIGNED_CERT_IN_CHAIN`,
-a recent Node 22 runtime supports this workaround:
+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, 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 local Cloudflare Checkup has a cross-package end-to-end test in apps/com: the
-built CLI collects through the smoke's fake `cf` and uploads to the real
-vigilbase.com route handlers, with One's tool-runs API faked on loopback. Run it
-after a build:
+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.
 
-```bash
-pnpm --filter @vigilbase/cli build
-pnpm --filter com exec vitest run lib/cloudflare-checkup/local/__tests__/e2e-local-cli.test.ts
-```
+**Timeouts.** Use `--timeout` for slower queries; some security analytics APIs
+take longer than the default.
 
-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.
+**Help.** Email help@vigilbase.com or visit <https://vigilbase.com/help>.

package/SECURITY.md

@@ -1,6 +1,6 @@
 # Security command reference
 
-All commands start with `vigilbase security`. Sign in with `vigilbase login` first. Commands use the configured One origin and its authenticated `/api/flarehawk` boundary. One independently checks permissions and maps the current organization to its security tenant. Internal operators can supply `--customer-id <One customer UUID>` for validated View-as access; this never supplies an upstream organization identity.
+All commands start with `vigilbase security`. Sign in with `vigilbase login` first (signing in isn't supported on Windows yet). Commands use the configured One origin and its authenticated `/api/flarehawk` boundary. One independently checks permissions and maps the current organization to its security tenant. Internal operators can supply `--customer-id <One customer UUID>` for validated View-as access; this never supplies an upstream organization identity.
 
 Every operation below is **GET/read-only**, except `incidents update`, which is **PATCH/write** and requires `--confirm` plus server service-write permission. Reads require server service-read permission. No command directly accesses the retained service, runs archived chat, changes remediation authority, or approves provider effects.
 
@@ -131,4 +131,4 @@ vigilbase security connections logpush-status <connection-uuid> <job-uuid>
 vigilbase security intel ip 1.1.1.1
 ```
 
-The API contract sources are One's `flarehawk/policy.ts`, `flarehawk-ui/client.ts`, `flarehawk-ui/normalizers.ts`, specialized analytics request/normalizer modules, personal-controls schemas, and incident-share schemas. Binary log downloads and routes without a verified JSON consumer are not exposed. The standalone `scripts/fixtures/security.mjs` catalog covers every named wire operation for compiled CLI end-to-end verification.
+Binary log downloads and routes without a verified JSON consumer are not exposed.

package/dist/auth/device-auth.d.ts

@@ -55,4 +55,3 @@ export declare function waitForDeviceAuthorization(config: CliConfig, device: De
     signal?: AbortSignal;
     maxConsecutiveTransient?: number;
 }): Promise<DeviceTokenSuccess>;
-//# sourceMappingURL=device-auth.d.ts.map