Entrypoints

main.py (Flow A, active) and legacy/cli.py (Flow B, frozen) are the two command-line entries. Root cli.py, agent_loop.py, planner.py, executor.py, observer.py, memory.py, mission.py, and evidence.py are DeprecationWarning shims over legacy.*. The installed breachpilot command maps to main:main.

Overview

python main.py --doctor
python main.py --target 10.0.0.50 --mode recon --goal initial_access
breachpilot --daemon --api-port 9000
python legacy/cli.py init-mission --config mission.yaml
python legacy/cli.py status

Flow A — main.py

Argument parser is main.parse_args (main.py:352-645). The --version flag prints BreachPilot <version> and exits.

Flag groups

Group names are the argparse argument groups in parse_args.

Notable defaults from parse_args: --config defaults to config.yaml; --eval and --benchmark use nargs="*" with default None (bare --eval is an empty list, meaning all oracle targets); --ctf-root-shell is store_true with default False (main.py:577-583); --api-host defaults to None (resolved to 127.0.0.1 in _run_daemon); --api-port defaults to None (resolved to 8765).

Dispatch order

Order of the gates in main() (main.py:1307-1528):

The graded --eval path (step 12) runs without --target and does not exit 2; exit 2 from tools.eval_harness.run_eval (tools/eval_harness.py:382-387) belongs to the legacy single-target path, which main() only reaches when --target is present.

python main.py --eval                       # graded suite, all oracle targets
python main.py --eval dvwa juice_shop --save-baseline
python main.py --eval --check-regression    # exit 1 on regression
python main.py --eval --target 10.0.0.50    # legacy single-target harness

Exit codes

_run_daemon (main.py:955-1057) refuses any --api-host outside 127.0.0.1 / localhost / ::1 with exit 2, builds webui/dist/ for --web via _ensure_webui_build, and serves create_app from app.py with uvicorn.

Console script

pyproject.toml:65-66 registers the installed command:

[project.scripts]
breachpilot = "main:main"

breachpilot takes the same flags as python main.py. python main.py with no arguments starts the WebUI daemon (--web); python main.py --menu forces the terminal menu.

Flow B — legacy/cli.py

Parser is legacy/cli.py:build_parser (legacy/cli.py:530-598). Every subcommand except init-mission accepts --mission-id after the subcommand (resume/reattach a named mission instead of the latest active one). Mission loading is _load_mission / _require_mission; the workspace root is _workspace_root (RESEARCH_WORKSPACE, default research_workspace) with the database at research.db.

Mission subcommands

python legacy/cli.py init-mission --config mission.yaml
python legacy/cli.py add-scope --allow "*.example.com" --notes "main scope"
python legacy/cli.py next-task --mission-id M-001
python legacy/cli.py run-task T-00001
python legacy/cli.py status

run-task gates through ScopeGate.check_scope, then RiskController, and marks needs_approval without executing when either side requires human approval (legacy/cli.py:298-352). Exit codes: 0 success, 1 error (including scope/risk blocks), 130 on Ctrl-C, and 1 with help text when no subcommand is given (legacy/cli.py:604-622).

Flow B compatibility shims

Root files are one-release proxies that warn and re-export legacy.* (see legacy/README.md). Each follows this shape:

import importlib
import sys
import warnings

warnings.warn("cli is legacy; use legacy.cli", DeprecationWarning, stacklevel=2)
_mod = importlib.import_module("legacy.cli")
sys.modules[__name__] = _mod

New code must import from legacy.* (Flow B) or tools.* (Flow A), never from the root shims.

Mission config — mission.yaml vs --config

mission.yaml is the example Flow B mission file consumed by legacy/cli.py init-mission --config mission.yaml. main.py --config is a different flag: it points at config.yaml (provider, model, MCP, and run settings), not at mission.yaml.

program_name: "Example Authorized Program"
objective: "Find valid, in-scope, non-destructive, reproducible vulnerabilities with evidence."
risk_profile: "high_authorized_testing"
allowed_assets:
  - "example.com"
  - "*.example.com"
disallowed_assets:
  - "payments.example.com"
forbidden_actions:
  - "denial_of_service"
rate_limits:
  default_requests_per_second: 2
  max_concurrent_requests: 3
testing_modes:
  - "recon"
  - "analysis"
accounts: []
notes: |
  Operator rules and program context.

Implementation note: legacy/mission.py also accepts id, target_assets, and notes keys in _MISSION_KEYS; max_commands_per_session and max_tasks_active are derived from the risk profile, not set directly in mission.yaml.

Related documentation

• CLI Reference
• Getting Started
• Architecture
• Runtime Flows
• Configuration Reference
• Legacy Flow B

Source map

• main.py
• legacy/cli.py
• cli.py
• agent_loop.py
• planner.py
• executor.py
• observer.py
• memory.py
• mission.py
• evidence.py
• mission.yaml
• legacy/mission.py
• legacy/README.md
• pyproject.toml
• tools/eval_harness.py
• docs/cli-reference.md