CLI Reference

Commands and options for the usm CLI.

Quick Reference

Command	Description
docs	usm docs serve and usm docs build — serves generated docs locally via VitePress
enrich	The usm enrich command fills in TODO: describe placeholders in .usm files using
feedback	The usm feedback command configures the agent feedback policy in system.usm — in
generate	The usm generate command reads all .usm files and produces markdown, OpenAPI, Me
import	Structurizr bridge — import a Structurizr workspace JSON into .usm system and se
init	The usm init command analyzes the repo and generates a starter usmconfig.json.
query	Predicate query language over .usm data — a tiny expression grammar (selectors,
scaffold	The usm scaffold command creates a new .usm file with a template for system, ser
scaffold-project	The usm scaffold-project command generates a starter .usm/ directory for single-
scan	The usm scan command reads usmconfig.json, scans the codebase, and generates .us
upgrade	usm upgrade — detect stale USM projects and guide users through adopting new opt
validate	The usm validate command checks .usm files against the v1 JSON Schema and report

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

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|anthropic|ollama)	from usmconfig.json
--url <url>	Override LLM API URL	from usmconfig.json

feedback

The usm feedback command configures the agent feedback policy in system.usm — interactive setup or non-interactive flags for human-gate, direct-to-feedback, or direct-to-github modes.

Prerequisites:

• An existing .usm/system.usm (create with 'usm init-file' or 'usm scan')

Usage

# Interactive setup — prompts for GitHub auth and policy choice (TTY only)
usm feedback

# Non-interactive — agents write structured .usm/feedback entries directly
usm feedback --policy direct-to-feedback --github-auth

# Non-interactive — agents ask the human before filing (the default)
usm feedback --policy human-gate

# Non-interactive — agents file GitHub issues via gh
usm feedback --policy direct-to-github --github-auth --tracker https://github.com/org/repo/issues

Options

Flag	Description	Default
-r, --root <root>	Repo root directory	.
-s, --system <path>	Path to system.usm (default <root>/.usm/system.usm)	—
-p, --policy <policy>	Policy: human-gate | direct-to-feedback | direct-to-github (skips interactive prompts)	—
-g, --github-auth	Declare that the dev agent has GitHub (gh CLI) auth	false
--no-github-auth	Declare that the dev agent lacks GitHub auth	false
-t, --tracker <url>	Override the issue tracker URL (default identity.repository/issues)	—

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

import

Structurizr bridge — import a Structurizr workspace JSON into .usm system and service specs via usm import, and export a Structurizr DSL workspace from .usm via a new generate target (usm generate --only structurizr). USM as the hub: one model, many notations.

Prerequisites:

• A Structurizr workspace JSON export

Usage

# Import a Structurizr workspace into .usm specs
usm import workspace.json

# List planned writes without writing
usm import workspace.json --dry-run

# Set id prefix and domain, overwrite existing
usm import workspace.json --id acme --domain acme.com --force

Options

Flag	Description	Default
<file>	Path to the export file (e.g. structurizr-workspace.json)	required
-f, --format <format>	Import format	structurizr-json
-r, --root <root>	Repo root directory	.
--id <prefix>	$id org prefix	slugified system name
--domain <domain>	identity.domain for the system file	example.com
--force	Overwrite existing .usm files	false
--dry-run	List planned writes without writing	false

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

query

Predicate query language over .usm data — a tiny expression grammar (selectors, comparisons, and/or/not, has, contains) evaluated against parsed .usm files, exposed as usm query CLI and usm_query MCP tool. Turns grep-and-guess into typed impact analysis.

Prerequisites:

• A .usm/ directory with specs

Usage

# List planned features
usm query "features where status = planned"

# Drift check - features with no contracts
usm query "features where contracts = 0"

# Find specs mentioning auth (case-insensitive)
usm query "all where summary ~ auth"

# Full parsed objects as JSON
usm query "services where has decisions" --json

# Cap results
usm query "features where status = built and contracts > 2" --limit 5

Options

Flag	Description	Default
<expr>	Query: <selector> [where <predicate>]	required
-r, --root <root>	Repo root directory	.
--json	Output full parsed objects as JSON	false
--limit <n>	Cap number of results	100

scaffold

The usm scaffold command creates a new .usm file with a template for system, service, or feature types.

Usage

# Scaffold a system .usm file
usm scaffold .usm/system.usm

# Scaffold a service .usm file
usm scaffold .usm/services/api.usm --type service

# Scaffold a feature .usm file
usm scaffold .usm/features/auth/login.usm --type feature

Options

Flag	Description	Default
-t, --type <type>	File type: system, service, or feature	system

scaffold-project

The usm scaffold-project command generates a starter .usm/ directory for single-app, monorepo-sub, or monorepo-root projects.

Usage

# Scaffold a single-app .usm/ structure
usm scaffold-project

# Scaffold a monorepo root .usm/ structure
usm scaffold-project --type monorepo-root

# Scaffold a sub-app in a monorepo
usm scaffold-project --type monorepo-sub --name my-app

Options

Flag	Description	Default
-t, --type <type>	Project type: single-app, monorepo-sub, or monorepo-root	single-app
-n, --name <name>	App or project name	my-app
-o, --output <path>	Output directory	.
--org <org>	Organization ID prefix	my-org

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

upgrade

usm upgrade — detect stale USM projects and guide users through adopting new optional capabilities (like the feedback policy) via a self-describing capability registry. Compares the installed USM version against system.usm.version, reports missing/recommended capabilities, offers interactive or default setup, and bumps the project version on completion.

Prerequisites:

• An existing .usm/system.usm (create with 'usm init-file' or 'usm scan')

Usage

# Detect stale capabilities and guide interactive setup (TTY)
usm upgrade

# Apply all recommended missing capabilities with defaults (non-interactive, CI-safe)
usm upgrade --apply

# Report only; exit non-zero if the project is stale (for CI)
usm upgrade --check

# Target a single capability by id
usm upgrade --capability feedback

Options

Flag	Description	Default
-r, --root <root>	Repo root directory	.
-s, --system <path>	Path to system.usm (default: <root>/.usm/system.usm)	—
--apply	Apply all recommended missing capabilities with defaults, no prompts	false
--check	Report only; exit non-zero if stale (CI mode)	false
-c, --capability <id>	Target a single capability (e.g. feedback)	—

validate

The usm validate command checks .usm files against the v1 JSON Schema and reports errors.

Prerequisites:

• .usm files must exist

Usage

# Validate all .usm files in the .usm/ directory
usm validate .usm

# Validate a single file
usm validate .usm/system.usm

# Validate from current directory (scans all .usm dirs)
usm validate .

Next steps

• Schema Reference — understand every .usm field
• MCP Tools — agent tools for the spec-first workflow
• Getting Started — first-run walkthrough
• Configuration Reference — usmconfig.json fields