> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vigolium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI References

> Common usage examples for the vigolium CLI, scanning, agentic runs, ingestion, server, database, and more.

A curated tour of the most common `vigolium` invocations, grouped by command. For the full flag list of any command, run `vigolium <command> --help`. For the same examples in your terminal, run `vigolium --full-example`.

## Top-Level Commands

```bash theme={null}
vigolium --help              # All available commands and global flags
vigolium <command> --help    # Flags and help for a specific command
vigolium --full-example      # Curated tour of all common usage
vigolium version             # Build and version info
```

The global `--soft-fail` flag forces an exit code of `0` even when a command fails (the error is still printed to stderr). It keeps a failing `vigolium` call from interrupting the wrapping script or CI pipeline:

```bash theme={null}
vigolium scan -t https://example.com --soft-fail
```

<Note>
  Mistype a long flag and Vigolium suggests the nearest match instead of a bare "unknown flag" error — e.g. `--module` yields `unknown flag: --module. Did you mean --modules? (run 'vigolium scan --help' for all flags)`. Added in v0.3.0.
</Note>

## Scanning

Run the full native pipeline against one or more targets.

```bash theme={null}
# Single target
vigolium scan -t https://example.com

# Bare positional target URLs also work (deduped against -t/--target); also on scan-url/scan-request/run
vigolium scan https://example.com https://api.example.com

# Multiple targets (-t and -T/--target-file are both repeatable and combine)
vigolium scan -t https://example.com -t https://api.example.com
vigolium scan -T targets.txt
vigolium scan -T prod.txt -T staging.txt

# Scanning profiles and strategies
vigolium scan -t https://example.com --strategy deep
vigolium scan -t https://example.com --scanning-profile quick
vigolium scan -t https://example.com --scanning-profile full

# Phase control
vigolium scan -t https://example.com --only dynamic-assessment
vigolium scan -t https://example.com --skip discovery,spidering

# Module selection
vigolium scan -t https://example.com -m xss-reflected,sqli-error
vigolium scan -t https://example.com --module-tag spring --module-tag injection

# Output and reporting
vigolium scan -t https://example.com --format jsonl -o results.jsonl
vigolium scan -t https://example.com --format html -o report.html
vigolium scan -S -t https://example.com --format sqlite -o scan      # standalone .sqlite (stateless only)
vigolium scan -t https://example.com --format fs -o run             # browsable run-traffic/ + run-findings/ tree

# Print results to stdout after the scan (pairs with -S --silent; also on scan-url/scan-request/run)
vigolium scan-url -S -t https://example.com --silent --print-finding        # findings as Markdown
vigolium scan-url -S -t https://example.com --silent --print-traffic-tree   # traffic as a host/path tree
vigolium scan-url -S -t https://example.com --silent --print-traffic        # raw request/response pairs

# Network controls
vigolium scan -t https://example.com --proxy http://127.0.0.1:8080
vigolium scan -t https://example.com -c 100 --rate-limit 200
vigolium scan -t https://example.com --scanning-max-duration 2h
vigolium scan -t https://example.com --no-waf-pacing         # Disable proactive WAF/CDN pre-throttling (speed control)

# Discovery: sweep alternate HTTP(S) ports on the target hosts (deep intensity or --follow-subdomains)
vigolium scan -t https://example.com --intensity deep --port-sweep-ports 80,443,8080,8443

# CI/agent exit-code gating
vigolium scan -t https://example.com --fail-on high       # exit non-zero on any high+ finding
vigolium scan -t https://example.com --fail-on high --soft-fail   # surface the error but always exit 0

# Custom JS extensions
vigolium scan -t https://example.com --ext custom-check.js
vigolium scan -t https://example.com --ext-dir ./my-extensions
vigolium scan -t https://example.com --only extension --ext custom-check.js

# Project scoping
vigolium scan -t https://example.com --project-name my-project

# OAST and known-issue scanning
vigolium scan -t https://example.com --oast-url https://interact.sh/abc123
vigolium scan -t https://example.com --known-issue-scan-tags cve,misconfig --known-issue-scan-severities critical,high
```

The repeatable "opaque" flags — `-H/--header`, `--auth`, `--auth-file`, `-t/--target`, `-T/--target-file`, `--spec-header`, and `--cookie` — take each value **verbatim**: commas are **literal**, not separators. So a target URL with a query like `?ids=1,2,3`, or a header/cookie whose value contains a comma, survives intact. To pass several values, **repeat the flag** (`-t https://a -t https://b`) rather than comma-joining them.

**Speed control — WAF-aware pacing.** The per-host rate limiter now **proactively pre-throttles** a host the first time earlier-phase traffic fingerprints it behind a recognized CDN/WAF edge (CloudFront, Cloudflare, Akamai, Imperva/Incapsula, Sucuri, or Azure Front Door — detected from headers on ordinary 200s), dropping that host's concurrency to `MaxPerHost/4` and ramping back up on healthy responses. This keeps an aggressive active phase from bursting the edge into a rate-based block that would hide findings. A one-time-per-host `[waf-pacing-armed]` notice prints the drop (e.g. `40→10`) to stderr and the session log. `--no-waf-pacing` disables this **proactive** pacing; the **reactive** back-off after a *confirmed* WAF block still applies. It's a Speed Control flag, available on `scan` / `scan-url` / `scan-request` / `run` / `ingest`.

