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
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
--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:
vigolium scan -t https://example.com --soft-fail
Scanning
Run the full native pipeline against one or more targets.
# Single target
vigolium scan -t https://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
# 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
Parallel & isolated scans
Scan many targets at once, or let several parallel scans share one database without write contention.
# 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.
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
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 -
vigolium --list-input-mode to see every supported input format with examples.
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.
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.
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
# 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
--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.
# Browse
vigolium db ls
vigolium db ls --table findings
vigolium db stats
vigolium db stats --detailed
vigolium traffic # Alias for `db ls --table 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
vigolium finding --min-severity high --confidence certain,firm # Filter by severity floor + confidence
# 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`)
# Cleanup
vigolium db clean --scan-uuid my-scan
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).
Import
Pull external scan data back into a database. The input type is auto-detected from the path.
# 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
--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 — with or without a mutation — to confirm a finding, fuzz a parameter, or push a whole corpus back through a proxy. The banner is suppressed so bulk output stays pipe-clean.
# Confirm a stored record with a SQLi payload (baseline vs. mutated diff)
vigolium replay --record-uuid abc12345 -m 'name=id,payload=1 OR 1=1'
# Replay a finding's stored evidence with an XSS payload
vigolium replay --finding-id 42 -m 'name=q,payload=<svg/onload=alert(1)>'
# 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 \
-m 'name=user,payload=admin' -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
Bulk replay
Pass --all (or any of --host / --method / --status / --path / --source / --search / --body) to replay every matching stored record through the mutation/diff engine, streaming one JSONL object per record with per-record error isolation.
# Replay ALL stored traffic through Burp (JSONL out, 5 at a time)
vigolium replay --all --proxy http://127.0.0.1:8080 -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
# Fuzz an 'id' param across every matching GET record
vigolium replay --method GET --host api.example.com -m 'name=id,payload=1 OR 1=1'
--all lifts the default -n/--limit cap (100); narrow the set with the filter flags instead. Without -m/--mutate, each record is re-sent verbatim.- Throttle with
-c/--concurrency (default 10); cap the set with -n/--limit (default 100, lifted by --all).
-S/--stateless --db <file> reads baselines from a standalone .sqlite/.jsonl export with project scoping off — it never writes to your project DB.
Strategies & Phases
Inspect scanning strategy presets and the phases that make up a scan.
vigolium strategy
vigolium strategy ls
vigolium phase
Modules
Manage the active and passive scanner modules.
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.
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.
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).
vigolium scope view
vigolium scope set host.include '*.example.com'
Agent (AI)
Run agentic and source-audit modes. See Agent Mode for the full list of subcommands.
agent query: single-shot prompts
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
vigolium agent swarm -t https://example.com --discover
vigolium agent swarm -t https://example.com --discover --focus 'API injection'
# 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
agent autopilot: autonomous agentic scan
# 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 --focus "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" \
--instruction "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 / browser / auth
vigolium agent autopilot -t https://example.com --provider anthropic-api-key
vigolium agent autopilot -t https://example.com --browser --credentials "admin/admin123"
# 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
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.
# 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
-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:
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
vigolium config ls
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
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.
