— docs

CLI reference

Every aegis command and every flag.

The full CLI surface, grouped by what you’d actually use them for.

Engagement lifecycle

`aegis init`

Profile the host (CPU, memory, OS, installed tools) and cache the result to ~/.config/aegis/env-profile.json. Run this once after installing, and again whenever you add new tools.

`aegis engagement new`

Scaffold a new engagement directory.

aegis engagement new \
  --client "Acme Corp" \
  --scope www.acme.com,acme.com,api.acme.com \
  --budget-usd 5.00 \
  [--out engagements/]

Creates engagements/<id>-acme/ with scope.yaml, an empty SQLite DB, and an artifacts/ folder. Edit scope.yaml to tighten rate limits, add exclusions, or pin extra context for the agent.

`aegis engagement list`

List every engagement in the current working tree.

`aegis run`

Run a pentest engagement. The headline command.

aegis run <engagement-dir> [flags]

Flag	What it does
`--phase <name>`	Skip straight to a specific phase (e.g. `--phase vuln_analysis`)
`--dry-run`	Plan actions and print them; never execute or call the LLM
`--budget-usd <n>`	Override the engagement’s USD budget
`--hunt`	Bug-hunter mode — loop past REPORTING until `/stop`
`--classic`	Use the legacy Rich.Live TUI instead of the React/Ink one
`--json`	Stream NDJSON events to stdout, no TUI

`aegis report`

Render an HTML / Markdown / JSON report from a finished engagement.

aegis report <engagement-dir> [--format html|md|json] [--out report.html]

`aegis status`

Live, read-only dashboard of an engagement that’s currently running (or paused).

aegis status <engagement-dir>

`aegis findings`

Browse / suppress findings in an engagement DB.

aegis findings list <engagement-dir> [--severity high,critical]
aegis findings suppress <engagement-dir> <finding-id> --reason "false positive"

Environment

`aegis env show`

One-screen summary: OS, CPU, memory, tool inventory, LLM backend status.

`aegis env tools`

Detailed table of every detected tool with version and path.

`aegis env install [--missing]`

Walk the tool catalog and install missing ones (pacman, yay, go install, pipx, npm).

`aegis env refresh`

Re-profile the host. Run after installing new tools.

Knowledge base

`aegis kb update`

Refresh the local CVE / nuclei-template / WSTG knowledge bases.

`aegis kb search <query>`

Search the local KB for a CVE, template, or check.

Docker

`aegis docker build`

Build the bundled Docker image (aegis-pentest:latest) with all 80+ tools preinstalled.

`aegis docker run <engagement-dir>`

Run an engagement inside the container. The engagement dir is mounted RW.

`aegis docker shell [engagement-dir]`

Drop into an interactive shell inside the container. Useful when you want to use a single tool out of the catalog without going through the orchestrator.

`aegis docker status`

Show whether the image is built and what’s inside it.

MCP server mode

`aegis serve`

Start AEGIS as an MCP stdio server. Claude Code can be the orchestrator instead of aegis run:

claude mcp add aegis -- aegis serve

Then inside any Claude Code session: aegis_load_scope('/path/to/scope.yaml').

Cost & audit

`aegis cost <engagement-dir>`

Token spend, USD spend, per-phase breakdown.

`aegis audit <engagement-dir>`

Tail the audit log: every tool invocation, every LLM call, every scope check.

Global flags

Flag	Effect
`--version`	Print the version and exit
`--help`	Show help for any command
`--log-level`	`debug`, `info`, `warning`, `error`