# Commands

> Run Vigilbase tools from the CLI, use JSON output in scripts, read exit codes and find the Vigilbase One command groups.

Source: https://docs.vigilbase.com/tools/cli/commands

This page covers the CLI commands for the free tools and the options every command shares. For built-in help, run `vigilbase <command> --help`, `vigilbase help <command>` or `vigilbase help <tool>`.

## Tool commands

| Command | What it does |
| --- | --- |
| `list` (alias `tools`) | Lists the public tools and the tools that need a Vigilbase One sign-in. |
| `headers <url>` | Runs [Security headers](https://docs.vigilbase.com/tools/security-headers). Same as `run security-headers <url>`. |
| `email <domain>` | Runs [Email security](https://docs.vigilbase.com/tools/email-security). Same as `run email-security <domain>`. |
| `run <tool> <target>` | Runs a tool by name. Add `--via one` to run a public tool through Vigilbase One. |
| `describe <tool>` | Prints the tool's description and a `Target:` line with the expected format. |
| `skill <tool>` | Prints the tool's published [agent skill](https://docs.vigilbase.com/tools/developers/agent-skills-and-discovery). |
| `badge <domain>` | Prints the [badge](https://docs.vigilbase.com/tools/developers/badges) URL for a domain. `--style default`, `compact` or `mini`. |
| `cloudflare-checkup` | Runs the [Cloudflare Checkup on your machine](https://docs.vigilbase.com/tools/cli/cloudflare-checkup-cli). |

```terminal
$ vigilbase headers https://vigilbase.com
$ vigilbase email vigilbase.com --json
$ vigilbase run website-security example.com --json
$ vigilbase badge vigilbase.com --style compact
```

`website-security`, `react2shell` and `fortibleed-check` run only through Vigilbase One and need `vigilbase login`. Without a sign-in they stop with code `NOT_SIGNED_IN`. An unknown tool name stops with `INVALID_ARGUMENT` before any request.

Public scans share the hourly quota described on [Agent API](https://docs.vigilbase.com/tools/developers/agent-api): 20 scans per client IP and 20 per target. When it is used up the CLI exits 2 with the delay until the quota resets. It never retries on its own.

## JSON output and scripts

Every command accepts `--json` (or `-j`). JSON goes to stdout; progress and browser instructions go to stderr. With `--json`, errors are JSON on stdout too.

A graded scan exits 0 whatever its grade, even F. Gate your scripts on `.grade` or `.result.status` in the JSON, not on the exit code:

```bash
grade=$(vigilbase headers https://example.com --json | jq -r '.grade')
[ "$grade" = "A" ] || [ "$grade" = "A+" ] || exit 1
```

A scan that the scanner ran but could not assess, for example because the site answered with a bot challenge, prints `✗ <tool> · <target> · n/a` with the reason and exits 1. Its JSON has `success: false` and code `scan_unassessed`.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success, including a graded scan of any grade and a signed-out `whoami` |
| `1` | Validation, API, network or sign-in error, or a scan that failed or could not be assessed |
| `2` | Rate limited (`HTTP 429`) |
| `130`, `143`, `129` | `cloudflare-checkup` cancelled by Ctrl-C, SIGTERM or SIGHUP |

## Global options

| Flag | Meaning |
| --- | --- |
| `--json`, `-j` | JSON on stdout |
| `--help`, `-h` | Help for the command; makes no request |
| `--version`, `-V` | The installed version |
| `--base-url <origin>` | Public origin; default `https://vigilbase.com` |
| `--one-url <origin>` | Vigilbase One origin; default `https://one.vigilbase.com` |
| `--auth-url <origin>` | Identity issuer; default `https://auth.vigilbase.com` |
| `--timeout <ms>` | Per-request timeout; default `60000` |

Unknown flags fail with code `UNKNOWN_OPTION` and a `Did you mean` suggestion when one is close.

## Sign-in commands

| Command | What it does |
| --- | --- |
| `login` | Signs in with a device code. `--no-open` for remote terminals, `--token-stdin` to save a token. |
| `whoami` | Shows the saved sign-in. Signed out is a successful answer. |
| `logout` | Revokes and deletes the saved sign-in. |
| `doctor` | Checks the public API, Vigilbase One and your sign-in. See [Troubleshooting](https://docs.vigilbase.com/tools/cli/troubleshooting). |

## Vigilbase One commands

With a sign-in, the CLI also reaches Vigilbase One. Your organization's permissions in One decide what each command can see.

| Group | Examples |
| --- | --- |
| Account and billing | `account`, `account services`, `billing`, `billing portal` |
| Run history | `runs list`, `runs get <id>` |
| Watchdog | `watchdog list`, `watchdog scans` |
| Cloudflare | `cf accounts`, `cf zones`, `cf checkup start`, `cf checkup result <run-id>` |
| Customers, organizations, monitoring, support | `customers list`, `orgs`, `monitoring`, `support tickets` |

Commands that change something, such as `account invites create`, need `--confirm`. The full references ship with the package: [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.10/files/COMMANDS.md), [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.10/files/CLOUDFLARE.md) and [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.10/files/ONE.md).