CLI Reference

Command Structure

awa organizes commands into two groups:

Workflow Commands — init, check, trace, and spec management (renumber, recode, merge, codes)
Template Commands — template subcommands (generate, diff, features, test)

Global Options

Option	Description
`-v, --version`	Display version number
`-h, --help`	Display help information

Update Check

awa periodically checks the npm registry for newer versions and prints a warning after command output when an update is available. The check runs asynchronously and does not slow down CLI startup.

See Configuration — [update-check] for the full reference.

Workflow Commands

`awa init [output]` / `awa template generate [output]`

Generate configuration files from templates. init is a top-level convenience command equivalent to awa template generate — identical behaviour, both equally valid.

awa init .                                         # current directory, default template
awa init ./my-project                              # specific output directory
awa init . --features copilot claude               # with feature flags
awa init . --preset full              # with a preset
awa init . --dry-run                  # preview without writing
awa init . --delete                   # apply deletions from template
awa init . --json                     # JSON output (implies --dry-run)
awa init . --summary                  # compact one-line summary
awa init . --overlay ./my-overrides   # layer custom files over base template
awa init --all-targets                # process all named targets from config
awa init --target claude              # process a specific named target

Option	Description
`[output]`	Output directory (positional, optional if set in config)
`-t, --template <source>`	Template source — local path or Git repo
`-f, --features <flag...>`	Feature flags (repeatable)
`--preset <name...>`	Preset names to enable (repeatable)
`--remove-features <flag...>`	Feature flags to remove (repeatable)
`--force`	Overwrite existing files without prompting
`--dry-run`	Preview changes without modifying files
`--delete`	Enable deletion of files listed for deletion in the template
`-c, --config <path>`	Path to configuration file
`--refresh`	Force re-fetch of cached Git templates
`--all-targets`	Process all named targets from config
`--target <name>`	Process a specific named target from config
`--overlay <path...>`	Overlay directory paths applied over base template (repeatable)
`--json`	Output results as JSON to stdout (implies `--dry-run`)
`--summary`	Output compact one-line counts summary

If --config is omitted, awa discovers .awa.toml by searching upward from the current directory to the repo root (.git); relative paths in config are resolved from the config file location.

`awa check`

Validate spec files against schemas and check traceability between code markers and specs.

Exit code 0 = all checks pass, 1 = errors found, 2 = internal error.

awa check                              # check with defaults
awa check --json                       # JSON output for CI
awa check --summary                    # compact one-line summary
awa check --code-ignore "test/**"      # ignore specific code paths
awa check --config ./custom.toml       # custom config file
awa check --allow-warnings             # warnings don't fail
awa check --spec-only                  # skip code-to-spec traceability
awa check --no-fix                     # skip auto-fix of traceability matrices
awa check --deprecated                 # surface warnings for deprecated ID references

Option	Description
`-c, --config <path>`	Path to configuration file
`--spec-ignore <pattern...>`	Glob patterns to exclude from spec file scanning
`--code-ignore <pattern...>`	Glob patterns to exclude from code file scanning
`--json`	Output results as JSON
`--summary`	Output compact one-line summary
`--format <format>`	Output format: `text` or `json` (hidden; prefer `--json`)
`--allow-warnings`	Allow warnings without failing (default: warnings are treated as errors)
`--spec-only`	Run only spec-level checks (schema and cross-refs); skip code-to-spec traceability
`--no-fix`	Skip auto-regeneration of Requirements Traceability sections and Feature Codes table
`--deprecated`	Surface warnings for code markers and cross-references targeting deprecated IDs

The check command validates:

Auto-Fix

Before running schema checks, awa check automatically regenerates:

Requirements Traceability sections in DESIGN and TASK files
Feature Codes table in ARCHITECTURE.md

This ensures schema line-limit validation sees the current generated content. Use --no-fix to skip this auto-regeneration.

Code-to-Spec Checks

Check	Severity	Description
Orphaned `@awa-impl`	error	Marker references an AC ID not found in any REQ spec
Orphaned `@awa-test`	error	Marker references an AC or property ID not in any spec
Orphaned `@awa-component`	error	Marker references a component name not in any DESIGN spec
Uncovered AC	warning	Acceptance criterion in a REQ spec has no `@awa-test`
Invalid ID format	warning	Marker ID doesn’t match the configured ID pattern

Spec-to-Spec Checks

Check	Severity	Description
Broken IMPLEMENTS	error	DESIGN component references an AC ID not in any REQ spec
Broken VALIDATES	error	DESIGN property references an AC or requirement ID not in any REQ spec
Orphaned spec	warning	Spec file’s feature code isn’t referenced by any marker or cross-reference
Marker trailing text	error	Marker contains trailing text after the ID(s)

Schema Checks

