CLI Reference

Installation

pip install substr8

Commands

substr8 init

Scaffold a new project with framework examples.

substr8 init [path] [options]

Options:

• --framework — all, langgraph, pydantic-ai, autogen (default: all)
• --api-key — Pre-fill API key in .env
• --minimal — Create minimal structure

substr8 run

Run an agent with governance enabled.

substr8 run <script> [options]

Options:

• --framework — Force framework detection (auto, langgraph, pydantic-ai, autogen)
• --local / --cloud — Use local or cloud MCP (default: --cloud)
• --out — Output directory for RunProof (default: ./runproofs)
• --mcp-url — Custom MCP server URL
• --no-tarball — Don’t create .runproof.tgz archive
• --label — Add labels in k=v format (can repeat)

Examples:

# Basic run
substr8 run agent.py
 
# Force framework
substr8 run agent.py --framework langgraph
 
# Local MCP server
substr8 run agent.py --local
 
# Custom output
substr8 run agent.py --out ./proofs --label env=prod

substr8 verify

Verify a RunProof bundle offline.

substr8 verify <path> [options]

Options:

• --json — Output as JSON
• --strict — Also verify signature

Exit codes:

• 0 — Valid
• 40 — Root hash mismatch
• 41 — Ledger chain invalid
• 42 — CIA validation failed
• 43 — GAM validation failed
• 44 — Signature invalid

substr8 mcp

MCP server commands.

# Start local MCP server
substr8 mcp start --local
 
# Start with auth required
substr8 mcp start --local --require-auth
 
# Custom port
substr8 mcp start --local --port 9988

substr8 connect

Connect to a local MCP server (for IDEs and tools).

# Connect to default local server
substr8 connect
 
# Connect with custom URL
substr8 connect --url http://localhost:9988

The connection is persisted in ~/.substr8/config.json.

substr8 disconnect

Disconnect from the current MCP server.

substr8 disconnect

substr8 status

Show current connection and governance status.

substr8 status

Output:

Substr8 Status
━━━━━━━━━━━━━━
MCP:     connected (local @ localhost:9988)
Mode:    governance enabled
Runs:    12 total, 3 active
Version: 1.5.0

substr8 info

Show platform information.

substr8 info

substr8 badge

Generate README badge for a run.

substr8 badge <run-id>

Output:

[![Verified by Substr8](https://verify.substr8labs.com/badge/run-6c39af.svg)](https://verify.substr8labs.com/run/run-6c39af)

Environment Variables