Skip to main content
Shannon provides a simple command-line interface for managing AI-powered penetration testing workflows. All commands use the ./shannon script with KEY=value style arguments.

​
Quick Reference

start

Start a new pentest workflow

workspaces

List all available workspaces

logs

View real-time workflow logs

query

Query workflow progress and state

stop

Stop all containers

​
Command Syntax

All Shannon commands follow this pattern: 
./shannon <command> [KEY=value ...]

​
Available Commands

CommandDescriptionCommon Usage
startStart a pentest workflow./shannon start URL=<url> REPO=<name>
workspacesList all workspaces./shannon workspaces
logsTail workflow logs./shannon logs ID=<workflow-id>
queryQuery workflow stateVia Temporal Web UI at http://localhost:8233
stopStop containers./shannon stop or ./shannon stop CLEAN=true
helpShow help message./shannon help

​
Environment Setup

Before running commands, ensure you have:
  1. API Keys: Set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN in .env
  2. Docker: Docker or Podman installed and running
  3. Repository: Target code in ./repos/<repo-name>/
# Setup
cp .env.example .env
# Edit .env to add your API key

# Clone target repository
git clone https://github.com/org/repo.git ./repos/my-repo

# Run pentest
./shannon start URL=https://example.com REPO=my-repo

​
Monitoring

​
Temporal Web UI

Access the Temporal Web UI for detailed workflow monitoring: 
http://localhost:8233
Features:
  • Real-time workflow progress
  • Query workflow state via getProgress
  • View workflow history and events
  • Inspect activity executions
  • Stack trace analysis for failures

​
Log Streaming

Stream logs in real-time: 
./shannon logs ID=example.com_shannon-1234567890

​
Workspace Management

List all workspaces and their status: 
./shannon workspaces

​
Output Locations

Shannon generates output in multiple locations:
Output TypeDefault LocationConfigurable Via
Workflow logs./audit-logs/<workspace-id>/workflow.logOUTPUT=<path>
Audit data./audit-logs/<workspace-id>/OUTPUT=<path>
Deliverables./repos/<repo>/deliverables/Fixed
ReportsGenerated in both locations-

​
Common Patterns

​
Basic Workflow

# Start pentest
./shannon start URL=https://app.example.com REPO=example-app

# Monitor in separate terminal
./shannon logs ID=app.example.com_shannon-1234567890

# Check Temporal UI
open http://localhost:8233

​
Named Workspace

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

# List workspaces
./shannon workspaces

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

​
Custom Configuration

# Use custom config and output directory
./shannon start URL=https://example.com REPO=my-repo \
  CONFIG=./configs/production.yaml \
  OUTPUT=./security-reports

​
Development Testing

# Fast iteration with minimal prompts
./shannon start URL=https://example.com REPO=my-repo \
  PIPELINE_TESTING=true

# Force rebuild after code changes
./shannon start URL=https://example.com REPO=my-repo \
  REBUILD=true

​
Error Handling

Shannon provides clear error messages for common issues: 
# Missing required parameters
./shannon start URL=https://example.com
# ERROR: URL and REPO are required

# Repository not found
./shannon start URL=https://example.com REPO=missing
# ERROR: Repository not found at ./repos/missing

# Missing API key
./shannon start URL=https://example.com REPO=my-repo
# ERROR: Set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN in .env

​
Next Steps

Start Command

Learn all options for starting workflows

Configuration

Explore YAML configuration options

Workspaces

Master workspace management and resume

Troubleshooting

Common issues and solutions

Build docs developers (and LLMs) love

Get started for freeTalk to us