CLI Commands

The Shannon CLI provides commands for managing penetration testing workflows through a simple, intuitive interface.

start

Start a new penetration testing workflow or resume an existing workspace.

Usage

./shannon start URL=<url> REPO=<name>

Required Parameters

URL

string

required

Target URL to test (e.g., https://example.com)

REPO

string

required

Repository folder name under ./repos/ containing the target application source codeImportant: This must be a folder name (e.g., my-repo), not an absolute path. Clone or symlink your repository to ./repos/ first:

git clone https://github.com/org/repo.git ./repos/my-repo
# or symlink existing repo
ln -s /path/to/existing/repo ./repos/my-repo

Optional Parameters

CONFIG

string

Path to YAML configuration file with auth settings, MFA/TOTP, and testing parameters

./shannon start URL=https://example.com REPO=my-repo CONFIG=./configs/my-config.yaml

OUTPUT

string

default:"./audit-logs/"

Custom output directory for reports and logs

./shannon start URL=https://example.com REPO=my-repo OUTPUT=./my-reports

WORKSPACE

string

Named workspace identifier. Enables resuming previous runs or creating organized workspaces

New workspace: Creates a new workspace with the specified name
Resume: If workspace exists, automatically resumes from last checkpoint
Auto-named: Without this flag, workspaces are auto-named from URL + timestamp

# Create new named workspace
./shannon start URL=https://example.com REPO=my-repo WORKSPACE=q1-audit

# Resume existing workspace (same command)
./shannon start URL=https://example.com REPO=my-repo WORKSPACE=q1-audit

PIPELINE_TESTING

boolean

default:"false"

Enable minimal prompts and fast retries for testing and development

./shannon start URL=https://example.com REPO=my-repo PIPELINE_TESTING=true

ROUTER

boolean

default:"false"

Enable multi-model routing through claude-code-router for alternative providersSupports OpenAI, OpenRouter, and other providers. Requires provider API keys in .env

./shannon start URL=https://example.com REPO=my-repo ROUTER=true

REBUILD

boolean

default:"false"

Force Docker rebuild with --no-cache flagUse when code changes aren’t being picked up by the container

./shannon start URL=https://example.com REPO=my-repo REBUILD=true

Examples

Basic workflow

./shannon start URL=https://example.com REPO=repo-name

Output:

Starting Shannon containers...
Waiting for Temporal to be ready...
Temporal is ready!

✓ Workflow started: example.com_shannon-1234567890
Monitor at: http://localhost:8233

Named workspace for organized testing

./shannon start URL=https://example.com REPO=repo-name WORKSPACE=q1-audit

Creates a workspace named q1-audit that can be resumed later with the same command.

Custom configuration and output

./shannon start URL=https://example.com REPO=repo-name CONFIG=./config.yaml OUTPUT=./reports

Uses custom YAML config and saves reports to ./reports/ instead of default ./audit-logs/

Multi-model routing with OpenAI

./shannon start URL=https://example.com REPO=repo-name ROUTER=true

Output:

Starting claude-code-router...
Waiting for router to start...
Starting Shannon containers...
Temporal is ready!

✓ Workflow started with router mode enabled

Error Handling

Missing required parameters

./shannon start URL=https://example.com

Error:

ERROR: URL and REPO are required
Usage: ./shannon start URL=<url> REPO=<name>

Repository not found

./shannon start URL=https://example.com REPO=nonexistent

Error:

ERROR: Repository not found at ./repos/nonexistent

Place your target repository under the ./repos/ directory

Missing API credentials

Error:

ERROR: Set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN in .env
       (or use CLAUDE_CODE_USE_BEDROCK=1 for AWS Bedrock,
        CLAUDE_CODE_USE_VERTEX=1 for Google Vertex AI,
        or ROUTER=true with OPENAI_API_KEY or OPENROUTER_API_KEY)

logs

Tail real-time logs for a specific workflow.

Usage

./shannon logs ID=<workflow-id>

Required Parameters

string

required

Workflow ID to view logs forFormat: {hostname}_{sessionId} (e.g., example.com_shannon-1234567890)

Examples

Tail workflow logs

./shannon logs ID=example.com_shannon-1234567890

Output:

Tailing workflow log: ./audit-logs/example.com_shannon-1234567890/workflow.log

[2026-03-03 10:15:32] Starting Pre-Recon phase...
[2026-03-03 10:15:45] Running nmap scan on example.com
[2026-03-03 10:16:02] Discovered 3 open ports
[2026-03-03 10:16:15] Analyzing source code...
...

Resume workflow logs

./shannon logs ID=q1-audit_resume_123

Automatically finds the correct log file for resumed workflows.

Error Handling

Workflow not found

./shannon logs ID=invalid-workflow-id

Error:

ERROR: Workflow log not found for ID: invalid-workflow-id

Possible causes:
  - Workflow hasn't started yet
  - Workflow ID is incorrect

Check the Temporal Web UI at http://localhost:8233 for workflow details

Notes

The logs command automatically searches for log files in:
1. Default location: ./audit-logs/{ID}/workflow.log
2. Resume workflow locations
3. Custom output directories (up to 3 levels deep)
Logs are displayed in real-time using tail -f
Press Ctrl+C to stop tailing

workspaces

List all active and completed workspaces with their status.

Usage

./shannon workspaces

Examples

List all workspaces

./shannon workspaces

Output:

Starting Shannon containers...
Temporal is ready!

Active Workspaces:

Name: q1-audit
URL: https://example.com
Status: Running (Vulnerability Analysis phase)
Started: 2026-03-03 09:30:15
Progress: 3/5 phases complete

Name: staging-test
URL: https://staging.example.com
Status: Completed
Started: 2026-03-02 14:20:00
Completed: 2026-03-02 16:45:30

Total: 2 workspaces

Notes

Requires Temporal containers to be running (automatically started)
Shows both in-progress and completed workflows
Displays workspace names, target URLs, status, and timestamps
Use workspace names with the WORKSPACE parameter to resume

stop

Stop Shannon containers and optionally clean up all data.

Usage

./shannon stop [CLEAN=true]

Optional Parameters

CLEAN

boolean

default:"false"

Remove all data including Docker volumesWithout CLEAN: Preserves workflow data, databases, and state for resumingWith CLEAN=true: Complete cleanup including all volumes and persistent data

./shannon stop CLEAN=true

Examples

Stop containers (preserve data)

./shannon stop

Output:

Stopping Shannon containers...

[+] Running 5/5
 ✔ Container shannon-worker-1    Stopped
 ✔ Container shannon-temporal-1  Stopped
 ✔ Container shannon-postgres-1  Stopped
 ✔ Container shannon-router-1    Stopped
 ✔ Network shannon_default       Removed

Workflow data is preserved. Running ./shannon start again will resume from checkpoints.

Stop and clean all data

./shannon stop CLEAN=true

Output:

Stopping Shannon containers and removing volumes...

[+] Running 8/8
 ✔ Container shannon-worker-1     Removed
 ✔ Container shannon-temporal-1   Removed
 ✔ Container shannon-postgres-1   Removed
 ✔ Container shannon-router-1     Removed
 ✔ Volume shannon_postgres-data   Removed
 ✔ Volume shannon_temporal-data   Removed
 ✔ Network shannon_default        Removed

All workflow state, databases, and persistent data removed.

Notes

Default stop preserves Temporal workflow state and PostgreSQL data
Use CLEAN=true only when you want to completely reset Shannon
Audit logs in ./audit-logs/ are NOT removed by CLEAN=true
Router container is always stopped (uses --profile router)

help

Display Shannon CLI help information with ASCII banner and usage examples.

Usage

./shannon help
# or
./shannon --help
# or
./shannon -h
# or
./shannon

Output

  ███████╗██╗  ██╗ █████╗ ███╗   ██╗███╗   ██╗ ██████╗ ███╗   ██╗
  ██╔════╝██║  ██║██╔══██╗████╗  ██║████╗  ██║██╔═══██╗████╗  ██║
  ███████╗███████║███████║██╔██╗ ██║██╔██╗ ██║██║   ██║██╔██╗ ██║
  ╚════██║██╔══██║██╔══██║██║╚██╗██║██║╚██╗██║██║   ██║██║╚██╗██║
  ███████║██║  ██║██║  ██║██║ ╚████║██║ ╚████║╚██████╔╝██║ ╚████║
  ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝  ╚═══╝

           AI Penetration Testing Framework

Usage:
  ./shannon start URL=<url> REPO=<name>   Start a pentest workflow
  ./shannon workspaces                    List all workspaces
  ./shannon logs ID=<workflow-id>         Tail logs for a specific workflow
  ./shannon stop                          Stop all containers
  ./shannon help                          Show this help message

Options for 'start':
  REPO=<name>            Folder name under ./repos/ (e.g. REPO=repo-name)
  CONFIG=<path>          Configuration file (YAML)
  OUTPUT=<path>          Output directory for reports (default: ./audit-logs/)
  WORKSPACE=<name>       Named workspace (auto-resumes if exists, creates if new)
  PIPELINE_TESTING=true  Use minimal prompts for fast testing
  ROUTER=true            Route requests through claude-code-router (multi-model support)

Options for 'stop':
  CLEAN=true             Remove all data including volumes

Examples:
  ./shannon start URL=https://example.com REPO=repo-name
  ./shannon start URL=https://example.com REPO=repo-name WORKSPACE=q1-audit
  ./shannon start URL=https://example.com REPO=repo-name CONFIG=./config.yaml
  ./shannon start URL=https://example.com REPO=repo-name OUTPUT=./my-reports
  ./shannon workspaces
  ./shannon logs ID=example.com_shannon-1234567890
  ./shannon stop CLEAN=true

Monitor workflows at http://localhost:8233

Notes

Default command when no arguments provided
Also triggered by --help, -h, or invalid commands
Displays full ASCII banner and comprehensive usage information

Get Started

Core Concepts

Guides

CLI Reference

start

Usage

Required Parameters

Optional Parameters

Examples

Error Handling

logs

Usage

Required Parameters

Examples

Error Handling

Notes

workspaces

Usage

Examples

Notes

stop

Usage

Optional Parameters

Examples

Notes

help

Usage

Output

Notes

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

CLI Reference

​start

​Usage

​Required Parameters

​Optional Parameters

​Examples

​Error Handling

​logs

​Usage

​Required Parameters

​Examples

​Error Handling

​Notes

​workspaces

​Usage

​Examples

​Notes

​stop

​Usage

​Optional Parameters

​Examples

​Notes

​help

​Usage

​Output

​Notes

Build docs developers (and LLMs) love

start

Usage

Required Parameters

Optional Parameters

Examples

Error Handling

logs

Usage

Required Parameters

Examples

Error Handling

Notes

workspaces

Usage

Examples

Notes

stop

Usage

Optional Parameters

Examples

Notes

help

Usage

Output

Notes