@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).

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

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

Documentation

| Reference | Covers | | --- | --- | | COMMANDS.md | Core commands, aliases, global options, API mapping, sign-in, output | | CLOUDFLARE.md | Accounts, zones, DNS, WAF, analytics, Zero Trust, Workers/Pages, audit, checkups | | SECURITY.md | Incidents, logs, intelligence, analytics, assets, connections, policies, notifications, reports | | ONE.md | Customer records, billing, reports, investigations, organizations, monitoring, support | | 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:

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:

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:

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:

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:

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

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:

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

See 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).
• 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 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 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:

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 [email protected]. Public tools work without signing in.

… is a symbolic link, … must have mode 0700 and similar. See 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. On an older Node 22, fetch failed or SELF_SIGNED_CERT_IN_CHAIN can be worked around with:

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 [email protected] or visit https://vigilbase.com/help.