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

bash

# 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 (strict: fails if taken)	auto — next free port from 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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
Getting Started — first-run walkthrough
Configuration Reference — usmconfig.json fields

CLI Reference ​

Quick Reference ​

docs ​

Usage ​

Options ​

enrich ​

Usage ​

Options ​

feedback ​

Usage ​

Options ​

generate ​

Usage ​

Options ​

import ​

Usage ​

Options ​

init ​

Usage ​

Options ​

query ​

Usage ​

Options ​

scaffold ​

Usage ​

Options ​

scaffold-project ​

Usage ​

Options ​

scan ​

Usage ​

Options ​

upgrade ​

Usage ​

Options ​

validate ​

Usage ​

Next steps ​

CLI Reference

Quick Reference

docs

Usage

Options

enrich

Usage

Options

feedback

Usage

Options

generate

Usage

Options

import

Usage

Options

init

Usage

Options

query

Usage

Options

scaffold

Usage

Options

scaffold-project

Usage

Options

scan

Usage

Options

upgrade

Usage

Options

validate

Usage

Next steps