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

[github-actions]

CLI Consistency Report

Date: 2026-03-06
APM Version: 0.7.4 (251fa5e)
Commands Inspected: 28 (including all subcommands)

Summary

Severity	Count
High	0
Medium	3
Low	5

---

Medium Severity

apm uninstall accepts multiple packages but docs show singular PACKAGE

• Command: apm uninstall
• Problem: The CLI accepts PACKAGES... (variadic, one or more), but the documentation shows only a singular argument PACKAGE. The argument order also differs: CLI is [OPTIONS] PACKAGES... but docs show PACKAGE [OPTIONS].
• Evidence:
  • CLI: Usage: apm uninstall [OPTIONS] PACKAGES...
  • Docs (cli-reference.md): apm uninstall PACKAGE [OPTIONS] and "PACKAGE - Package to uninstall."
• Suggested Fix: Update cli-reference.md to use PACKAGES... (plural) in the usage line, and update the argument description to reflect that multiple packages can be uninstalled in a single call.

---

apm compile --output description mismatch between CLI and docs

• Command: apm compile --output
• Problem: The CLI and docs describe the --output flag differently. The docs claim a default of AGENTS.md, which the CLI does not confirm. The CLI notes it is limited to single-file mode, which the docs omit.
• Evidence:
  • CLI: -o, --output TEXT Output file path (for single-file mode)
  • Docs: - \-o, --output TEXT` - Output file path (default: AGENTS.md)`
• Suggested Fix: Align the docs to match the CLI: "Output file path (for single-file mode)". Remove the undocumented default claim or validate it in the CLI help text.

---

apm compile --dry-run description meaningfully differs between CLI and docs

• Command: apm compile --dry-run
• Problem: The CLI and docs use different phrasing that conveys different semantics. CLI explicitly says "shows placement decisions", which is not in the docs. Docs say "Generate content without writing file" while CLI says "Preview compilation without writing files".
• Evidence:
  • CLI: --dry-run 🔍 Preview compilation without writing files (shows placement decisions)
  • Docs: - \--dry-run` - Generate content without writing file`
• Suggested Fix: Update docs to: "Preview compilation without writing files (shows placement decisions)".

---

Low Severity

Emoji inconsistency in top-level apm --help command list

• Command: apm --help
• Problem: Only 4 of 13 top-level commands have emojis in their description in apm --help: compile (🚀), init (🚀), install (📦), update (⬆️). The other 9 (config, deps, list, mcp, preview, prune, run, runtime, uninstall) have no emoji. This is visually inconsistent.
• Evidence:

  compile    🚀 Compile APM context into distributed AGENTS.md files
  config     Configure APM CLI
  deps       Manage APM package dependencies
  list       List available scripts in the current project
  mcp        Manage MCP servers
  preview    Preview a script's compiled prompt files
  prune      Remove APM packages not listed in apm.yml
  run        Run a script with parameters
  runtime    Manage Coding Agent CLI runtimes
  uninstall  Remove APM packages from apm.yml and apm_modules
  

• Suggested Fix: Add emojis to the remaining command descriptions for visual consistency (e.g., list → 📋, preview → 👀, prune → 🧹, run → 🚀, config → ⚙️, deps → 🔗, mcp → 🔌, runtime → 🤖, uninstall → 🗑️).

---

apm config set / apm config get missing emojis and terse descriptions

• Command: apm config set, apm config get
• Problem: These subcommands have no emoji prefix and are unusually terse compared to analogous subcommands (e.g., apm deps list → 📋 List installed APM dependencies, apm deps info → ℹ️ Show detailed package information).
• Evidence:
  • apm config set --help: Set configuration value
  • apm config get --help: Get configuration value
  • Compare: apm deps list --help: 📋 List installed APM dependencies
• Suggested Fix: Update descriptions to ⚙️ Set a configuration value and ⚙️ Get a configuration value for consistency.

---

apm compile --validate uses "primitives" in CLI vs "context" in docs

• Command: apm compile --validate
• Problem: The CLI and docs use different terminology for the same concept.
• Evidence:
  • CLI: --validate Validate primitives without compiling
  • Docs: - \--validate` - Validate context without compiling`
• Suggested Fix: Align to one term. "primitives" is more precise in the APM domain and matches usage elsewhere in the codebase, so update docs to use "primitives".

---

apm init --yes drops "interactive" in CLI vs docs description

• Command: apm init --yes
• Problem: Minor phrasing difference — the CLI omits the word "interactive" present in the docs.
• Evidence:
  • CLI: -y, --yes Skip prompts and use auto-detected defaults
  • Docs: - \-y, --yes` - Skip interactive prompts and use auto-detected defaults`
• Suggested Fix: Update CLI help text to: Skip interactive prompts and use auto-detected defaults.

---

Clean Areas

The following commands and areas passed all checks — no inconsistencies or missing documentation found:

• apm install — all flags (--runtime, --exclude, --only, --update, --dry-run, --force, --verbose, --trust-transitive-mcp, --parallel-downloads) match docs exactly
• apm deps list, apm deps tree, apm deps info, apm deps clean, apm deps update — all match docs
• apm mcp list, apm mcp search, apm mcp show — all match docs (no mcp install in docs or CLI; consistent)
• apm config (default display), apm config set, apm config get — all exist as documented (no config list in docs or CLI; consistent)
• apm runtime setup, apm runtime list, apm runtime remove, apm runtime status — all match docs
• apm prune, apm update — match docs
• apm run, apm preview, apm list — match docs
• Error handling — all tested invalid-argument scenarios (--nonexistent-flag, missing required args) produce clean Error: messages, no stack traces
• Exit codes — correct non-zero exit on invalid input throughout

Generated by CLI Consistency Checker · ◷

• expires on Mar 8, 2026, 1:29 PM UTC