FEAT: Convert pyrit_scan mode-flags to subcommands + stale docs corrections

.pyrit_conf_example

@@ -33,7 +33,7 @@ memory_db_type: sqlite
 # - A dictionary with 'name' and optional 'args' for parameters
 #
 # Parameters are lists of strings. Use the CLI command
-# `pyrit_scan --list-initializers` to see available parameters.
+# `pyrit_scan list-initializers` to see available parameters.
 #
 # Example:
 # initializers:

doc/blog/2026_07_09_scenarios.md

@@ -25,7 +25,7 @@ Open one up and you'll find the same four things working together: a **dataset o
 Let's say you want a wide read on a new target. The broadest scenario in the catalog is `RapidResponse` — a comprehensive sweep across the most common attack techniques and the full AIRT harm-category catalog. The [**Scanner**](../scanner/0_scanner.md) — PyRIT's single-command entry point for running any scenario — makes it one line:
 
 ```bash
-pyrit_scan airt.rapid_response --target my_target
+pyrit_scan run airt.rapid_response --target my_target
 ```
 
 That one command does a lot. Behind the scenes, initializers populate the registries (techniques, targets, datasets); the CLI resolves `airt.rapid_response` and `my_target`, instantiates `RapidResponse`, and runs it. Out of the box (using the default configuration for techniques ie `--techniques default`) it sends `role_play` and `many_shot` attacks plus a baseline pass — across seven AIRT harm categories: hate, fairness, violence, sexual, harassment, misinformation, leakage. Switch to `--techniques single_turn` to swap in the single-turn pool — `role_play`, `context_compliance`, `crescendo_simulated`, plus the persona-driven crescendo variants (`crescendo_movie_director`, `crescendo_history_lecture`, `crescendo_journalist_interview`). `--techniques multi_turn` picks up the multi-turn pool instead: `many_shot`, `tap`, `pair`, and `red_teaming`.

doc/code/scenarios/2_custom_scenario_parameters.ipynb

@@ -101,7 +101,7 @@
     "Each `Parameter` carries:\n",
     "\n",
     "- **name**: dict key in `self.params`, converted to `--kebab-case` for the CLI\n",
-    "- **description**: shown in `--list-scenarios` and `--help`\n",
+    "- **description**: shown in `list-scenarios` and `--help`\n",
     "- **default**: value used when not supplied; deep-copied per run\n",
     "- **param_type**: `str`, `int`, `float`, `bool`, a `Literal[...]`/`Enum` (a\n",
     "  constrained scalar that carries its own allowed set), a `list[...]` of any of\n",
@@ -197,10 +197,10 @@
     "\n",
     "```bash\n",
     "# Use the declared default (5)\n",
-    "pyrit_scan airt.scam --target my_target --initializers target\n",
+    "pyrit_scan run airt.scam --target my_target --initializers target\n",
     "\n",
     "# Override\n",
-    "pyrit_scan airt.scam --target my_target --initializers target --max-turns 10\n",
+    "pyrit_scan run airt.scam --target my_target --initializers target --max-turns 10\n",
     "```\n",
     "\n",
     "The same flags work in `pyrit_shell`:\n",
@@ -209,18 +209,13 @@
     "pyrit_shell> run airt.scam --target my_target --initializers target --max-turns 10\n",
     "```\n",
     "\n",
-    "Declared flags also show up in `pyrit_scan <scenario> --help`, alongside\n",
-    "the built-in options:\n",
+    "Scenario-declared flags don't appear in `pyrit_scan run <scenario> --help`\n",
+    "(that shows only the built-in run options); use `list-scenarios` to discover\n",
+    "a scenario's parameters.\n",
     "\n",
-    "```bash\n",
-    "pyrit_scan airt.scam --help\n",
-    "# ...\n",
-    "#   --max-turns MAX_TURNS  Conversation turn cap\n",
-    "```\n",
-    "\n",
-    "## Discovering parameters via --list-scenarios\n",
+    "## Discovering parameters via `list-scenarios`\n",
     "\n",
-    "`--list-scenarios` prints declared parameters alongside each scenario's\n",
+    "`pyrit_scan list-scenarios` prints declared parameters alongside each scenario's\n",
     "other metadata (description, techniques, datasets). The same formatter the\n",
     "CLI uses is callable programmatically:"
    ]

doc/code/scenarios/2_custom_scenario_parameters.py

@@ -67,7 +67,7 @@
 # Each `Parameter` carries:
 #
 # - **name**: dict key in `self.params`, converted to `--kebab-case` for the CLI
