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

[github-actions]

CLI Consistency Report

Date: 2026-03-10
APM Version: 0.7.6 (872108a)
Commands Inspected: 30 (plus 2 tested non-existent: apm mcp install, apm config list)

Summary

Severity	Count
High	0
Medium	3
Low	4

---

Medium Severity

Incorrect argument order in apm install usage docs

• Command: apm install
• Problem: The usage line in docs/cli-reference.md shows arguments before options, which is the reverse of what the CLI actually displays and the Click convention.
• Evidence:
  • Docs (line 112): apm install [PACKAGES...] [OPTIONS]
  • Actual CLI: Usage: apm install [OPTIONS] [PACKAGES]...
• Suggested Fix: Update docs line 112 to: apm install [OPTIONS] [PACKAGES...]

---

Missing default value for apm mcp list --limit in docs

• Command: apm mcp list
• Problem: The --limit option for apm mcp list does not document its default (20) in docs/cli-reference.md, while the sibling apm mcp search --limit does document its default (10). This asymmetry is misleading.
• Evidence:
  • apm mcp list docs (line 630): --limit INTEGER - Number of results to show (no default)
  • apm mcp search docs (line 653): --limit INTEGER - Number of results to show (default: 10) ✅
  • Source confirms: apm mcp list default=20, apm mcp search default=10
  • Neither command shows a default in their --help output, while apm install --parallel-downloads does show [default: 4]
• Suggested Fix: Update docs line 630 to: --limit INTEGER - Number of results to show (default: 20). Also consider adding show_default=True to both --limit options in cli.py (lines 4019 and 4287) for consistency with --parallel-downloads.

---

Emojis appearing in CLI runtime output violates project policy

• Commands: apm deps list, apm config
• Problem: Project policy explicitly prohibits emojis in any CLI output, but several commands emit emojis at runtime. This was confirmed by the project owner: "we don't want any emojis in any output."
• Evidence:

  $ apm deps list
  💡 No APM dependencies installed yet
  ```
  ```
  $ apm config
  ⚙️  Current APM Configuration
  

  Source locations: src/apm_cli/commands/deps.py lines 47, 160, 164, 171, 198, 201, 204, 222, 225.
• Suggested Fix: Replace emoji prefixes with text-only equivalents (e.g., INFO:, WARNING:, APM Dependencies) in deps.py runtime output and config command table title.

---

Low Severity

deps update and deps info argument name mismatch (docs vs CLI)

• Commands: apm deps update, apm deps info
• Problem: Documentation uses PACKAGE_NAME as the argument label in both usage lines and argument descriptions, but the CLI help shows PACKAGE.
• Evidence:
  • apm deps update --help: Usage: apm deps update [OPTIONS] [PACKAGE]
  • apm deps info --help: Usage: apm deps info [OPTIONS] PACKAGE
  • Docs (line 599): apm deps update [PACKAGE_NAME]
  • Docs (line 551): apm deps info PACKAGE_NAME
• Suggested Fix: Update docs to use PACKAGE instead of PACKAGE_NAME in both commands' usage lines and argument tables for consistency with the CLI.

---

--verbose short flag -v missing from apm install

• Commands: apm install, apm compile
• Problem: apm compile supports both -v and --verbose, but apm install only supports --verbose (no short flag). Users who learn -v from compile will be surprised it doesn't work with install.
• Evidence:
  • apm install --help: --verbose Show detailed installation information (no -v)
  • apm compile --help: -v, --verbose Show detailed source attribution...
• Suggested Fix: Either add -v as a short alias for --verbose in apm install, or document this intentional difference explicitly.

---

apm runtime status help description mismatch

• Command: apm runtime status
• Problem: CLI help text and docs heading describe the command differently.
• Evidence:
  • CLI help: Check which runtime will be used
  • Docs heading (line 1090): `apm runtime status` - Show runtime status
• Suggested Fix: Align the docs heading to match the CLI: `apm runtime status` - Check which runtime will be used

---

apm install option order differs between docs and CLI help

• Command: apm install
• Problem: The order of --force and --dry-run options in the docs differs from the CLI help output, making it harder to cross-reference.
• Evidence:
  • CLI order: --update, --dry-run, --force, --verbose, --trust-transitive-mcp, --parallel-downloads
  • Docs order (lines 121-127): --update, --force, --dry-run, --parallel-downloads, --verbose, --trust-transitive-mcp
• Suggested Fix: Reorder options in docs to match the CLI output order.

---

Clean Areas

The following commands passed all checks with no issues found:

• apm init — help text, flags, and docs consistent
• apm uninstall — help text, --dry-run flag, and docs consistent
• apm update — help text and --check flag consistent with docs
• apm compile — all options documented correctly; help text consistent
• apm run — consistent with docs
• apm list — consistent with docs
• apm preview — consistent with docs
• apm pack / apm unpack — all options documented correctly
• apm prune — consistent with docs
• apm deps list / apm deps tree / apm deps clean — consistent with docs
• apm mcp list / apm mcp search / apm mcp show — consistent with docs
• apm config set / apm config get — consistent with docs
• apm config (bare, invoke_without_command) — correctly shows configuration
• apm runtime setup / apm runtime list / apm runtime remove / apm runtime status — all exist and are documented
• Exit behavior: all commands return proper error messages (no tracebacks) for invalid flags or missing required arguments

Generated by CLI Consistency Checker · ◷

• expires on Mar 12, 2026, 1:36 PM UTC