**Discovery — alternate-port sweep.** `--port-sweep-ports` overrides the alternate HTTP(S) ports swept on the CLI target hosts (comma-separated). The sweep runs when `--intensity deep` is set or `--follow-subdomains` is on, so a host reachable on `8080`/`8443` (or any port you list) is discovered and scanned alongside the standard `80`/`443`.

### Parallel & isolated scans

Scan many targets at once, or let several parallel scans share one database without write contention.

```bash theme={null}
# Fan out a target list across N isolated child processes, one per-host output file each
vigolium scan -T targets.txt -P 4 --stateless --split-by-host --format jsonl -o results

# Parallel into one shared DB: each worker scans into a private temp DB, then merges into --db
vigolium scan -T targets.txt -P 4 --db-isolate --db shared.db --format jsonl,html -o report

# Single scan into a private temp DB merged back into --db (no write contention)
vigolium scan -t https://example.com --db-isolate --db shared.db

# Resume an interrupted stateless fan-out (skips targets that already completed)
vigolium scan -T targets.txt -P 4 --stateless --split-by-host --format jsonl -o results --resume
vigolium scan --resume                                              # auto-discover *.progress.json in cwd
```

* `-P, --parallel N` — scan up to N targets concurrently as isolated child processes. Requires either `-S --split-by-host` (per-host outputs) or `--db-isolate` (merge into one `--db`). Real in-flight requests ≈ `N × --concurrency`.
* `--db-isolate` — scan into a private temporary SQLite DB and merge results into `--db` at the end (SQLite only; not combinable with `--stateless`).
* `--split-by-host` — in stateless multi-target mode, write a separate `base-<host>.<ext>` output file per target.
* `--resume` — resume a prior `-S -T --split-by-host -P` run from its `<output>.progress.json` manifest, scanning only the targets that didn't finish. Run bare (no other flags) to auto-discover the manifest in the current directory and relaunch the saved run.

## Running a Single Phase

`vigolium run <phase>` is an alias for `scan --only <phase>`, useful when you want one specific stage of the pipeline.

```bash theme={null}
vigolium run discover -t https://example.com
vigolium run spidering -t https://example.com
vigolium run dynamic-assessment -t https://example.com
vigolium run dynamic-assessment -t https://example.com --module-tag spring
vigolium run external-harvest -t https://example.com
vigolium run known-issue-scan -t https://example.com
vigolium run known-issue-scan -t https://example.com --known-issue-scan-tags cve --known-issue-scan-severities critical,high
vigolium run extension -t https://example.com --ext custom-check.js
vigolium run deparos -t https://example.com
vigolium run dast -t https://example.com
```

## Input Modes

Feed traffic into a scan from OpenAPI, Burp, curl, HAR, or stdin.

```bash theme={null}
vigolium scan -I openapi -i openapi.yaml -t https://api.example.com
vigolium scan -I burp    -i burp-export.xml -t https://example.com
vigolium scan -I curl    -i requests.txt
vigolium scan -I har     -i traffic.har
cat urls.txt | vigolium scan -i -
```

Run `vigolium --list-input-mode` to see every supported input format with examples. Accepted formats are `urls`, `openapi`/`swagger`, `postman`, `curl`, `burpraw`/`raw`, `burpxml`/`burp`, `har`, and `nuclei`.

An unknown `-I/--input-mode` value is now **rejected up front** with a clear error (it previously fell through to the Nuclei parser silently, so a typo could yield zero or partial records with no warning).

## Ingestion

Push HTTP traffic into the database without running a scan, useful for building a project corpus before scanning, or for sending traffic to a remote server.

```bash theme={null}
vigolium ingest -t https://example.com -I openapi -i spec.yaml
vigolium ingest -t https://example.com -I burp    -i export.xml
cat urls.txt | vigolium ingest -i -

# Send to a remote Vigolium server
vigolium ingest -s http://server:9002 -i api.yaml -I openapi
```

## Server

Start the REST API and ingest proxy.

```bash theme={null}
vigolium server                                              # Default host/port from config
vigolium server --host 0.0.0.0 --service-port 8443
vigolium server --no-auth                                    # Local use only — disables bearer auth
vigolium server -t https://example.com --scan-on-receive     # Auto-scan ingested traffic (-S is shorthand for --scan-on-receive)
vigolium server -S --passive-only                            # Passive modules only — no active traffic; includes secret detection
vigolium server --mirror-fs ./mirror                         # Live-mirror ingested traffic + findings to a filesystem tree
vigolium server --burp-bridge-url http://127.0.0.1:9009      # Merge live Burp Proxy history into GET /api/http-records

# Transparent ingest proxy (records traffic flowing through it)
vigolium server --ingest-proxy-port 9003

# Intercept HTTPS too via a generated MITM CA (trust the CA printed at startup)
vigolium server --ingest-proxy-port 9003 --proxy-mitm -S
vigolium server --ingest-proxy-port 9003 --proxy-mitm --proxy-insecure   # skip upstream TLS verification

# Export the MITM CA certificate and exit (generates it if needed)
vigolium server --export-ca ./vigolium-ca.pem
```

See [Transparent Proxy](/server-mode/proxy) for the full MITM workflow.

`--burp-bridge-url <url>` points the server at a running Burp Suite's loopback **live bridge** (default listener `http://127.0.0.1:9009`, exposed by the [`burp-vigolium`](https://github.com/vigolium/burp-vigolium) extension) and merges Burp's live Proxy rows into `GET /api/http-records` — labelled `source: burp` — for the UI and API. The flag also reads the `VIGOLIUM_BURP_BRIDGE_URL` env var as a fallback. See [Using Vigolium with Burp Suite](/getting-started/burp-suite) for bridge setup.