Check	Severity	Description
Missing section	error	Required section heading not found
Wrong level	warning	Section exists but at wrong heading level
Missing content	error	Section missing required content (pattern/list/table/code-block)
Table columns	error	Table columns don’t match expected headers
Prohibited formatting	warning	Prohibited formatting pattern found outside code blocks
Line limit	warning	File exceeds the line limit defined in the rule

By default, warnings are treated as errors (exit code 1). Use --allow-warnings to only fail on errors.

Finding Codes

Code	Severity	Description
`orphaned-marker`	error	`@awa-impl`, `@awa-test`, or `@awa-component` references an ID not in specs
`uncovered-ac`	warning	Acceptance criterion has no corresponding `@awa-test`
`broken-cross-ref`	error	IMPLEMENTS/VALIDATES points to non-existent requirement ID
`invalid-id-format`	warning	Marker ID doesn’t match the configured ID pattern
`marker-trailing-text`	error	Marker contains trailing text after the ID(s)
`orphaned-spec`	warning	Spec file’s feature code not referenced by any marker or cross-ref
`schema-missing-section`	error	Required section heading not found
`schema-wrong-level`	warning	Section exists but at wrong heading level
`schema-missing-content`	error	Section missing required content
`schema-table-columns`	error	Table columns don’t match expected headers
`schema-prohibited`	warning	Prohibited formatting pattern found outside code blocks
`schema-line-limit`	warning	File exceeds the line limit defined in the rule
`deprecated-ref`	warning	Code marker or cross-reference targets a deprecated ID (requires `--deprecated`)
`deprecated-id-conflict`	error	Active spec reuses an ID that is listed in `DEPRECATED.md`

JSON Output Format

When --json (or --format json) is used, output is a JSON object:

{
  "valid": false,
  "errors": 3,
  "warnings": 2,
  "findings": [
    {
      "severity": "error",
      "code": "orphaned-marker",
      "message": "@awa-impl references unknown ID 'FOO-1_AC-1'",
      "filePath": "src/foo.ts",
      "line": 5,
      "id": "FOO-1_AC-1"
    },
    {
      "severity": "warning",
      "code": "uncovered-ac",
      "message": "AC 'BAR-2_AC-1' has no @awa-test",
      "id": "BAR-2_AC-1"
    }
  ]
}

`awa trace [ids...]`

Explore traceability chains and assemble context from specs, code, and tests.

Exit code 0 = chain found, 1 = ID not found / no context, 2 = internal error.

awa trace DIFF-1_AC-1                    # trace a single ID
awa trace DIFF-1 DIFF-2                  # trace multiple IDs
awa trace --all                          # trace all known IDs
awa trace --task .awa/tasks/TASK-DIFF-diff-001.md  # trace IDs from a task file
awa trace --file src/core/differ.ts      # trace IDs from a source file's markers
awa trace DIFF-1 --content               # output actual file sections
awa trace DIFF-1 --content --max-tokens 4000  # cap content output size
awa trace DIFF-1 --list                  # output file paths only
awa trace DIFF-1 --json                  # JSON output
awa trace DIFF-1 --summary               # compact one-line summary
awa trace DIFF-1 --direction forward     # trace forward only
awa trace DIFF-1 --depth 2              # limit traversal depth
awa trace DIFF-1 --scope DIFF            # limit to a feature code
awa trace DIFF-1 --no-code               # exclude source code
awa trace DIFF-1 --no-tests              # exclude test files
awa trace DIFF-1 --content -C 10         # 10 lines of context before and after

Option	Description
`[ids...]`	Traceability ID(s) to trace (positional)
`--all`	Trace all known IDs in the project
`--task <path>`	Resolve IDs from a task file
`--file <path>`	Resolve IDs from a source file’s markers
`--content`	Output actual file sections instead of locations
`--list`	Output file paths only (no content or tree)
`--max-tokens <n>`	Cap content output size (implies `--content`)
`--depth <n>`	Maximum traversal depth
`--scope <code>`	Limit results to a feature code
`--direction <dir>`	Traversal direction: `both` (default), `forward`, `reverse`
`--no-code`	Exclude source code (spec-only context)
`--no-tests`	Exclude test files
`--json`	Output results as JSON
`--summary`	Output compact one-line summary
`-A <n>`	Lines of context after a code marker (`--content` only; default: 20)
`-B <n>`	Lines of context before a code marker (`--content` only; default: 5)
`-C <n>`	Lines of context before and after (`--content` only; overrides `-A` and `-B`)
`-c, --config <path>`	Path to configuration file

`awa spec renumber [code]`

Renumber traceability IDs to match document order, closing gaps in numbering sequences.

Exit code 0 = no changes needed, 1 = changes applied/previewed, 2 = error.

