CLI Reference
The BlackRainbow CLI is available as br or blackrainbow. Built with Click and Rich for structured terminal output.
Global Options
| Flag | Description |
|---|---|
--version | Print version and exit |
--help | Print help and exit |
br --version
# blackrainbow, version 0.1.0
br init
Initialize a new engagement config from a template.
br init [OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
--template | Choice: htb, webapp | htb | Template to start from |
--output | String | blackrainbow.yaml | Output config file path |
Behavior
- Copies the selected template to the output path.
- Exits with error if the output file already exists (will not overwrite).
- Exits with error if the template is not found.
Examples
# Default: htb template, writes blackrainbow.yaml
br init
# Webapp template
br init --template webapp
# Custom output path
br init --template htb --output engagements/box1.yaml
Templates
Templates live in the templates/ directory of the BlackRainbow repo:
| Template | File | Target Type | Use Case |
|---|---|---|---|
htb | templates/htb.yaml | network-service | HackTheBox, CTF, single host |
webapp | templates/webapp.yaml | web-application | Web application assessment |
Both templates include CHANGEME placeholders that must be replaced before running.
br run
Execute an engagement: generate, execute, and evaluate.
br run [OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
--config | String | blackrainbow.yaml | Engagement config file |
--plugins | String | (from config) | Override plugins, comma-separated |
--target | String | (from config) | Override target host |
--dry-run | Flag | false | Generate sequences but do not execute |
--max-attempts | Integer | 5 | Max iterations per plugin |
Behavior
- Loads and validates the YAML config.
- Applies CLI overrides (
--target,--plugins) on top of config values. - Imports built-in plugins and targets (lazy import for fast startup).
- Creates the engine and runs the full pipeline.
- Prints a summary with sequence counts, pass/fail totals.
Examples
# Run with default config
br run
# Dry run to preview attack sequences
br run --dry-run
# Override target
br run --target 10.10.10.99
# Override plugins
br run --plugins recon
# Custom config file
br run --config engagements/box1.yaml
# Full override
br run --config box1.yaml --target 10.10.10.99 --plugins recon --dry-run --max-attempts 3
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Engagement completed |
| 1 | Config not found or invalid |
br plugins
List all registered plugins.
br plugins
Displays a Rich table with columns: ID, Description, Colors.
Example Output
Registered Plugins
┏━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ ID ┃ Description ┃ Colors ┃
┡━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ recon │ Network and service enumeration, OSINT, target │ orange, red, green │
│ │ profiling │ │
└───────┴─────────────────────────────────────────────────┴────────────────────┘
br strategies
List all registered strategies.
br strategies
Displays a Rich table with columns: ID, Description.
br targets
List all registered target types.
br targets
Displays a Rich table with columns: Type, Class.
Example Output
Registered Targets
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Type ┃ Class ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ network-service │ NetworkServiceTarget │
└─────────────────┴───────────────────────┘
br status
Show framework status summary.
br status
Example Output
BlackRainbow v0.1.0
Plugins: 1 registered
Strategies: 0 registered
Targets: 1 registered
br banner
Display the ASCII banner.
br banner
Prints the full BlackRainbow ASCII art banner with the current version number.