`--passive-only` (with `--scan-on-receive`) restricts scanning to **passive modules only** — no active scan traffic is sent, and secret detection is included. It's the safest way to analyze forwarded Burp/proxy traffic in place. Combining it with `--full-native-scan-on-receive` still crawls (discovery + spidering send requests); for zero active traffic, use `--scan-on-receive` without the full-native flag.

## Database & Results

Browse, export, and prune scan data.

```bash theme={null}
# Browse
vigolium db ls
vigolium db ls findings           # Positional table selector: findings | scans | scopes (--table is deprecated)
vigolium db stats
vigolium db stats --detailed
vigolium traffic                  # Alias for `db ls http_records`
vigolium traffic login            # Filter to login-related records
vigolium finding                  # Fuzzy-search findings
vigolium finding xss --markdown   # Render matches as Markdown (evidence + http blocks) to stdout

# Severity: --severity is an explicit set (alias --sev on `finding`); --min-severity is a floor
vigolium finding --severity high,critical                        # exactly these severities
vigolium finding --sev h,c                                       # single-letter shorthands
vigolium finding --sev crit,me,info                              # unambiguous prefixes
vigolium finding --min-severity high --confidence certain,firm   # floor (high+critical) + confidence
vigolium db ls findings --severity high,critical                 # --severity also on `db ls`

# Record kind & producing-module type (on `finding` and `db list`)
vigolium finding --record-kind finding,candidate                 # kinds: finding (default), candidate, observation
vigolium finding --module-type active,passive                    # by producing module type
vigolium db ls findings --module-type nuclei,agent               # also on `db ls`

# Exclude filters (on `finding` and `traffic`) — inverse of --search/--header/--body
vigolium finding --search sqli --exclude-search login            # keep sqli, drop anything mentioning login
vigolium traffic --exclude-header Authorization                  # drop rows carrying an Authorization header
vigolium traffic --exclude-search .css --exclude-search .js      # repeatable — drop if ANY term matches

# Read a standalone export directly (project scoping off, never writes to your DB)
vigolium finding -S --db ./scan.jsonl --min-severity high
vigolium traffic -S --db ./scan.sqlite --status 500 -n 20

# Export
vigolium export --format jsonl -o full-export.jsonl
vigolium export --format jsonl --only findings
vigolium export --format jsonl --only findings,http
vigolium export --format html -o report.html
vigolium export --format fs -o run            # browsable run-traffic/ + run-findings/ tree (also on `db export`)

# Live Burp bridge — read Burp history into the traffic view, or push DB traffic back into Burp
vigolium traffic --burp-bridge-url http://127.0.0.1:9009                                # merge live Burp Proxy history
vigolium traffic --burp-bridge-url http://127.0.0.1:9009 --save-to-vigolium-db          # persist the current page into the DB
vigolium traffic --burp-bridge-url http://127.0.0.1:9009 --save-to-vigolium-db --all    # persist every matching record
vigolium traffic --burp-bridge-url http://127.0.0.1:9009 --save-to-burp                 # copy DB traffic into Burp's Site map

# Cleanup — a selector is required; a bare `db clean` is rejected
vigolium db clean --scan-uuid my-scan
vigolium db clean --host api.example.com
vigolium db clean --all --force                    # delete every row from the data tables
vigolium db reset --force                          # delete + recreate the DB file (SQLite; VACUUMs automatically)
```

`finding`/`traffic` accept `-S/--stateless` + `--db <file>` to read a `--format jsonl` export or a standalone `.sqlite` directly, and `--markdown` to print the matched items as Markdown (under `-S`, add `--compact` to window long responses around the match).

**Severity filters.** `--severity` (alias `--sev` on `finding`) takes an explicit comma-separated set, accepting single-letter shorthands (`h,c`) and any unambiguous prefix (`crit`, `me`, `info`). It differs from `--min-severity`, which is a **floor** — `--min-severity high` expands to `high,critical`. When both are given, `--severity` wins. `db ls` carries `--severity` too (findings tables).

**Record-kind & module-type filters.** `--record-kind` (on `finding` and `db list`) filters by record kind — `finding`, `candidate`, or `observation` (comma-separated; default `finding`). `--module-type` (same commands) filters by the **producing module type** — `active`, `passive`, `nuclei`, `agent`, `source-tools`, `oast`, or `extension` (comma-separated).

**Exclude filters.** `--exclude-search` / `--exclude-header` / `--exclude-body` (on `finding` and `traffic`) are the inverse of `--search` / `--header` / `--body`: they **drop** any row where the term appears. `--exclude-search` is repeatable, and a row is dropped if **any** term matches (contrast `--search`, whose repeated terms AND-narrow the kept set).