awa spec renumber DIFF                   # renumber a single feature code
awa spec renumber --all                  # renumber all feature codes
awa spec renumber DIFF --dry-run         # preview changes without modifying
awa spec renumber DIFF --json            # JSON output
awa spec renumber DIFF --expand-unambiguous-ids  # expand malformed shorthand
awa renumber DIFF                        # backward-compat alias

Option	Description
`[code]`	Feature code to renumber (e.g. DIFF, TRC)
`--all`	Renumber all feature codes
`--dry-run`	Preview changes without modifying files
`--json`	Output results as JSON
`--expand-unambiguous-ids`	Expand unambiguous malformed ID shorthand before renumbering
`-c, --config <path>`	Path to configuration file

The renumber command:

Scans all REQ and DESIGN spec files for the given feature code (multi-file support)
Builds a globally sequential renumber map that closes gaps (e.g. 1, 3, 5 → 1, 2, 3)
Propagates ID changes across all spec file types (ARCHITECTURE.md, FEAT, EXAMPLE, REQ, DESIGN, API, TASK, PLAN, ALIGN), source code, and tests
Detects and reports malformed IDs

Malformed ID Expansion

When --expand-unambiguous-ids is set, the command expands unambiguous malformed ID shorthand before applying the renumber map:

Pattern	Example	Action
Slash range	`ARC-36_AC-8/9`	Expanded to `ARC-36_AC-8, ARC-36_AC-9`
Dot-dot AC range	`ARC-18_AC-14..16`	Expanded to `ARC-18_AC-14, ARC-18_AC-15, ARC-18_AC-16`

Expansions are reported separately from standard renumber replacements. In --dry-run mode, proposed expansions are shown without being applied.

`awa spec recode <source> <target>`

Recode traceability IDs from one feature code to another. Rewrites all IDs, renames spec files, and updates headings.

Exit code 0 = no changes needed, 1 = changes applied/previewed, 2 = error.

awa spec recode CHK CLI                  # recode CHK → CLI
awa spec recode CHK CLI --dry-run        # preview changes
awa spec recode CHK CLI --renumber       # renumber target after recode
awa spec recode CHK CLI --json           # JSON output

Option	Description
`<source>`	Source feature code to recode from
`<target>`	Target feature code to recode into
`--dry-run`	Preview changes without modifying files
`--json`	Output results as JSON
`--renumber`	Renumber target code after recode
`-c, --config <path>`	Path to configuration file

The recode command:

Builds an offset map across all source REQ and DESIGN files so source IDs don’t collide with existing target IDs
Propagates ID changes across all spec and code files
Renames source spec files to the target code namespace
Detects rename conflicts (use awa spec merge if target files already exist)
Updates the Feature Codes table in ARCHITECTURE.md

`awa spec merge <source> <target>`

Merge one feature code into another — combines recode, content merge, and cleanup in a single command.

Exit code 0 = no changes needed, 1 = changes applied/previewed, 2 = error.

awa spec merge CHK CLI                   # merge CHK into CLI
awa spec merge CHK CLI --dry-run         # preview changes
awa spec merge CHK CLI --renumber        # renumber target after merge
awa spec merge CHK CLI --json            # JSON output

Option	Description
`<source>`	Source feature code to merge from
`<target>`	Target feature code to merge into
`--dry-run`	Preview changes without modifying files
`--json`	Output results as JSON
`--renumber`	Renumber target code after merge
`-c, --config <path>`	Path to configuration file

The merge command pipeline:

Recode — builds an offset map and propagates ID changes (source IDs renumbered past the target’s highest IDs)
Move — renames source spec files into the target code namespace (appends an index suffix on conflict)
Stale-ref check — warns about any leftover source-code references
Post-processing — optionally renumbers the target code and updates the Feature Codes table in ARCHITECTURE.md

When to use merge vs. recode: Use recode when the target code has no existing spec files (pure rename). Use merge when both source and target have spec files that need to be combined.

`awa spec codes`

List all feature codes with requirement counts and scope summaries.

Exit code 0 = success, 2 = internal error.

awa spec codes                           # table output
awa spec codes --json                    # JSON output
awa spec codes --summary                 # compact one-line summary

Option	Description
`--json`	Output results as JSON
`--summary`	Output compact one-line summary
`-c, --config <path>`	Path to configuration file

The codes command scans all spec files to build an inventory of feature codes with their requirement counts and scope boundaries (from ARCHITECTURE.md).

Template Commands

`awa template features`

Discover feature flags available in a template.

Exit code 0 = success, 1 = error.

awa template features                              # discover flags in default template
awa template features --template ./templates/awa   # specific template
awa template features --json                       # JSON output
awa template features --overlay ./custom           # include overlay features
awa template features --summary                    # compact one-line summary