-# - **description**: shown in `--list-scenarios` and `--help`
+# - **description**: shown in `list-scenarios` and `--help`
 # - **default**: value used when not supplied; deep-copied per run
 # - **param_type**: `str`, `int`, `float`, `bool`, a `Literal[...]`/`Enum` (a
 #   constrained scalar that carries its own allowed set), a `list[...]` of any of
@@ -135,10 +135,10 @@
 #
 # ```bash
 # # Use the declared default (5)
-# pyrit_scan airt.scam --target my_target --initializers target
+# pyrit_scan run airt.scam --target my_target --initializers target
 #
 # # Override
-# pyrit_scan airt.scam --target my_target --initializers target --max-turns 10
+# pyrit_scan run airt.scam --target my_target --initializers target --max-turns 10
 # ```
 #
 # The same flags work in `pyrit_shell`:
@@ -147,18 +147,13 @@
 # pyrit_shell> run airt.scam --target my_target --initializers target --max-turns 10
 # ```
 #
-# Declared flags also show up in `pyrit_scan <scenario> --help`, alongside
-# the built-in options:
+# Scenario-declared flags don't appear in `pyrit_scan run <scenario> --help`
+# (that shows only the built-in run options); use `list-scenarios` to discover
+# the full list of a scenario's parameters.
 #
-# ```bash
-# pyrit_scan airt.scam --help
-# # ...
-# #   --max-turns MAX_TURNS  Conversation turn cap
-# ```
-#
-# ## Discovering parameters via --list-scenarios
+# ## Discovering parameters via `list-scenarios`
 #
-# `--list-scenarios` prints declared parameters alongside each scenario's
+# `pyrit_scan list-scenarios` prints declared parameters alongside each scenario's
 # other metadata (description, techniques, datasets). The same formatter the
 # CLI uses is callable programmatically:
 

doc/getting_started/pyrit_conf.md

@@ -182,7 +182,7 @@ Client settings for connecting to or launching a PyRIT backend.
 | Field | Description | Default |
 |---|---|---|
 | `url` | Backend URL used when `--server-url` is omitted | `http://localhost:8000` |
-| `startup_timeout` | Seconds `pyrit_scan --start-server` waits for a healthy backend before terminating the spawned process | `120` |
+| `startup_timeout` | Seconds `pyrit_scan start-server` waits for a healthy backend before terminating the spawned process | `120` |
 
 `startup_timeout` must be a finite number greater than zero. The `--startup-timeout` CLI option overrides the configured value for an individual scanner invocation.
 
@@ -208,7 +208,7 @@ flowchart LR
 | -------- | ---------------------- | ----------------------------------------------------------------------- |
 | Lowest   | `~/.pyrit/.pyrit_conf` | Loaded automatically if it exists                                       |
 | Medium   | Explicit config file   | Passed via `--config-file` (CLI) or `config_file` parameter             |
-| Highest  | Individual arguments   | CLI flags like `--database`, `--initializers`, or API keyword arguments |
+| Highest  | Individual arguments   | CLI flags like `--initializers` or API keyword arguments               |
 
 This means you can set sensible defaults in `~/.pyrit/.pyrit_conf` and override specific values on a per-run basis without modifying the file.
 
@@ -230,10 +230,10 @@ Because initializers run last, they can modify anything set up in earlier steps
 The CLI and shell automatically load `~/.pyrit/.pyrit_conf`. You can also point to a different config file:
 
 ```bash
-pyrit_scan run --config-file ./my_project_config.yaml --database InMemory
+pyrit_scan run airt.scam --config-file ./my_project_config.yaml
 ```
 
-Individual CLI arguments (like `--database`) override values from the config file.
+Individual CLI arguments (like `--initializers`) override values from the config file.
 
 ### From Python
 

doc/index.md

@@ -125,7 +125,7 @@ initializers:
 Run security assessments from the command line with `pyrit_scan` or the interactive `pyrit_shell`. Execute built-in scenarios against your AI targets.
 
 ```bash
-pyrit_scan airt.scam --target openai_chat
+pyrit_scan run airt.scam --target openai_chat
 ```
 
 ![scanner-demo](scanner-demo.png)

doc/scanner/0_scanner.md

@@ -23,7 +23,7 @@ PyRIT provides two command-line interfaces:
 
 ```bash
 # Run the Foundry RedTeamAgent scenario against your configured target
-pyrit_scan foundry.red_team_agent --target openai_chat --initializers target --techniques base64
+pyrit_scan run foundry.red_team_agent --target openai_chat --initializers target --techniques base64
 ```
 
 ## Built-in Scenarios