CLI Reference

Complete reference for the rai command-line interface.

Global Options

These options are available on all commands:

Flag	Short	Description
`--version`	`-V`	Show version and exit
`--format`	`-f`	Output format: `human`, `json`, or `table`
`--verbose`	`-v`	Increase verbosity (`-v`, `-vv`, `-vvv`)
`--quiet`	`-q`	Suppress non-error output
`--help`		Show help and exit

Project

`rai init`

Initialize a RaiSE project in the current directory. Detects project type (greenfield or brownfield), creates .raise/manifest.yaml, and sets up the project structure.

With --detect, also analyzes code conventions and generates guardrails.

Flag	Short	Description
`--name`	`-n`	Project name (defaults to directory name)
`--path`	`-p`	Project path (defaults to current directory)
`--detect`	`-d`	Detect conventions and generate `guardrails.md`

# New project
rai init

# Named project
rai init --name my-api

# Existing project with convention detection
rai init --detect

Session

`rai session start`

Start a new working session. Increments the session counter and sets active session state. Checks for orphaned sessions (started but not closed) and warns if found.

With --context, outputs a token-optimized context bundle (~150 tokens) assembled from your developer profile, session state, and memory graph.

Flag	Short	Description
`--name`	`-n`	Your name (required for first-time setup)
`--project`	`-p`	Project path to associate with this session
`--agent`		Agent type (e.g., `claude-code`, `cursor`). Default: `unknown`
`--context`		Output a context bundle for AI consumption

# First-time setup
rai session start --name "Alice" --project .

# Start session with context bundle
rai session start --project . --context

# Simple start
rai session start

`rai session close`

End the current working session. With --summary or --state-file, performs a full structured close — records session, patterns, corrections, and updates state.

Flag	Short	Description
`--summary`	`-s`	Session summary
`--type`	`-t`	Session type (feature, research, maintenance, etc.)
`--pattern`		Pattern description to record
`--correction`		Coaching correction observed
`--correction-lesson`		Lesson from the correction
`--state-file`		YAML file with full structured session output
`--session`		Session ID to close (e.g., `SES-177`). Falls back to `RAI_SESSION_ID` env var
`--project`	`-p`	Project path

# Simple close
rai session close

# Close with summary
rai session close --summary "Implemented auth module" --type feature

# Close with pattern learned
rai session close --summary "Refactored tests" --type maintenance \
  --pattern "Use fixtures for database setup"

Memory

`rai memory query`

Search the unified memory for relevant concepts. The memory contains all context sources: governance (principles, requirements, terms), memory (patterns, calibration, sessions), skills (workflow metadata), and work (epics, stories, decisions).

Flag	Short	Description
`--format`	`-f`	Output format: `human` or `json`
`--output`	`-o`	Output file path (default: stdout)
`--strategy`	`-s`	Query strategy: `keyword_search` or `concept_lookup`
`--types`	`-t`	Filter by types (comma-separated: `pattern`, `calibration`, `principle`, etc.)
`--edge-types`		Filter by edge types (comma-separated: `constrained_by`, `depends_on`, etc.)
`--limit`	`-l`	Maximum number of results (default: 10)
`--index`	`-i`	Memory index path

# Search by keywords
rai memory query "planning estimation"

# Filter to patterns only
rai memory query "testing" --types pattern,calibration

# Lookup specific concept by ID
rai memory query "PAT-001" --strategy concept_lookup

# Output as JSON
rai memory query "velocity" --format json

`rai memory context`

Show full architectural context for a module. Returns the module’s bounded context (domain), architectural layer, applicable guardrails (constraints), and module dependencies.

Flag	Short	Description
`--format`	`-f`	Output format: `human` or `json`
`--index`	`-i`	Memory index path

# Show context for memory module
rai memory context mod-memory

# JSON output
rai memory context mod-memory --format json

`rai memory build`

Build the unified memory index from all sources: governance documents, memory (patterns, calibration, sessions), work tracking (epics, stories), skills, and components from discovery.

Flag	Short	Description
`--output`	`-o`	Path to save index JSON

# Build index to default location
rai memory build

# Save to custom location
rai memory build --output custom_index.json

`rai memory validate`

Validate memory index structure and relationships. Checks for cycles in depends_on relationships, valid relationship types, and that all edge targets exist as nodes.

Flag	Short	Description
`--index`	`-i`	Path to index JSON file

# Validate default index
rai memory validate

# Validate specific index file
rai memory validate --index custom_index.json

`rai memory list`

List concepts in the memory index. Shows concepts for inspection and debugging.

Flag	Short	Description
`--format`	`-f`	Output format: `human`, `json`, or `table`
`--output`	`-o`	Output file path (default: stdout)
`--index`	`-i`	Memory index path
`--memory-only` / `--all`		Show only memory types (pattern, calibration, session) or all

# Show summary table
rai memory list

# Show only patterns/calibrations/sessions
rai memory list --memory-only

# Export as JSON
rai memory list --format json --output memory.json

`rai memory extract`

