CLI Reference

CLI Reference

Installation

pip install substr8

Current version: 1.7.2

Core Commands

substr8 proof verify

Verify a RunProof v2 JSON file.

substr8 proof verify <file>

Example:

substr8 proof verify runproof.json

Output:

╭──────────────────────────── Verification Result ─────────────────────────────╮
│ ✓ RunProof: VALID                                                            │
╰──────────────────────────────────────────────────────────────────────────────╯

  Proof ID   proof_ccfe7c4abd014eab
  Run ID     run_ade859b400e24d09
  Agent      demo/research-agent

Checks:
  ✓ schema
  ✓ hash_chain
  ✓ merkle_root
  ✓ signature

Verification checks:

  • schema — Valid RunProof v2 structure
  • hash_chain — Events form valid hash chain
  • merkle_root — Merkle root matches events
  • signature — Ed25519 signature valid

substr8 proof inspect

Inspect RunProof v2 details without verification.

substr8 proof inspect <file>

Output:

╭─────────────────────────── proof_ccfe7c4abd014eab ───────────────────────────╮
│ ✓ RunProof                                                                   │
╰──────────────────────────────────────────────────────────────────────────────╯

            Proof Details
╭─────────┬─────────────────────────╮
│ Field   │ Value                   │
├─────────┼─────────────────────────┤
│ Run ID  │ run_ade859b400e24d09    │
│ Agent   │ demo/research-agent     │
│ Runtime │ langgraph               │
│ Status  │ completed               │
│ Events  │ 6                       │
│ Started │ 2026-03-10 08:10:33 UTC │
│ Ended   │ 2026-03-10 08:10:33 UTC │
╰─────────┴─────────────────────────╯

                      Cryptographic Commitments
╭────────────┬───────────────────────────────────────────────────────╮
│ Field      │ Value                                                 │
├────────────┼───────────────────────────────────────────────────────┤
│ Event Root │ sha256:ba56701f663b204dccafc93968d34207de6b909dd7f... │
│ Proof Hash │ sha256:a65b14e11a1a96a436e3adcc129813c10538d50f1e6... │
│ Algorithm  │ ed25519                                               │
│ Public Key │ ed25519:09f2cb092ea8af1c94689b6cda0f80fe...           │
╰────────────┴───────────────────────────────────────────────────────╯

substr8 info

Show platform information and available modules.

substr8 info

Output:

  Verifiable AI Infrastructure

                            Components
╭──────────┬────────────┬─────────────────────────────────────────╮
│ Module   │ Status     │ Description                             │
├──────────┼────────────┼─────────────────────────────────────────┤
│ fdaa     │ ✓ ready    │ File-Driven Agent Architecture          │
│ gam      │ ✓ ready    │ Git-Native Agent Memory                 │
│ acc      │ ✓ ready    │ Agent Capability Control                │
│ dct      │ ✓ ready    │ Deterministic Capability Tokens         │
│ ril      │ ✓ ready    │ Runtime Integrity Layer                 │
│ mcp      │ ✓ ready    │ MCP Server - Universal framework bridge │
│ gateway  │ ✓ ready    │ Docker Swarm orchestration              │
╰──────────┴────────────┴─────────────────────────────────────────╯

substr8 status

Show connection and governance status.

substr8 status

Advanced Command Groups

The CLI includes additional command groups for power users:

GroupDescription
substr8 gamGit-Native Agent Memory
substr8 fdaaFile-Driven Agent Architecture
substr8 accAgent Capability Control
substr8 dctDeterministic Capability Tokens
substr8 rilRuntime Integrity Layer
substr8 mcpMCP Server commands
substr8 registryRun Registry queries
substr8 gatewayDocker Swarm orchestration
substr8 devDeveloper scaffolding

Use --help on any group for details:

substr8 gam --help
substr8 fdaa --help

GAM Commands

Git-Native Agent Memory for semantic memory operations.

# Initialize GAM in current repo
substr8 gam init
 
# Store a memory
substr8 gam remember "User prefers dark mode" --tags ui,preference
 
# Search memories
substr8 gam recall "user preferences"
 
# Show GAM status
substr8 gam status

FDAA Commands

File-Driven Agent Architecture for agent workspaces.

# Create a new agent workspace
substr8 fdaa init my-agent
 
# Start a chat session
substr8 fdaa chat my-agent
 
# Verify agent matches registered hash
substr8 fdaa verify my-agent

MCP Commands

Start and manage MCP servers for framework integration.

# Start local MCP server
substr8 mcp start
 
# Start with custom port
substr8 mcp start --port 9988

Environment Variables

VariableDescription
SUBSTR8_MCP_URLDefault MCP server URL
SUBSTR8_API_KEYAPI key for cloud access
SpecificationBasic LangGraph