CLI Consistency Report

Date: 2026-03-13
APM Version: 0.7.8 (09fef91)
Commands Inspected: 30

All findings were verified by running the actual CLI. Every evidence block contains exact output.

Summary

Medium Severity

1. --target values differ between apm pack and apm compile

• Commands: apm pack, apm compile
• Problem: The two commands use opposite conventions for the same target concept. apm pack treats copilot as the canonical value (with vscode as an alias). apm compile treats vscode as the canonical value (with agents as an alias). Users switching between the two commands face inconsistent terminology.
• Evidence:

  # apm pack --help
  -t, --target [copilot|vscode|claude|all]
                                  Filter files by target (default: auto-
                                  detect). 'vscode' is an alias for 'copilot'.
  
  # apm compile --help
  -t, --target [vscode|agents|claude|all]
                                  Target platform: vscode/agents (AGENTS.md),
                                  claude (CLAUDE.md), or all. Auto-detects if
                                  not specified.
  ```
  

• Suggested Fix: Standardize on vscode as the primary value across both commands (matching the VSCode-facing branding). In apm pack, swap so the accepted values are [vscode|copilot|claude|all] with a note that copilot is the alias for vscode.

2. apm deps clean is missing --dry-run and --yes flags

• Command: apm deps clean
• Problem: apm deps clean removes the entire apm_modules/ directory but offers no --dry-run preview and no --yes flag for non-interactive/scripted use. Every other destructive operation in the CLI supports --dry-run (install, uninstall, prune, pack, unpack), and apm runtime remove has --yes. The asymmetry makes deps clean harder to use safely in CI pipelines.
• Evidence:

  # apm deps clean --help
  Usage: apm deps clean [OPTIONS]
  
    Remove all APM dependencies
  
  Options:
    --help  Show this message and exit.
  
  # apm prune --help (for comparison — same category, has --dry-run)
  Options:
    --dry-run  Show what would be removed without removing
    --help     Show this message and exit.
  

• Suggested Fix: Add --dry-run (show what would be removed) and --yes / -y (skip the interactive confirmation prompt) to apm deps clean.

3. apm mcp list --limit does not display a default value; apm mcp search --limit does

• Commands: apm mcp list, apm mcp search
• Problem: Both commands expose a --limit INTEGER option, but only apm mcp search annotates the default value in the help text. Users running apm mcp list cannot tell how many results will be returned without reading the source or running the command.
• Evidence:

  # apm mcp list --help
    --limit INTEGER  Number of results to show
  
  # apm mcp search --help
    --limit INTEGER  Number of results to show  [default: 10]
  

• Suggested Fix: Add a default= parameter to the --limit option in apm mcp list so the help text displays [default: N], matching apm mcp search.

Low Severity

4. --verbose has a short flag (-v) in apm compile but not in apm install

• Commands: apm install, apm compile
• Problem: Both commands expose a --verbose flag but only apm compile adds the -v shorthand. Users who habitually type -v for verbose output in apm install get an error.
• Evidence:

  # apm install --help
    --verbose                     Show detailed installation information
  
  # apm compile --help
    -v, --verbose                   Show detailed source attribution and
                                    optimizer analysis
  

• Suggested Fix: Add -v as a short flag for --verbose in apm install.

5. apm deps update argument name differs between CLI and docs

• Command: apm deps update
• Problem: The CLI declares the optional positional argument as PACKAGE, but the documentation at docs/src/content/docs/reference/cli-commands.md refers to it as PACKAGE_NAME. While functionally harmless, it creates confusion when cross-referencing.
• Evidence:

  # apm deps update --help (CLI)
  Usage: apm deps update [OPTIONS] [PACKAGE]
  
  # docs/src/content/docs/reference/cli-commands.md (line 589)
  - `PACKAGE_NAME` - Optional. Update specific package only
  

• Suggested Fix: Align the documentation to use PACKAGE to match the actual CLI usage string, or update the CLI source to use PACKAGE_NAME for clarity.

6. apm runtime status description diverges between CLI and documentation

• Command: apm runtime status
• Problem: The CLI short description and the documentation description are worded differently, which can cause confusion when comparing help output to docs.
• Evidence:

  # apm runtime status --help (CLI)
    status  Check which runtime will be used
  
  # docs/src/content/docs/reference/cli-commands.md (line 1087-1088)
  #### `apm runtime status` - Show runtime status
  Display which runtime APM will use for execution and runtime preference order.
  

• Suggested Fix: Update the CLI help string to Show active runtime and preference order (or similar), bringing it in line with the documentation's more descriptive phrasing.

Clean Areas

The following commands and areas passed all checks with no issues found:

• apm init — options, description, and docs fully aligned
• apm install — all flags documented accurately; error handling clean
• apm uninstall — consistent with docs; --dry-run present
• apm update — --check flag present and documented correctly
• apm prune — --dry-run present; docs consistent
• apm run / apm preview — --param flag consistent between both commands
• apm list — simple, accurate
• apm unpack — flags match docs; --dry-run and --skip-verify present
• apm deps list / apm deps tree / apm deps info — help text consistent with docs
• apm mcp search / apm mcp show — argument names and flags consistent
• apm config set / apm config get — flags and argument names match docs
• apm runtime setup / apm runtime list / apm runtime remove — consistent with docs
• Error handling: All tested invalid-argument scenarios produced clean Error: messages — no stack traces or unhandled exceptions observed
• --help / -h: Works correctly on every command and subcommand inspected

Generated by CLI Consistency Checker · ◷

• expires on Mar 15, 2026, 1:31 PM UTC