Extract concepts from governance markdown files. If no file path is provided, extracts from all standard governance locations (governance/prd.md, governance/vision.md, framework/reference/constitution.md).

Flag	Short	Description
`--format`	`-f`	Output format: `human` or `json`

# Extract from all governance files
rai memory extract

# Extract from specific file
rai memory extract governance/prd.md

`rai memory add-pattern`

Add a new pattern to memory. Patterns capture learnings from development — process improvements, technical discoveries, architectural decisions.

Flag	Short	Description
`--context`	`-c`	Context keywords (comma-separated)
`--type`	`-t`	Pattern type: `codebase`, `process`, `architecture`, `technical` (default: `process`)
`--from`	`-f`	Story/session where learned
`--scope`	`-s`	Memory scope: `global`, `project`, `personal` (default: `project`)
`--memory-dir`	`-m`	Memory directory path (overrides scope)

# Add a process pattern
rai memory add-pattern "HITL before commits" -c "git,workflow"

# Add a technical pattern
rai memory add-pattern "Use capsys for stdout tests" -t technical -c "pytest,testing"

# Add with source reference
rai memory add-pattern "BFS reuse across modules" -t architecture --from S2.3

# Add to personal scope
rai memory add-pattern "My workflow preference" --scope personal

`rai memory add-calibration`

Add calibration data for a completed story. Tracks estimate vs. actual duration for velocity analysis.

Flag	Short	Description
`--name`		Story name (required)
`--size`	`-s`	T-shirt size: `XS`, `S`, `M`, `L`, `XL` (required)
`--actual`	`-a`	Actual minutes spent (required)
`--estimated`	`-e`	Estimated minutes
`--sp`		Story points
`--kata` / `--no-kata`		Whether kata cycle was followed (default: yes)
`--notes`	`-n`	Additional notes
`--scope`	`-s`	Memory scope: `global`, `project`, `personal`
`--memory-dir`	`-m`	Memory directory path

# Basic calibration
rai memory add-calibration S3.5 --name "Skills Integration" -s XS -a 20

# With estimate for velocity calculation
rai memory add-calibration S3.5 --name "Skills Integration" -s XS -a 20 -e 60

# Full details
rai memory add-calibration S3.5 --name "Skills Integration" -s XS -a 20 -e 60 --sp 2 -n "Hook-assisted"

`rai memory add-session`

Add a session record to memory. Sessions are developer-specific and always written to the personal directory.

Flag	Short	Description
`--outcomes`	`-o`	Session outcomes (comma-separated)
`--type`	`-t`	Session type (default: `story`)
`--log`	`-l`	Path to session log file
`--memory-dir`	`-m`	Memory directory path

# Basic session
rai memory add-session "S3.5 Skills Integration"

# With outcomes
rai memory add-session "S3.5 Skills Integration" -o "Writer API,Hooks setup,CLI commands"

# Full details
rai memory add-session "S3.5 Skills Integration" -t story -o "Writer API,Hooks" \
  -l "dev/sessions/2026-02-02-s3.5.md"

`rai memory emit-work`

Emit a work lifecycle event for Lean flow analysis. Tracks work items (epics, stories) through normalized phases to enable lead time, wait time, WIP, and bottleneck analysis.

Phases: design, plan, implement, review.

Flag	Short	Description
`--event`	`-e`	Event type: `start`, `complete`, `blocked`, `unblocked`, `abandoned` (default: `start`)
`--phase`	`-p`	Phase: `design`, `plan`, `implement`, `review` (default: `design`)
`--blocker`	`-b`	Blocker description (for `blocked` events)

# Epic lifecycle
rai memory emit-work epic E9 --event start --phase design
rai memory emit-work epic E9 -e complete -p design

# Story lifecycle
rai memory emit-work story S9.4 --event start --phase implement
rai memory emit-work story S9.4 -e complete -p implement

# Work blocked
rai memory emit-work story S9.4 -e blocked -p plan -b "unclear requirements"

`rai memory emit-session`

Emit a session event to telemetry. Records session completion for local learning and insights.

Flag	Short	Description
`--type`	`-t`	Session type: `story`, `research`, `maintenance`, etc. (default: `story`)
`--outcome`	`-o`	Session outcome: `success`, `partial`, `abandoned` (default: `success`)
`--duration`	`-d`	Session duration in minutes
`--stories`	`-f`	Stories worked on (comma-separated)

# Basic session complete
rai memory emit-session --type story --outcome success

# With duration and stories
rai memory emit-session -t story -o success -d 45 -f S9.1,S9.2,S9.3

`rai memory emit-calibration`

Emit a calibration event to telemetry. Records estimate vs. actual for velocity tracking. Velocity is calculated automatically: estimated / actual (>1.0 = faster than estimated).

Flag	Short	Description
`--size`	`-s`	T-shirt size: `XS`, `S`, `M`, `L` (default: `S`)
`--estimated`	`-e`	Estimated duration in minutes
`--actual`	`-a`	Actual duration in minutes

# Story completed faster than estimated
rai memory emit-calibration S9.4 --size S --estimated 30 --actual 15

