CLI Reference

Commands and options for the usm CLI.

Quick Reference

Command	Description
cli-docs	usm docs serve and usm docs build — serves generated docs locally via VitePress
cli-enrich	The usm enrich command fills in TODO: describe placeholders in .usm files using
cli-generate	The usm generate command reads all .usm files and produces markdown, OpenAPI, Me
cli-init	The usm init command analyzes the repo and generates a starter usmconfig.json.
cli-scan	The usm scan command reads usmconfig.json, scans the codebase, and generates .us

cli-docs

usm docs serve and usm docs build — serves generated docs locally via VitePress dev server with live reload for the spec-first review workflow, and builds a static site for Cloudflare Pages deployment. Unifies all generated docs into a single docs/ directory with auto-generated sidebar navigation.

Prerequisites:

• Run 'usm generate' first to produce docs
• VitePress installed (pnpm add -D vitepress)

Usage

# Start VitePress dev server with live reload
usm docs serve

# Serve filtered help docs (public-facing)
usm docs serve --audience help

# Build static site for deployment
usm docs build

# Build static help docs site
usm docs build --audience help

Options

Flag	Description	Default
--port <port>	Dev server port	5173
--audience <audience>	Audience: developer (full) or help (public, filtered)	developer

cli-enrich

The usm enrich command fills in TODO: describe placeholders in .usm files using an LLM (LiteLLM, OpenAI, Anthropic, or Ollama).

Prerequisites:

• .usm files with TODO: describe placeholders
• LLM provider configured in usmconfig.json or via flags

Usage

# Enrich all .usm files with TODO placeholders
usm enrich

# Enrich a single file
usm enrich --file .usm/features/auth/login.usm

# Show what would change without calling LLM or writing
usm enrich --dry-run

# Override the LLM model
usm enrich --model anthropic/claude-sonnet-4-5

Options

Flag	Description	Default
--root <root>	Monorepo root directory	current directory
--file <file>	Single .usm file to enrich	all files with TODOs
--dry-run	Show changes without writing or calling LLM	false
--fields <fields>	Comma-separated fields to enrich	summary,intent,decisions,flows,contracts,tests,status
--model <model>	Override LLM model	from usmconfig.json
--provider <provider>	Override provider (litellm	openai
--url <url>	Override LLM API URL	from usmconfig.json

cli-generate

The usm generate command reads all .usm files and produces markdown, OpenAPI, Mermaid, ArchiMate, TOGAF, AGENTS.md, and Vitest test specs.

Prerequisites:

• .usm files must exist (run 'usm init' and 'usm scan' first)

Usage

# Generate all docs from .usm files
usm generate

# Check if generated files are up to date (dry run)
usm generate --check

Options

Flag	Description	Default
--check	Check if outputs are up to date without writing	false
--root <root>	Monorepo root directory	current directory

cli-init

The usm init command analyzes the repo and generates a starter usmconfig.json.

Prerequisites:

• None — this is the first command to run

Usage

# Analyze repo and generate usmconfig.json
usm init

# Overwrite existing usmconfig.json
usm init --force

Options

Flag	Description	Default
--root <root>	Repo root directory	.
--output <path>	Output path for usmconfig.json	usmconfig.json
--force	Overwrite existing usmconfig.json	false

cli-scan

The usm scan command reads usmconfig.json, scans the codebase, and generates .usm files for services, packages, data, and features.

Prerequisites:

• Run 'usm init' first to create usmconfig.json

Usage

# Scan with defaults (smart merge)
usm scan

# Overwrite all existing .usm files
usm scan --force

# Only extract routes, skip service/package detection
usm scan --routes

# Overwrite mechanical fields, preserve human edits
usm scan --merge overwrite

Options

Flag	Description	Default
--root <root>	Repo root directory	.
--config <path>	Path to usmconfig.json	usmconfig.json
--force	Overwrite existing .usm files (bypasses merge)	false
--routes	Only extract routes (skip service/package/data detection)	false
--merge <strategy>	Merge strategy: smart, skip, or overwrite	smart