**Live Burp bridge.** With a running Burp Suite exposing the loopback bridge (default listener `http://127.0.0.1:9009`, from the [`burp-vigolium`](https://github.com/vigolium/burp-vigolium) extension; env fallback `VIGOLIUM_BURP_BRIDGE_URL`), `vigolium traffic --burp-bridge-url <url>` merges Burp's live Proxy history into the traffic view. Add `--save-to-vigolium-db` to persist those bridge rows into the DB (the current page, or every match with `--all`), or `--save-to-burp` to copy DB traffic **into** Burp's Target Site map (the two `--save-to-*` flags are mutually exclusive). See [Using Vigolium with Burp Suite](/getting-started/burp-suite) for bridge setup.

**Push findings to Burp.** `vigolium finding --push-to-burp` (paired with `--burp-bridge-url`) hands the selected finding(s)' evidence request+response to Burp's Organizer — severity-coloured, one item per finding — for manual confirmation. `--to-repeater` opens the finding's request in a Repeater tab instead (Burp caps Repeater at \~30 tabs/min, so prefer `--push-to-burp` for a large selection), and `--send-via-burp` re-issues the request through Burp's engine to capture a fresh response (with `--http-mode auto|http1|http2|http2_ignore_alpn`). These honour the usual `finding` selectors (`--severity`, `--min-severity`, a fuzzy term, `--finding-id`).

```bash theme={null}
# Push all XSS findings' evidence into Burp's Organizer for manual confirmation
vigolium finding xss --push-to-burp --burp-bridge-url http://127.0.0.1:9009

# Open one finding in a Repeater tab and re-issue it through Burp for a fresh response
vigolium finding --finding-id 42 --to-repeater --send-via-burp \
                 --burp-bridge-url http://127.0.0.1:9009
```

**Cleanup safety.** A bare `vigolium db clean` with no selector is **rejected** — narrow the delete with a filter (`--scan-uuid`, `--host`, `--before`, `--status`, `--severity`, `--search`, `--orphans`, `--findings-only`, `--table`), use `db clean --all --force` to empty the data tables, or `vigolium db reset --force` to delete and recreate the SQLite database file from scratch (it VACUUMs automatically; without `--force` on a TTY it prompts for interactive confirmation).

### Import

Pull external scan data back into a database. The input type is auto-detected from the path.

```bash theme={null}
# JSONL export (http_record + finding envelopes, e.g. from `vigolium export --format jsonl`)
vigolium import full-export.jsonl

# Audit output folder (contains audit-state.json + findings-draft/)
vigolium import ./audit-output/

# Merge another vigolium SQLite scan DB into your default database
vigolium import other-vigolium-scan.sqlite

# Merge into an explicit destination (--db is the target)
vigolium import --db team.sqlite other-vigolium-scan.sqlite

# Combine many standalone scan DBs into one (idempotent — re-runs are no-ops)
for f in scans/*.sqlite; do vigolium import --db combined.sqlite "$f"; done

# Compressed archive (.tar.gz / .tgz / .zip) or a cloud-storage object
vigolium import ./scan-bundle.tar.gz
vigolium import gs://<project-uuid>/imports/scan.tar.gz

# One-shot persist of a running Burp Suite's live Proxy history into the DB
vigolium import --burp-bridge-url http://127.0.0.1:9009
```

`--burp-bridge-url <url>` turns `import` into a one-shot persist of **all** of a running Burp's live Proxy history into the database (default listener `http://127.0.0.1:9009`; env fallback `VIGOLIUM_BURP_BRIDGE_URL`). It's an import *source*, so it cannot be combined with path arguments or `--glob-db`. See [Using Vigolium with Burp Suite](/getting-started/burp-suite).

A **SQLite database input** (detected by its magic header, any extension) is a lossless, idempotent SQLite→SQLite merge: HTTP records, findings, scans, agentic scans, OAST interactions, and projects are deduped on their natural keys, and each row keeps its original project. Re-importing the same database adds nothing the second time. The destination is the `--db` target (or the configured default database when `--db` is omitted). Add `-j/--json` to print a per-table merge summary (rows inserted vs. skipped). This pairs with `scan -S --format sqlite`: fan out per-host `.sqlite` files, then merge them back into one queryable DB.

## Replay

Re-send stored traffic — verbatim, or with an exact-byte override — to confirm a finding or push a whole corpus back through a proxy. For payload / insertion-point fuzzing, reach for [`vigolium fuzz`](#fuzz) instead (`replay`'s `-m/--mutate` was removed). The banner is suppressed so bulk output stays pipe-clean.

```bash theme={null}
# Re-send a stored record and diff the fresh response against the baseline
vigolium replay --record-uuid abc12345

# Re-fire the exact request behind a finding (human-readable summary)
vigolium replay --finding-id 42 --pretty

# Send exact bytes verbatim — a hand-edited raw request overrides the resolved baseline
vigolium replay --record-uuid abc12345 --raw-request-file exact.txt

# Replay a curl command verbatim (auto-baseline by re-sending)
vigolium replay -i "curl -X POST https://example.com/api/login -d 'u=admin'"

# Multi-step auth via a persistent cookie jar
vigolium replay --session-id login -i curl-login.sh
vigolium replay --session-id login --record-uuid <action-uuid>

# Confirm against a different environment than the baseline
vigolium replay --record-uuid abc12345 --target https://staging.example.com \
                 -H 'X-Forwarded-For: 127.0.0.1'

# Merge headers from a saved auth session (from `vigolium auth list`)
vigolium replay --record-uuid abc12345 --target https://staging.example.com \
                 --auth-session my-session

# Save a replayed request + its fresh response back into Burp's Target Site map
vigolium replay --record-uuid abc12345 \
                 --burp-bridge-url http://127.0.0.1:9009 --save-to-burp

# Send the exact bytes through Burp's OWN HTTP engine (not Go's client) — force HTTP/1 for desync
vigolium replay -i req.txt --burp-bridge-url http://127.0.0.1:9009 \
                 --send-via-burp --http-mode http1

# Stage the request in a Burp Repeater tab, or store request+response in the Organizer
vigolium replay --record-uuid abc12345 --burp-bridge-url http://127.0.0.1:9009 --to-repeater
vigolium replay --record-uuid abc12345 --burp-bridge-url http://127.0.0.1:9009 \
                 --to-organizer --notes 'IDOR candidate' --highlight orange
```

**Exact-byte override.** `--raw-request <string>` sends those exact bytes instead of the resolved baseline — for a hand-crafted smuggling prefix, a deliberate `Content-Length`, or an unusual method; `--raw-request-file <path>` reads the same from a file (the two are mutually exclusive). `-i/--input` (curl / raw HTTP / Burp) likewise replaces the whole request. For wordlist-scale payload injection at an exact position, use [`vigolium fuzz`](#fuzz).

`--save-to-burp` (paired with `--burp-bridge-url`) adds each replayed request and its fresh response straight into Burp's Target Site map — without proxying it twice — so a confirmed exploit lands back in Burp for manual follow-up (default listener `http://127.0.0.1:9009`; env fallback `VIGOLIUM_BURP_BRIDGE_URL`). See [Using Vigolium with Burp Suite](/getting-started/burp-suite).

**Send through Burp's engine.** `--send-via-burp` routes the send through Burp's own HTTP stack so the exact bytes reach the wire — a deliberate `Content-Length`, a smuggling prefix, or an unusual method is preserved instead of being normalised by Go's client. Pick the wire protocol with `--http-mode auto|http1|http2|http2_ignore_alpn` (default `auto`; use `http1` for request smuggling / desync so `auto` doesn't renegotiate HTTP/2 and reframe the request). Independently, `--to-repeater` (with `--repeater-tab <name>`, default `vigolium`) stages the request in a Burp Repeater tab, and `--to-organizer` (with `--notes` and `--highlight`) stores the request + response pair in Burp's Organizer. All require `--burp-bridge-url`; without them the send path is unchanged. See [Send traffic through Burp's engine](/getting-started/burp-suite#send-traffic-through-burps-engine).

### Bulk replay

A positional `vigolium replay <term>` does a broad fuzzy match over stored traffic (URL, path, host, method, content-type, source, and the raw request/response) — exactly like `vigolium traffic <term>` — and switches replay into "iterate **every matching stored record**" mode. Passing `--all` or any selector flag does the same. Each matched record is re-sent verbatim through the diff engine, streaming one JSONL object per record with per-record error isolation.

```bash theme={null}
# Replay every stored request whose text matches "admin" through a proxy (5 at a time)
vigolium replay admin --proxy http://127.0.0.1:8080 -c 5

# Replay ALL stored traffic through a proxy (JSONL out)
vigolium replay --all --proxy http://127.0.0.1:8080 -c 5

# Traffic-style selectors: POST records containing "token" but not "logout"
vigolium replay --host api.example.com --method POST --search token \
                 --exclude-search logout --proxy http://127.0.0.1:8080 -c 5

# Date range + ordering: JSON 200s since a date, oldest-sent first
vigolium replay --status 200 --body 'application/json' --from 2026-07-21 \
                 --sort sent_at --asc -c 5

# Replay every record from a standalone export (project scoping off)
vigolium replay -S --db scan.sqlite --all --proxy http://127.0.0.1:8080 -c 5
```

The selection surface mirrors `vigolium traffic`:

* **Match:** a positional term, repeatable `--search` (AND-combined; matches URL/path **and** the raw request/response), `--host`, `--method` (repeatable), `--status` (repeatable), `--path`, `--source`, `--body`.
* **Exclude:** repeatable `--exclude-search` and `--exclude-body` drop matching records.
* **Range & order:** `--from` / `--to` (`YYYY-MM-DD` or RFC3339), `--sort uuid|created_at|sent_at|method|status|time` (default `created_at`), `--asc` (default: newest-first), `--offset <n>` for pagination.
* `--all` lifts the default `-n/--limit` cap (100); narrow the set with the selectors instead. Each record is re-sent verbatim — payload / insertion-point fuzzing lives in [`vigolium fuzz`](#fuzz).
* Throttle with `-c/--concurrency` (default 10); cap the set with `-n/--limit` (default 100, lifted by `--all`).
* Combine with `--proxy`, `--save-to-burp`, or `--send-via-burp` as with single-record replay.
* `-S/--stateless --db <file>` reads baselines from a standalone `.sqlite`/`.jsonl` export with project scoping off — it never writes to your project DB.

## Fuzz

`vigolium fuzz` injects a caller-supplied payload set into chosen positions of **one** request and streams per-payload response signals (status, size, words, lines, time, reflection, baseline-delta) with match/exclude gating and auto-calibration against the target's catch-all. It is a low-level **primitive**, not a scanner: it sends exactly the payloads you give it at exactly the positions you pick and makes **no vulnerability decision** — it emits raw signals, not findings. The intelligence comes from the caller (typically a coding agent). For confirmation-backed detection of known classes, use the module scanner instead: `vigolium scan-request -i req.txt -m xss,sqli -j`.

```bash theme={null}
# Fuzz a wordlist into a FUZZ marker; keep only 200s
vigolium fuzz 'https://acme.test/api/FUZZ' -w dir-short --match-status-code 200

# Inject a built-in payload class into one parameter; anomalies vs the calibrated baseline
vigolium fuzz 'https://acme.test/item?id=1' --point URL_PARAM:id --class sqli,xss

# Fuzz from a raw request on stdin with inline payloads; drop 404s
cat req.txt | vigolium fuzz -p "' OR 1=1--" -p '<svg/onload=alert(1)>' --exclude-status-code 404

# Fuzz a stored record (by UUID) as the baseline request
vigolium fuzz -u <record-uuid> --fuzz params -w fuzz

# Agent handle: stream JSONL to stderr, print ONE summary object to stdout
vigolium fuzz 'https://acme.test/api?id=FUZZ' -w ~/wordlists/ids.txt -j

# CI/agent gate: exit non-zero (3) if any result matches
vigolium fuzz 'https://acme.test/admin/FUZZ' -w dir-short --match-status-code 200,301 --fail-on-match
```

**Source** (one of): a positional URL (with `-X`/`-H`/`-d` to build the request), `-i/--input` (curl, raw HTTP, Burp XML, base64, URL, or `-` for stdin), `-u/--record-uuid` (a stored HTTP record), or a request piped on stdin. `-t/--target` overrides the scheme/host/port the request is actually sent to.

**Positions** (what to fuzz): a literal `FUZZ` marker anywhere in the request (request line, path, header, or body) wins if present; otherwise `--fuzz method|path|params|param-name|headers|cookies|all` (default: all discovered insertion points), `--point TYPE:name` (e.g. `URL_PARAM:id`, repeatable), or `--fuzz-header <name>` (repeatable). The marker keyword is configurable with `--keyword`.

**Payloads** (combine freely): `--class` selects a built-in vulnerability class — `xss`, `sqli`, `ssti`, `ssrf`, `lfi`, `path_traversal`, `xxe`, `cmdi`, `open_redirect`, `crlf` (aliases like `traversal`, `rce`, `sql`, `template` accepted); `-w/--wordlist` takes a builtin name (`fuzz`, `dir-short`, `dir-long`, `file-short`, `file-long`) **or** a file path (repeatable); `-p/--payload` adds an inline literal (repeatable).

**Matchers & excludes.** Matchers **keep** a response (OR-combined; empty keeps all): `--match-status-code` (accepts `all`), `--match-size`, `--match-words`, `--match-lines`, `--match-regex`, `--match-time` (ms). Each has an `--exclude-*` counterpart that **drops** a response. Auto-calibration (on by default) probes the target's wildcard/catch-all and suppresses matches identical to it — suppressed results carry `"calibrated":true`; disable it with `--no-calibrate`.

**Output.** Default is JSONL (one object per send) to stdout — matched-only unless `--all-results`; `--pretty` renders a human-readable table, `-o/--output` writes to a file. Under `-j/--json`, the JSONL streams to **stderr** and a single summary object prints to stdout: `{target, sent, matched, calibrated, baseline, top_results (ranked anomalies), query (a ready scan-request confirmation)}` — a handle a coding agent can act on directly. `--fail-on-match` exits `3` when any result matches, for CI/agent gating. Throttle with `-c/--concurrency` (default 10) and `--delay <ms>`; `--timeout` sets the per-request timeout and `--no-redirects` stops following 30x. Honors `HTTP_PROXY`/`HTTPS_PROXY` for Burp inspection.

**Send through Burp's engine.** `--send-via-burp` (with `--burp-bridge-url`) routes every payload through Burp's own HTTP stack so exact bytes hit the wire — the way to fuzz malformed/smuggling requests (pair with `--http-mode http1`); `--matches-to-organizer` pushes each matched request into Burp's Organizer for triage. See [Send traffic through Burp's engine](/getting-started/burp-suite#send-traffic-through-burps-engine).

<Note>
  `replay`'s `-m/--mutate` flag was **removed** — `replay` now re-sends stored traffic (verbatim, or with an exact-byte `--raw-request` override) and confirms, while `fuzz` owns wordlist-scale payload injection at an exact position. (The `pkg/replay` library and the agent's in-process `replay_request` tool still apply mutations.)
</Note>

## Strategies & Phases

Inspect scanning strategy presets and the phases that make up a scan.

```bash theme={null}
vigolium strategy
vigolium strategy ls
vigolium phase
```

## Modules

Manage the active and passive scanner modules.

```bash theme={null}
vigolium module ls
vigolium module ls xss             # Search by keyword
vigolium module enable xss
vigolium module disable sqli
vigolium scan -M                   # List all modules from the scan command
```

## Skills

Install the coding-agent skill bundles shipped **inside** the binary (so they always match your CLI version) into a coding agent's skills directory. See [Using Vigolium in your agent](/agentic-scan/using-vigolium-in-your-agent).

```bash theme={null}
vigolium skills                                   # List bundled skills (alias: vigolium skills list)
vigolium skills get vigolium-scanner              # Print a bundle without installing it
vigolium skills install                           # Install vigolium-scanner for Claude into the current project
vigolium skills install --agent codex --scope global   # --agent claude|codex|agents, --scope project|global
vigolium skills install --all                     # Install every bundled skill
vigolium skills install --dir ./.claude/skills    # Override the destination directory
```

## Extensions

Run and manage JavaScript extensions that hook into the scanner.

```bash theme={null}
vigolium ext ls
vigolium ext docs
vigolium ext preset
vigolium ext example                       # Print every example extension (all supported formats)
vigolium ext example --list                # Just the catalog index (keys + titles)
vigolium ext example js-active-insertion   # Print a single example by its catalog key
vigolium ext example --lang yaml           # Restrict to one language
vigolium ext eval 'vigolium.log("hello")'
vigolium ext eval --ext-file script.js
```

## Scope

Control what's in-scope. Source code is attached per scan via the `--source` flag on `vigolium agent <subcommand>` (autopilot, swarm, query, audit).

```bash theme={null}
vigolium scope view
vigolium scope set host.include '*.example.com'
```

## Agent (AI)

Run agentic and source-audit modes. See [Agent Mode](/agentic-scan/agent-mode) for the full list of subcommands.

### `agent query`: single-shot prompts

```bash theme={null}
vigolium agent query --source ./src --prompt-template security-code-review
vigolium agent query --source ./src --prompt-template endpoint-discovery
vigolium agent query 'review this code for vulnerabilities'
vigolium agent query --agent-label code-review --prompt-file custom-prompt.md
vigolium agent --list-templates
```

### `agent swarm`: AI-guided multi-phase scan

```bash theme={null}
vigolium agent swarm -t https://example.com --discover
vigolium agent swarm -t https://example.com --discover --prompt 'focus on API injection'

# Natural-language positional prompt — preserved as extra instruction context alongside flags
vigolium agent swarm "focus on the checkout and payment flows" -t https://example.com --discover

# Load prose guidance plus raw HTTP request seeds from one plan file
vigolium agent swarm -t https://example.com --plan-file ./pentest-plan.md

# Run browser-based login; describe credentials and roles in the prompt
vigolium agent swarm -t https://example.com --browser-auth \
  --prompt "log in as admin/admin123, then compare the user role"

# Skill control (force-load attack-vector skills, bypass planner selection)
vigolium agent swarm -t https://example.com --discover --skill-tag xss,idor
vigolium agent swarm -t https://example.com --discover --no-skill-filter

# Olium provider/model overrides (same set as `agent autopilot` / `agent query`)
vigolium agent swarm -t https://example.com --discover --provider anthropic-api-key --model claude-opus-4-7
vigolium agent swarm -t https://example.com --discover --base-url http://localhost:11434/v1 --llm-api-key "$KEY"
```

`agent swarm` accepts the olium override flags `--provider`, `--model`, `--base-url`, `--llm-api-key`, `--oauth-cred`, and `--oauth-token`; each falls back to `agent.olium.*`. `--prompt` and the positional `[prompt]` are the same task-guidance slot and stay verbatim when structured target/source flags are also present.

### `agent autopilot`: autonomous agentic scan

```bash theme={null}
# Natural-language prompt — target, source, and focus auto-extracted
vigolium agent autopilot "scan VAmPI source at ~/src/VAmPI on localhost:3005"
vigolium agent autopilot "test auth bypass on https://app.example.com"

# Plain target
vigolium agent autopilot -t https://example.com/api

# Source-aware (auto-runs vigolium-audit first to build context)
vigolium agent autopilot -t https://example.com --source ./src
vigolium agent autopilot -t https://example.com --source ./src --audit=off   # disable vigolium-audit

# Pipe a curl command or raw HTTP request via stdin
curl -s https://example.com/api/users | vigolium agent autopilot
cat request.txt | vigolium agent autopilot -t https://example.com

# Pass curl/raw HTTP as input
vigolium agent autopilot --input "curl -X POST -H 'Content-Type: application/json' \
  -d '{\"user\":\"admin\"}' https://example.com/api/login"

# Focus the agent on specific vulnerability classes
vigolium agent autopilot -t https://example.com --prompt "focus on auth bypass and IDOR"

# Skill control — force-load skills by name or tag, or skip pre-flight selection
vigolium agent autopilot -t https://example.com --skill idor-blast-radius
vigolium agent autopilot -t https://example.com --skill-tag xss,idor
vigolium agent autopilot -t https://example.com --no-skill-filter

# Intensity presets — quick (CI/PR), balanced (default), deep (pentest)
vigolium agent autopilot -t https://example.com --intensity deep
vigolium agent autopilot -t https://example.com --source ./src --intensity quick

# Narrow source scope
vigolium agent autopilot -t https://example.com --source ./src \
  --files "routes/api.js,controllers/auth.js" \
  --prompt "Focus on the new payment endpoint"

# PR / diff-aware scan
vigolium agent autopilot -t https://example.com --source ./src --diff "main...feature-branch"
vigolium agent autopilot -t https://example.com --source ./src --last-commits 3

# Backend and authenticated testing (browser is always available)
vigolium agent autopilot -t https://example.com --provider anthropic-api-key
vigolium agent autopilot -t https://example.com \
  --prompt "log in as admin/admin123, then test protected routes"

# Mine existing project/Burp traffic and supply application documentation
vigolium agent autopilot -t https://example.com --prior-context auto
vigolium agent autopilot -t https://example.com \
  --burp-bridge-url http://127.0.0.1:9009 --knowledge-base ./app-docs

# Durable-mode resume and explicit debug artifacts
vigolium agent autopilot --resume <agentic-scan-uuid> \
  --prompt "continue the remaining checks"
vigolium agent autopilot -t https://example.com \
  --session-dir ./debug/run-1 --transcript ./debug/run-1.jsonl

# Limits and previews
vigolium agent autopilot -t https://example.com --intensity deep --max-duration 4h
vigolium agent autopilot -t https://example.com --intensity quick --triage
vigolium agent autopilot -t https://example.com --source ./src --dry-run
vigolium agent autopilot -t https://example.com --source ./src --show-prompt
```

Autopilot and swarm no longer expose CLI flags named `--focus`, `--instruction`, `--instruction-file`, `--browser`, or `--credentials`. Put those details in `--prompt`. The REST agent endpoints keep structured equivalents for API clients.

### `agent audit`: unified source audit (vigolium-audit + piolium)

Runs the vigolium-audit harness and/or piolium against a single source tree under one AgenticScan, with per-driver session subdirs and a post-pass findings dedup. `vigolium-audit` is the embedded harness name; the CLI driver value is `audit`.

```bash theme={null}
# Default driver is "auto": run audit; fall back to piolium only if the
# claude/codex CLI required by audit is missing. Balanced mode.
vigolium agent audit --source .

# Run both drivers back-to-back, unconditionally
vigolium agent audit --driver both --source ./backend

# Single driver — piolium only (no audit, no fallback)
vigolium agent audit --driver piolium --source ./backend --mode lite
vigolium agent audit --driver audit   --source ./backend --agent claude

# Multi-driver, deep intensity, against a remote git URL
vigolium agent audit --driver both --source git@github.com:org/repo.git --intensity deep
vigolium agent audit --driver both --source https://github.com/org/repo.git --commit-depth 0   # full history

# Override pi's provider/model for the piolium leg
vigolium agent audit --driver both --source ./backend \
  --pi-provider vertex-anthropic --pi-model claude-opus-4-6

# Driver-specific modes (piolium=longshot/smoke, audit=mock)
vigolium agent audit --driver piolium --source ./mono-repo --mode longshot \
  --plm-longshot-langs python,go --plm-longshot-limit 200
vigolium agent audit --driver audit --source ./backend --mode mock

# Cap commit-history scan window (piolium only)
vigolium agent audit --driver piolium --source ./backend --plm-scan-since "60 days ago"
vigolium agent audit --driver piolium --source ./backend --plm-scan-limit 500

# Skip post-pass dedup or preflight checks
vigolium agent audit --source ./backend --no-dedup
vigolium agent audit --source ./backend --no-preflight

# Pull source from a cloud-storage archive, upload results when done
vigolium agent audit --source gs://my-bucket/snapshots/repo.tar.gz
vigolium agent audit --source ./backend --upload-results

# Stateless one-shot: run into a throwaway DB and auto-render a self-contained HTML report
vigolium agent audit --source ./backend -S

# Bundle the HTML report + each ran driver's raw vigolium-results/ tree into one folder
vigolium agent audit --driver both --source ./backend -S --output-dir ./audit-bundle
```

On `agent audit`, `--intensity deep` resolves to the `deep,confirm` mode chain (the modes run back-to-back), matching the `POST /api/agent/run/audit` endpoint; `quick` maps to `lite` and `balanced` to `balanced` (both single-mode).

`-S/--stateless` runs the whole audit into a throwaway temp DB (your main DB is untouched, mirroring `scan -S`) and, on completion, renders a self-contained HTML report from the run's findings to `vigolium-result/vigolium-audit-report.html` (override with `-o/--output`, which supports `gs://` and `{ts}`). `--output-dir <dir>` (stateless-only) additionally bundles that report **and** a copy of each ran driver's raw `vigolium-results/` tree into one folder — a single driver lands flat at `<dir>/vigolium-results/`, multiple are namespaced under `<dir>/<driver>/`. `-S` is rejected with `--interactive`. `--keep-raw` is **on by default** for the CLI (it retains the `<source>/vigolium-results/` copy); `--clean-raw` removes that source copy after the run.

### `log`: replay an agentic session

Every olium agent run (autopilot, swarm, query, `olium`) writes a Pi-compatible `transcript.jsonl`. Replay it as a rendered conversation, or dump the raw JSONL:

```bash theme={null}
vigolium log                       # Replay the most recent agentic session
vigolium log <session-id>          # Replay a specific session
vigolium log --raw                 # Print the raw transcript JSONL verbatim instead of the rendered replay
```

## Configuration

```bash theme={null}
vigolium config ls
vigolium config ls server             # Filter by a key prefix
vigolium config ls '*burp*'           # Filter keys by glob
vigolium config view 'notify.*'       # Print a subtree
vigolium config ls --show-secrets     # Reveal masked secret values (API keys, tokens) in plaintext

# Set individual keys by dotted path — missing nested sections are created automatically
vigolium config set server.enable_burp_bridge true
vigolium config set server.burp_bridge_url http://127.0.0.1:9009
vigolium config set notify.enabled true
vigolium config set notify.provider telegram
vigolium config set notify.severities high,critical      # coerced to a list
vigolium config set notify.telegram.bot_token <bot-token>
vigolium config set notify.telegram.chat_id <chat-id>
vigolium config set database.driver postgres

vigolium config clean
vigolium init                     # Initialize ~/.vigolium with defaults
vigolium doctor                   # Diagnose configuration and tool readiness
vigolium auth                     # Authentication management utilities
vigolium project                  # Manage multi-tenant projects
```

`vigolium config ls` (aliases `list` / `view`) redacts sensitive values — API keys, tokens, credentials — as `[redacted]` by default. Pass `--show-secrets` to reveal them in plaintext; it prints a warning to stderr. The generic `-F/--force` no longer reveals secrets (it only skips confirmation prompts). Both accept an optional key prefix or glob (`config ls server`, `config view 'notify.*'`) to print just a subtree.

`vigolium config set <key> <value>` takes a dotted path and **creates missing intermediate sections**, so a previously-unset nested key — `notify.telegram.bot_token`, `server.burp_bridge_url`, `server.enable_burp_bridge` — can be set directly instead of failing with *"key not found"*. The value is coerced to the field's declared type (bool / int / float / comma-separated list), and the key is validated against the config schema so a typo is rejected up front.

<Note>
  This page covers the most common invocations. Every command supports `--help` for the full flag reference, and most commands accept the global flags shown by `vigolium --help`.
</Note>