# Story took longer
rai memory emit-calibration S9.4 -s M -e 60 -a 90

`rai memory viz`

Generate an interactive HTML visualization of the memory graph. Creates a self-contained HTML file with a D3.js force-directed graph. Nodes are color-coded by type, filterable, zoomable, and searchable.

Flag	Short	Description
`--output`	`-o`	Output HTML file path
`--index`	`-i`	Memory index path
`--open` / `--no-open`		Open in browser after generating (default: open)

# Generate and open in browser
rai memory viz

# Generate to specific path
rai memory viz --output graph.html

# Generate without opening
rai memory viz --no-open

`rai memory generate`

Discovery

Commands for scanning, analyzing, and tracking your codebase architecture.

`rai discover scan`

Scan a directory and extract code symbols (classes, functions, methods, interfaces, module docstrings). Supports Python, TypeScript, and JavaScript.

Flag	Short	Description
`--language`	`-l`	Language: `python`, `typescript`, `javascript` (auto-detect if not set)
`--output`	`-o`	Output format: `human`, `json`, or `summary`
`--pattern`	`-p`	Glob pattern for files
`--exclude`	`-e`	Patterns to exclude (can be repeated)

# Scan current directory
rai discover scan

# Scan Python files only
rai discover scan src/ --language python

# JSON output for piping to analyze
rai discover scan src/ -l python -o json

# Exclude tests
rai discover scan . --exclude "**/test_*" --exclude "**/__tests__/**"

`rai discover analyze`

Analyze scan results with confidence scoring and module grouping. Takes raw scan output and produces an analysis with auto-categorization, hierarchical folding, and module grouping. All analysis is deterministic — no AI inference required.

Flag	Short	Description
`--input`	`-i`	Path to scan result JSON (reads stdin if not provided)
`--output`	`-o`	Output format: `human`, `json`, or `summary`
`--category-map`	`-c`	YAML file with custom path-to-category mappings

# Analyze from file
rai discover analyze --input scan-result.json

# Pipe from scan
rai discover scan src/ -l python -o json | rai discover analyze

# Summary only
rai discover analyze --input scan-result.json --output summary

`rai discover build`

Build unified graph with discovered components. Reads validated components from JSON and integrates them into the unified context graph, making them queryable via rai memory context.

Flag	Short	Description
`--input`	`-i`	Path to validated components JSON
`--project-root`	`-r`	Project root directory (default: `.`)
`--output`	`-o`	Output format: `human`, `json`, or `summary`

# Build with default input file
rai discover build

# Build with custom input
rai discover build --input my-components.json

`rai discover drift`

Check for architectural drift against baseline components. Compares scanned code against the validated component baseline to identify potential drift (files in wrong locations, naming convention violations, missing documentation).

Exit codes: 0 = no drift, 1 = drift warnings found.

Flag	Short	Description
`--project-root`	`-r`	Project root directory (default: `.`)
`--output`	`-o`	Output format: `human`, `json`, or `summary`

# Check entire project
rai discover drift

# Check specific directory
rai discover drift src/new_module/

# Output as JSON
rai discover drift --output json

Skills

`rai skill list`

List all skills in the skill directory. Shows skills grouped by lifecycle with version and description.

Flag	Short	Description
`--format`	`-f`	Output format: `human` or `json`

rai skill list

`rai skill validate`

Validate skill structure against the RaiSE schema. Checks frontmatter, required fields, sections, and naming conventions.

Flag	Short	Description
`--format`	`-f`	Output format: `human` or `json`

# Validate all skills
rai skill validate

# Validate specific skill
rai skill validate .claude/skills/story-start/SKILL.md

`rai skill scaffold`

Create a new skill from template. Generates a SKILL.md file with proper structure in .claude/skills/<name>/.

Flag	Short	Description
`--lifecycle`	`-l`	Lifecycle: `session`, `epic`, `story`, `discovery`, `utility`, `meta`
`--after`		Skill that should come before this one
`--before`		Skill that should come after this one
`--format`	`-f`	Output format: `human` or `json`

# Create a new story skill
rai skill scaffold story-validate

# With lifecycle and ordering
rai skill scaffold story-validate --lifecycle story --after story-implement --before story-close

`rai skill check-name`

Check a proposed skill name against naming conventions. Validates the {domain}-{action} pattern, checks for conflicts with existing skills or CLI commands, and verifies the lifecycle domain.

Flag	Short	Description
`--format`	`-f`	Output format: `human` or `json`

rai skill check-name story-validate

Profile

`rai profile show`

Display the developer profile in YAML format. Shows the contents of ~/.rai/developer.yaml. If no profile exists, guides you to create one.

rai profile show

Base

`rai base show`

Display base Rai package information. Shows the bundled base version, contents (identity, patterns, methodology), and whether it has been installed in the current project.

rai base show

Release

`rai release list`

List releases from the memory graph. Shows all release nodes with their status, target date, and associated epics.

Flag	Short	Description
`--project`	`-p`	Project root path (default: `.`)

rai release list