Skip to main content
Vigolium ships seven agent subcommands under vigolium agent. They split into four families:
  • Agentic scan modes: autonomous or AI-guided vulnerability scanning: autopilot, swarm
  • Source audit mode: multi-phase AI code audit: audit (unified driver for the embedded vigolium-audit harness and/or the standalone piolium harness, selected with --driver)
  • Single-shot / interactive: query, olium
  • Utility: session, triage
The parent vigolium agent command itself only supports --list-templates and --list-agents. All execution requires a subcommand. Every agent invocation is dispatched through the in-process olium runtime (pkg/olium/). There are no subprocess SDK or ACP backends, provider selection lives at agent.olium.provider in vigolium-configs.yaml. See How It Works for the provider list.

​
When to use what

​
Mode reference

​
query: single-shot prompt

  • Use for: code review, endpoint discovery, secret detection, ad-hoc prompts.
  • Not for: network scanning or multi-phase orchestration.
  • Key flags: --prompt-template, -p/--prompt, --stdin, --source, --files, --source-label, --output, --dry-run, --provider, --model, --oauth-cred, --oauth-token, --llm-api-key.

​
autopilot: autonomous agentic scan

  • Use for: pentest-style engagements where you want the agent to be creative and decide what to do.
  • How it works: one autonomous operator runs until it calls halt_scan or hits limits. legacy keeps one conversation; shadow/enforced rotate bounded sections and persist resumable state. When --source is provided, vigolium-audit runs first to prepare a frozen whitebox context bundle.
  • Key flags: [prompt]/--prompt, -t/--target, --input, --burp-bridge-url, --prior-context {auto|summary|off}, --knowledge-base, --plan-file, --source, --max-duration, --intensity {quick|balanced|deep}, --audit {lite|balanced|deep|off}, --resume, --session-dir, --transcript, --triage, --diff, and --last-commits.
See Autopilot.

​
swarm: AI-guided multi-phase scan

  • Use for: target-specific scanning when you want structure (planning → native scan → triage), source-aware route discovery, or verification loops.
  • How it works: 10-phase pipeline, normalize → auth (opt) → source-analysis (opt) → code-audit (opt) → discover (opt) → plan (AI) → extension → native scan → triage (opt) → rescan (opt).
  • Key flags: [prompt]/--prompt, -t/--target (required with --source), --input, --plan-file, --record-uuid, --source, --discover, --code-audit, --triage, --max-iterations, -m/--modules, --vuln-type, --audit {lite|balanced|deep}, --intensity, --only/--skip/--start-from, and --with-extensions.
See Swarm.

