Build from source & CLI

This guide covers the source-build workflow, common CLI commands, repository paths, and output locations. For the fastest first run, use the npx workflow in the Quick Start.

Throughout this site, command examples are shown as tabs. Pick npx or Build from source once and your choice is remembered on every page.

Prerequisites

• Docker
• Node.js 20.19+ (the source build’s toolchain needs it; the npx workflow runs on Node.js 18+)
• pnpm
• AI provider credentials

Clone and build

Use the source-build workflow if you want to run Shannon from a local clone, modify the open-source CLI, or keep the worker image built locally.

1. Clone Shannon:

   git clone https://github.com/KeygraphHQ/shannon.git
   cd shannon

2. Configure credentials:

   cp .env.example .env

3. Install dependencies and build:

   pnpm install
   pnpm build

4. Run a pentest:

   ./shannon start -u https://your-app.com -r /path/to/your-repo

At minimum, your .env file should include one supported AI provider credential, such as:

ANTHROPIC_API_KEY=your-api-key

Environment variables can also be exported directly:

export ANTHROPIC_API_KEY="your-api-key"

See AI Providers to choose a model and to set up OpenAI, xAI, AWS Bedrock, a custom LLM gateway, or a local model.

Prepare your repository

Shannon can scan any repository on your machine. Pass an absolute or relative path with -r. The target repository is mounted read-only inside the worker container.

npx (recommended)

npx @keygraph/shannon start -u https://example.com -r /path/to/repo

Build from source

./shannon start -u https://example.com -r ./relative/path

Common commands

Monitor progress:

npx (recommended)

npx @keygraph/shannon logs [<workspace>]                 # Defaults to the single running scan, else the most recent.
npx @keygraph/shannon logs [<workspace>] --agent <name>  # Tail one agent only; --list-agents lists them.
npx @keygraph/shannon status [<workspace>]               # Same default; add --json for a machine-readable snapshot.
npx @keygraph/shannon scans                              # List running and completed scans.
npx @keygraph/shannon version                            # Print the Shannon version.

Build from source

./shannon logs [<workspace>]                 # Defaults to the single running scan, else the most recent.
./shannon logs [<workspace>] --agent <name>  # Tail one agent only; --list-agents lists them.
./shannon status [<workspace>]               # Same default; add --json for a machine-readable snapshot.
./shannon scans                              # List running and completed scans.
./shannon version                            # Print the Shannon version.

With no workspace, logs and status follow the single running scan; when several are running, name one. Every scan writes one combined .shannon/workflow.log plus a log per agent under .shannon/agents/, which --agent reads.

Open the Temporal Web UI for detailed monitoring:

open http://localhost:8233

Stop Shannon:

npx (recommended)

npx @keygraph/shannon stop [<workspace>]   # Stop one scan (defaults to the single running scan; confirms first, add --yes to skip).
npx @keygraph/shannon stop --all           # Stop every scan (Temporal stays up).
npx @keygraph/shannon reset                # Stop everything and permanently remove all Temporal data (you must type confirm).

Build from source

./shannon stop [<workspace>]   # Stop one scan (defaults to the single running scan; confirms first, add --yes to skip).
./shannon stop --all           # Stop every scan (Temporal stays up).
./shannon reset                # Stop everything and permanently remove all Temporal data (you must type confirm).

Usage examples

npx (recommended)

# Basic pentest.
npx @keygraph/shannon start -u https://example.com -r /path/to/repo

# With a configuration file.
npx @keygraph/shannon start -u https://example.com -r /path/to/repo -c /path/to/my-config.yaml

# Custom output directory.
npx @keygraph/shannon start -u https://example.com -r /path/to/repo -o ./my-reports

# Named workspace.
npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w q1-audit

# Stream the log until the scan finishes, then exit on its outcome (useful in CI).
npx @keygraph/shannon start -u https://example.com -r /path/to/repo --follow

# List running and completed scans.
npx @keygraph/shannon scans

Build from source

./shannon start -u https://example.com -r /path/to/repo
./shannon start -u https://example.com -r /path/to/repo -c /path/to/my-config.yaml
./shannon start -u https://example.com -r /path/to/repo -o ./my-reports
./shannon start -u https://example.com -r /path/to/repo -w q1-audit
./shannon start -u https://example.com -r /path/to/repo --follow
./shannon scans

# Rebuild the worker image.
./shannon build --no-cache

See the CLI reference for the full list of commands and flags.

Output and results

Results are saved to the workspaces directory:

• ./workspaces/ in source-build mode
• ~/.shannon/workspaces/ in npx mode

Use -o <path> to copy deliverables to a custom output directory after a run completes.

Output structure. The run directory’s top level holds the final report, in PDF and Markdown; everything else is nested under a hidden .shannon/ directory:

workspaces/{hostname}_{sessionId}/
|-- Security-Assessment-Report.pdf  # the final report (PDF)
|-- Security-Assessment-Report.md   # the final report (Markdown)
`-- .shannon/                       # internals
    |-- deliverables/               # report source, per-phase analysis, queues
    |-- agents/                     # per-agent logs
    |-- prompts/                    # rendered prompts
    |-- scratchpad/                 # screenshots, scripts
    |-- session.json                # resume state
    `-- workflow.log

For workspace naming and resuming interrupted runs, see Workspaces & Resuming.