Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Armur-Ai/Pentest-Swarm-AI/llms.txt

Use this file to discover all available pages before exploring further.

pentestswarm campaign is a family of subcommands for managing the lifecycle of campaigns that were started with pentestswarm scan. A campaign is the central unit of work in Pentest Swarm AI — it tracks the target, scope, phase progression, agent events, and discovered findings. You can have multiple campaigns running simultaneously (each in their own process), and inspect any of them by ID.

​
Synopsis

pentestswarm campaign <subcommand> [args] [flags]

​
Subcommands

​
campaign list

Print a table of all campaigns known to the API server, including their status and finding count. 
pentestswarm campaign list
Example output: 
ID                                   STATUS       TARGET              FINDINGS
───────────────────────────────────────────────────────────────────────────────
abc-123-def-456                      running      example.com         12
789-ghi-jkl-012                      complete     10.0.0.0/24         31
When no campaigns exist yet, the command prints a hint to launch your first scan: 
  (no campaigns yet — run: pentestswarm scan <target> --scope <scope>)

​
campaign status <id>

Show a detailed snapshot of a single campaign by its UUID. 
pentestswarm campaign status abc-123
Example output: 
* Campaign: abc-123-def-456-789
  Status:  running
  Target:  example.com
The status command reads from the in-memory API server. Run pentestswarm serve (or use the embedded server started by scan) to ensure campaign state is accessible.

​
campaign watch <id>

Open a full-screen interactive TUI (terminal user interface) dashboard powered by Bubbletea. The dashboard shows all agents working simultaneously, live findings as they are discovered, attack paths being constructed, and agent reasoning steps — all in a multi-panel layout with AltScreen mode so it does not interfere with your scrollback buffer. 
pentestswarm campaign watch abc-123
Dashboard panels:
PanelContent
Agent activityPer-agent thought stream and tool calls
FindingsFindings as they are discovered, color-coded by severity
Attack pathsChains of exploitation steps being attempted
Event logRaw timestamped event feed
The TUI subscribes to the campaign’s WebSocket endpoint (/api/v1/campaigns/:id/ws) in a production setup, receiving events in real time. Press q or Ctrl-C to exit the dashboard without stopping the campaign. Demo events rendered in the TUI: 
  [*]  Campaign initialized
  [think]  Planning reconnaissance strategy...
  [>>]  Running subfinder, httpx, nuclei, naabu

​
campaign stop <id>

Send an emergency stop signal to a running campaign. The swarm’s goroutines receive a context cancellation, cleanup actions are executed, and the campaign status transitions to aborted. 
pentestswarm campaign stop abc-123
Example output: 
* Stopping campaign abc-123...
* Campaign stopped. Cleanup actions executed.
Stopping a campaign mid-exploit may leave incomplete attack state on the target. Always review any partial findings in the report directory before stopping.

​
campaign explore <id>

Launch an interactive Bubbletea attack-surface explorer that lets you browse discovered subdomains, resolved hostnames, open ports, detected services, and findings from a completed or running campaign. 
pentestswarm campaign explore abc-123
The explore TUI requires at least the recon phase to have completed. Run it after campaign watch shows the reconnaissance phase finishing.

​
Examples

# List all campaigns
pentestswarm campaign list

# Check the status of a specific campaign
pentestswarm campaign status 550e8400-e29b-41d4-a716-446655440000

# Open the live TUI dashboard
pentestswarm campaign watch 550e8400-e29b-41d4-a716-446655440000

# Emergency stop
pentestswarm campaign stop 550e8400-e29b-41d4-a716-446655440000

# Explore the attack surface interactively after recon completes
pentestswarm campaign explore 550e8400-e29b-41d4-a716-446655440000

​
Campaign lifecycle

planned → initializing → recon → exploit → report → complete
                                                   ↘ aborted (on stop)
                                                   ↘ failed  (on error)
Campaigns are created by pentestswarm scan (or POST /api/v1/campaigns via the REST API) and transition through phases driven by the engine runner. The campaign watch TUI reflects each state transition as a [*] event.

scan

Launch a new campaign with the AI swarm

serve

Start the API server that backs campaign state and the WebSocket feed

report

Polish and quality-gate finished campaign reports

playbook

Run structured attack playbooks as an alternative to freestyle campaigns

Build docs developers (and LLMs) love

Get started for freeTalk to us