​
audit: unified source-audit driver

  • Alias: vigolium audit is a top-level alias for vigolium agent audit (identical flags).
  • Use for: running the embedded vigolium-audit harness and/or the standalone piolium harness against a single source tree under one AgenticScan, with per-driver session subdirs ({session}/audit/, {session}/piolium/), per-driver child AgenticScan rows under one parent, and a post-pass project-wide findings dedup once both drivers exit.
  • Driver values (--driver):
    • auto (default) — run vigolium-audit; fall back to piolium only if the claude/codex CLI required by audit is missing.
    • both — run vigolium-audit then piolium back-to-back, unconditionally.
    • audit — run only the embedded vigolium-audit harness.
    • piolium — run only the standalone piolium harness (no audit, no fallback).
  • Modes: when the run includes both drivers (auto or both), --mode is restricted to the shared set: lite, balanced, deep, revisit, confirm, merge. Use --driver=piolium for longshot/smoke or --driver=audit for mock. --intensity deep expands to the chain deep,confirm.
  • Agent selection (audit leg only): --provider <olium-provider> resolves the agent and forwards that provider’s BYOK auth (anthropic-* → claude, openai-* → codex). --agent {claude|codex} is a pure agent selector layered on top of --provider (rejected for invalid values; warned under --driver=piolium).
  • Key flags: --driver {auto|both|audit|piolium}, --mode, --modes (chain), --intensity {quick|balanced|deep}, --source <path|git-url>, --commit-depth, --interactive, --no-stream, --no-dedup, --upload-results, --provider, --agent, plus the --pi-* and --plm-* passthroughs for the piolium leg. --list-modes prints the embedded vigolium-audit binary’s mode graph and exits.
  • Raw output (audit leg): --keep-raw is on by default (CLI), retaining <source>/vigolium-results/ in the source tree; --clean-raw removes it after the run (the session copy is always kept). --keep-raw+--clean-raw is an error. The REST keep_raw default is unchanged (off).
  • One-shot report: -S/--stateless runs the audit into a throwaway temp DB (main DB untouched, like vigolium scan -S) and auto-writes a self-contained HTML report to vigolium-result/vigolium-audit-report.html (override with -o/--output; supports gs:// and {ts}). Not valid with --interactive.
  • REST equivalent: POST /api/agent/run/audit with driver: "auto"|"both"|"audit"|"piolium" (default "auto").
See Agentic Security Audit.
There is no standalone vigolium agent piolium subcommand. Piolium runs only through the audit dispatcher, vigolium agent audit --driver piolium (piolium alone), --driver both (audit then piolium), or --driver auto (piolium as fallback when the claude/codex CLI is missing). Piolium-only modes (longshot, smoke) and passthroughs (--pi-*, --plm-*) are exposed on agent audit.

​
olium: interactive TUI chat

  • Aliases: top-level vigolium olium / vigolium ol.
  • Use for: interactive debugging, exploration, or one-shot non-interactive prompts. Provider-agnostic.
  • Not for: orchestrated scanning, there are no scan phases.
  • Key flags: --provider, --model, --llm-api-key, --oauth-cred/--oauth-token, --system, -p/--prompt (one-shot non-interactive), --stdin.

​
session: agent run history

  • Aliases: sessions, sess.
  • Use for: auditing prior runs, debugging failed scans.
  • Key flags: --mode {query|autopilot|swarm|audit}, -n/--limit, -o/--offset, --tail, --full.

​
triage: single-finding confirmation

  • Use for: confirming or downgrading one existing finding with AI, without launching a full scan.
  • How it works: vigolium agent triage [finding-id] loads the stored finding (and its linked request/response), runs the AI triage flow against it, and updates the finding’s verdict/severity in place.
  • Not for: discovering new issues, it only re-evaluates a finding you already have.

​
Picking between autopilot and swarm

Both are agentic scan modes. The distinction:
  • autopilot: the agent is the scanner. It opens a shell, reads files, runs tools, and decides everything. Best when the target is fuzzy or you want creative, exploratory testing.
  • swarm: the agent directs the native scanner. It plans, picks modules, generates JS extensions, and the deterministic Go pipeline does the heavy traffic. Best when you want structured, repeatable results with optional verification loops.
If you have source code and a target URL, both work; swarm --source --target ... --code-audit --triage gives you the most structured output, while autopilot --source ... gives the agent more freedom (and runs a vigolium-audit prep first).

​
Cross-cutting

  • Session dir: ~/.vigolium/agent-sessions/ (override via agent.sessions_dir in vigolium-configs.yaml).
  • Durable autopilot: set agent.olium.autopilot_mode to shadow or enforced; legacy remains the default.
  • Prompt templates: ~/.vigolium/prompts/ or embedded under public/presets/prompts/.
  • Output schemas: findings, http_records, attack_plan, triage_result, source_analysis.
  • Engine: every agent run is dispatched through the in-process olium runtime (pkg/olium/). Provider selection lives at agent.olium.provider in vigolium-configs.yaml, see How It Works for the provider list.
  • Source flag: --source is the canonical source-code flag across all modes; the legacy --repo/--repo-url/--source-url flags have been removed.
  • Task guidance: autopilot and swarm use --prompt or the positional prompt. Their former CLI flags --focus, --instruction, --instruction-file, --browser, and --credentials are removed; put focus and login details in the prompt. Structured equivalents remain available in the REST API.

​
REST API

The server exposes the run modes plus a status/artifact surface so a controller can launch and tail runs without the CLI. Run endpoints return 202 Accepted with {agentic_scan_uuid, status: "running"} and execute in the background. Expected workflow:
  1. POST one of the run/* endpoints, capture agentic_scan_uuid.
  2. Poll GET /api/agent/status/:id until status leaves running.
  3. Fetch the session artifacts via /api/agent/sessions/:id/logs, /artifacts, or /artifacts/{name} for the raw outputs (output.md, swarm-plan.json, audit-stream.jsonl, generated extensions, etc.).
The audit endpoint dispatches sequentially when more than one driver runs (auto with fallback or both), and multiplexes SSE chunks with a driver field bracketed by driver_start/driver_end markers when stream: true. See Agentic Security Audit for the unified-driver overview. Set stream: true on the run endpoints to opt into Server-Sent Events instead of the async response, most consumers should stick with the async flow and tail logs on demand.

​
Provider overrides

The CLI exposes per-invocation provider flags (--provider, --model, --oauth-cred, --oauth-token, --llm-api-key, --system). The server falls back to agent.olium.* in vigolium-configs.yaml (which keeps warm sessions and prompt caches stable across requests), but every agent run endpoint also accepts per-request BYOK credentials (api_key, oauth_token, oauth_cred_file, oauth_cred_json). The audit dispatcher additionally accepts audit_auth and piolium_auth for per-driver overrides. See API Reference, Agent for the full request/response schemas.