Option	Description
`-t, --template <source>`	Template source — local path or Git repo
`-c, --config <path>`	Path to configuration file
`--refresh`	Force re-fetch of cached Git templates
`--overlay <path...>`	Overlay directory paths applied over base template (repeatable)
`--json`	Output results as JSON
`--summary`	Output compact one-line summary

The features command:

Scans all template files (including partials) for it.features.includes('name') references
Lists each discovered feature flag and the files that reference it
Includes preset definitions from .awa.toml if available

Example JSON output from awa template features --json:

{
  "features": [
    { "name": "copilot", "files": ["CLAUDE.md", "_partials/_header.md"] },
    { "name": "claude", "files": ["CLAUDE.md"] }
  ],
  "presets": {
    "full": ["copilot", "claude", "cursor"]
  },
  "filesScanned": 42
}

`awa template diff [target]`

Compare generated template output against an existing target directory.

Exit code 0 = files match, 1 = differences found.

awa template diff .                                # diff against current directory
awa template diff ./my-project --template ./tpl    # diff specific target and template
awa template diff . --list-unknown                 # include files not in template
awa template diff . --watch                        # watch template and re-diff on change
awa template diff . --overlay ./my-overrides       # diff against merged template view
awa template diff . --json                         # JSON output for CI
awa template diff . --summary                      # compact one-line summary
awa template diff --all-targets                    # diff all named targets from config
awa template diff --target copilot                 # diff a specific named target

Option	Description
`[target]`	Target directory to compare (positional, optional if set in config)
`-t, --template <source>`	Template source — local path or Git repo
`-f, --features <flag...>`	Feature flags (repeatable)
`--preset <name...>`	Preset names to enable (repeatable)
`--remove-features <flag...>`	Feature flags to remove (repeatable)
`-c, --config <path>`	Path to configuration file
`--refresh`	Force re-fetch of cached Git templates
`--list-unknown`	Include files in target not present in templates
`--all-targets`	Process all named targets from config
`--target <name>`	Process a specific named target from config
`-w, --watch`	Watch template directory for changes and re-run diff
`--overlay <path...>`	Overlay directory paths applied over base template (repeatable)
`--json`	Output results as JSON to stdout
`--summary`	Output compact one-line counts summary

`awa template test`

Run template test fixtures to verify expected output.

Exit code 0 = all pass, 1 = failures found, 2 = internal error.

awa template test                                       # test default template
awa template test --template ./templates/awa            # test specific template
awa template test --update-snapshots                    # update stored snapshots
awa template test --refresh                             # re-fetch cached Git templates
awa template test --overlay ./custom                    # test with overlay applied
awa template test --json                                # JSON output for CI
awa template test --summary                             # compact one-line summary

Option	Description
`-t, --template <source>`	Template source — local path or Git repo
`-c, --config <path>`	Path to configuration file
`--refresh`	Force re-fetch of cached Git templates
`--overlay <path...>`	Overlay directory paths applied over base template (repeatable)
`--update-snapshots`	Update stored snapshots with current rendered output
`--json`	Output results as JSON
`--summary`	Output compact one-line summary

The test command:

Discovers fixture files (*.toml) in the template’s _tests/ directory
Renders templates for each fixture with specified features, presets, and remove-features
Verifies expected files exist in the rendered output
Compares rendered output against stored snapshots (if snapshot directories exist)
Reports pass/fail per fixture with failure details

See Template Testing for the full fixture format and CI setup.

Exit Codes

Command	0	1	2
`awa init` / `awa template generate`	Success	—	Internal error
`awa template diff`	All files match	Differences found	Internal error
`awa check`	All checks pass	Errors found	Internal error
`awa template test`	All fixtures pass	Failures found	Internal error
`awa template features`	Success	Error	—
`awa trace`	Chain found	ID not found / no context	Internal error
`awa spec renumber`	No changes needed	Changes applied/previewed	Internal error
`awa spec recode`	No changes needed	Changes applied/previewed	Error / stale refs
`awa spec merge`	No changes needed	Changes applied/previewed	Error / stale refs
`awa spec codes`	Success	—	Internal error

CLI Reference

Command Structure

Global Options

Update Check

Workflow Commands

awa init [output] / awa template generate [output]

awa check

Auto-Fix

Code-to-Spec Checks

Spec-to-Spec Checks

Schema Checks

Finding Codes

JSON Output Format

awa trace [ids...]

awa spec renumber [code]

Malformed ID Expansion

awa spec recode <source> <target>

awa spec merge <source> <target>

awa spec codes

Template Commands

awa template features

awa template diff [target]

awa template test

Further Reading

Exit Codes

`awa init [output]` / `awa template generate [output]`

`awa check`

`awa trace [ids...]`

`awa spec renumber [code]`

`awa spec recode <source> <target>`

`awa spec merge <source> <target>`

`awa spec codes`

`awa template features`

`awa template diff [target]`

`awa template test`