[cli-consistency] CLI Consistency Report — 2026-03-11

[github-actions]

CLI Consistency Report

Date: 2026-03-11
APM Version: 0.7.7 (62d03e7)
Commands Inspected: 30
(apm, init, install, uninstall, update, compile, run, list, preview, pack, prune, unpack, deps, deps list, deps tree, deps info, deps clean, deps update, mcp, mcp list, mcp search, mcp show, config, config get, config set, runtime, runtime setup, runtime list, runtime remove, runtime status)

Summary

Severity	Count
High	0
Medium	2
Low	4

---

Medium Severity

apm pack --target option values incomplete in documentation

• Command: apm pack
• Problem: docs/cli-reference.md lists --target as [vscode|claude|all] but the CLI exposes four choices: [copilot|vscode|claude|all]. The copilot option and the aliasing note are missing from the docs.
• Evidence:
  • CLI output: -t, --target [copilot|vscode|claude|all] Filter files by target (default: auto-detect). 'vscode' is an alias for 'copilot'.
  • Docs (line 348): `-t, --target [vscode|claude|all]` - Filter files by target. Auto-detects from `apm.yml` if not specified
• Suggested Fix: Update docs/cli-reference.md line 348 to list [copilot|vscode|claude|all] and add note: 'vscode' is an alias for 'copilot'.

---

apm runtime setup synopsis describes argument incorrectly

• Command: apm runtime setup
• Problem: docs/cli-reference.md shows the synopsis as apm runtime setup RUNTIME_NAME [OPTIONS] (free-form argument, options after), but the CLI constrains the argument to {copilot|codex|llm} and places [OPTIONS] before the argument per Click conventions.
• Evidence:
  • CLI output: Usage: apm runtime setup [OPTIONS] {copilot|codex|llm}
  • Docs (line 1031): apm runtime setup RUNTIME_NAME [OPTIONS]
  • Docs (line 1035): - \RUNTIME_NAME` - Runtime to install: `copilot`, `codex`, or `llm``
• Suggested Fix: Update synopsis on line 1031 to apm runtime setup [OPTIONS] {copilot|codex|llm} and update the argument description to reflect the constrained values. Apply the same correction for apm runtime remove at line 1080.

---

Low Severity

apm unpack --output flag documented with wrong shorthand and type

• Command: apm unpack
• Problem: Docs describe --output TEXT but the CLI exposes it as -o, --output PATH. The -o shorthand is missing from docs and the type is PATH not TEXT.
• Evidence:
  • CLI output: -o, --output PATH Target directory (default: current directory).
  • Docs (line 409): - \--output TEXT` - Target project directory (default: current directory)`
• Suggested Fix: Update docs line 409 to - \-o, --output PATH` - Target project directory (default: current directory)`.

---

apm mcp search --limit docs claim a default value not shown in CLI help

• Command: apm mcp search
• Problem: docs/cli-reference.md says --limit has "default: 10", but the CLI help text does not show any default, which creates a discrepancy.
• Evidence:
  • CLI output: --limit INTEGER Number of results to show (no default shown)
  • Docs (line 653): - \--limit INTEGER` - Number of results to show (default: 10)`
• Suggested Fix: Either add [default: 10] to the Click option definition so it appears in the CLI help, or remove the claimed default from the docs if there is none.

---

--parallel-downloads type abbreviation inconsistency between CLI and docs

• Command: apm install
• Problem: Docs write the type as INT (abbreviated) while the CLI shows INTEGER (full Click type name).
• Evidence:
  • CLI output: --parallel-downloads INTEGER Max concurrent package downloads (0 to disable parallelism) [default: 4]
  • Docs (line 125): - \--parallel-downloads INT` - Max concurrent package downloads (default: 4, 0 to disable)`
• Suggested Fix: Update docs line 125 to use INTEGER to match CLI output exactly.

---

apm config runtime output contains emoji contrary to project policy

• Command: apm config (default invocation, no subcommand)
• Problem: Running apm config without a subcommand outputs a table header prefixed with ⚙️. The confirmed project policy (owner-confirmed) is "we don't want any emojis in any output."
• Evidence:
  • Runtime output: ⚙️ Current APM Configuration
• Suggested Fix: Remove the ⚙️ emoji from the apm config table title / header in src/apm_cli/cli.py (config command output path), consistent with the no-emoji policy applied to the rest of the CLI.

---

Clean Areas

The following commands and areas passed all checks:

• apm --help, apm --version — correct and consistent
• apm init, apm install, apm uninstall, apm update, apm compile, apm run — help text accurate, options match docs
• apm list, apm preview, apm pack (except target values), apm prune, apm unpack (except shorthand)
• apm deps group (list, tree, info, clean, update) — all consistent with docs
• apm mcp group (list, search, show) — all consistent with docs except limit default
• apm config group (get, set) — help text and docs aligned; bare apm config behavior matches docs
• apm runtime group (list, remove, status) — consistent with docs
• Error handling — all tested commands produce clean Error: ... messages with usage hints (no tracebacks)
• --help / -h — works on every command and subcommand tested
• --dry-run — consistently named across all commands that support it

Generated by CLI Consistency Checker · ◷

• expires on Mar 13, 2026, 1:32 PM UTC