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

[github-actions]

CLI Consistency Report

Date: 2026-03-04
APM Version: 0.7.4
Commands Inspected: 28 (13 top-level + subcommands across deps, mcp, config, runtime)

Summary

Severity	Count
High	2
Medium	6
Low	3

---

High Severity

apm mcp list undocumented in CLI reference

• Command: apm mcp list
• Problem: The command apm mcp list exists and works in the CLI (shown in apm mcp --help) but has no documentation section in docs/cli-reference.md. The mcp docs jump from showing apm mcp group to only documenting search and show.
• Evidence:

  $ apm mcp --help
  Commands:
    list    List all available MCP servers
    search  Search MCP servers in registry
    show    Show detailed MCP server information
  ```
  `docs/cli-reference.md` only contains sections for `apm mcp search` and `apm mcp show` — `apm mcp list` has no section.
  

• Suggested Fix: Add a ### \apm mcp list`section todocs/cli-reference.md documenting its usage, options (--limit INTEGER`), and examples.

---

apm prune undocumented in CLI reference and README

• Command: apm prune
• Problem: apm prune is a real, functional command visible in apm --help, but it has no documentation in docs/cli-reference.md or README.md.
• Evidence:

  $ apm --help
  Commands:
    ...
    prune      Remove APM packages not listed in apm.yml
    ...
  
  $ apm prune --help
  Usage: apm prune [OPTIONS]
    Remove APM packages not listed in apm.yml
  Options:
    --dry-run  Show what would be removed without removing
    --help     Show this message and exit.
  

  Neither docs/cli-reference.md nor README.md contain any mention of apm prune.
• Suggested Fix: Add a ### \apm prune`section todocs/cli-reference.mdand reference it in the command table inREADME.md`.

---

Medium Severity

apm uninstall --verbose documented but does not exist

• Command: apm uninstall
• Problem: docs/cli-reference.md lists --verbose as a supported flag for apm uninstall, but the flag does not exist in the CLI.
• Evidence:

  # From docs/cli-reference.md line 262:
  - `--verbose` - Show detailed removal information
  
  # Actual CLI:
  $ apm uninstall --verbose
  Error: No such option: --verbose
  
  $ apm uninstall --help
  Options:
    --dry-run  Show what would be removed without removing
    --help     Show this message and exit.
  

• Suggested Fix: Either implement --verbose for apm uninstall (consistent with apm install) or remove it from the documentation.

---

apm runtime docs omit copilot as a supported runtime

• Command: apm runtime setup, apm runtime remove
• Problem: docs/cli-reference.md states "Currently supports two runtimes: codex, and llm" and only lists those two in the Supported Runtimes section. However, the CLI also accepts copilot as a valid runtime.
• Evidence:

  # docs/cli-reference.md line 849:
  "Currently supports two runtimes: `codex`, and `llm`."
  
  # Actual CLI:
  $ apm runtime setup --help
  Usage: apm runtime setup [OPTIONS] {copilot|codex|llm}
  
  $ apm runtime remove --help
  Usage: apm runtime remove [OPTIONS] {copilot|codex|llm}
  

• Suggested Fix: Update the docs to list all three supported runtimes: copilot, codex, and llm. Add a description for copilot in the Supported Runtimes table.

---

apm compile docs missing several flags

• Command: apm compile
• Problem: docs/cli-reference.md omits four flags that exist in the actual CLI: --verbose/-v, --local-only, --clean, and --single-agents.
• Evidence:

  $ apm compile --help
  Options:
    ...
    --single-agents   📄 Force single-file compilation (legacy mode)
    -v, --verbose     🔍 Show detailed source attribution and optimizer analysis
    --local-only      🏠 Ignore dependencies, compile only local primitives
    --clean           🧹 Remove orphaned AGENTS.md files that are no longer generated
    ...
  

  None of these four flags appear in the Options section of docs/cli-reference.md.
• Suggested Fix: Add all four missing flags to the Options list in the apm compile section of docs/cli-reference.md.

---

apm runtime setup docs missing --version option and has wrong argument description

• Command: apm runtime setup
• Problem: The docs for apm runtime setup are missing the --version TEXT option, and the argument description says "Runtime to remove" (wrong verb) instead of "Runtime to set up/install".
• Evidence:

  # Actual CLI:
  $ apm runtime setup --help
  Options:
    --version TEXT  Specific version to install
    --vanilla       ...
  
  # docs/cli-reference.md line 867:
  - `RUNTIME_NAME` - Runtime to remove: `codex`, or `llm`
  # (wrong verb: should be "to install" or "to set up", not "to remove")
  # Also: --version TEXT option is not listed in the docs Options section
  

• Suggested Fix: Add --version TEXT to the Options list and fix "Runtime to remove" → "Runtime to install".

---

Duplicate apm runtime status section with conflicting information

• Command: apm runtime status
• Problem: docs/cli-reference.md contains two #### \apm runtime status`sections. The first (line 919) correctly documents it with no arguments. The second (line 932) incorrectly claims it accepts aRUNTIME_NAME` argument — this does not work in practice.
• Evidence:

  # First section (line 919) — correct:
  #### `apm runtime status` - 📊 Show runtime status
  "Display which runtime APM will use for execution and runtime preference order."
  
  # Second section (line 932) — incorrect:
  #### `apm runtime status` - Show runtime status
  "Display detailed status for a specific runtime."
  apm runtime status RUNTIME_NAME
  
  # Actual CLI:
  $ apm runtime status someruntime
  Error: Got unexpected extra argument (someruntime)
  

• Suggested Fix: Remove the duplicate second apm runtime status section entirely.

---

Low Severity

apm compile --target docs list wrong valid values

• Command: apm compile --target
• Problem: Docs say -t, --target TEXT with values vscode, claude, or all. The CLI uses [vscode|agents|claude|all] — agents is also a valid alias for vscode but is absent from the documentation.
• Evidence:

  # docs/cli-reference.md line 619:
  - `-t, --target TEXT` - Target agent format: `vscode`, `claude`, or `all`.
  
  # Actual CLI:
  -t, --target [vscode|agents|claude|all]
  

• Suggested Fix: Update docs to show -t, --target [vscode|agents|claude|all] and document the agents value.

---

Missing emojis in some CLI command descriptions (style inconsistency)

• Commands: apm uninstall, apm run, apm list, apm preview, apm prune
• Problem: Several commands lack the emoji prefix in their CLI description that other commands use (e.g., apm install 📦, apm init 🚀, apm compile 🚀). This creates visual inconsistency in apm --help output.
• Evidence:

  $ apm --help
  Commands:
    compile    🚀 Compile APM context into distributed AGENTS.md files
    install    📦 Install APM and MCP dependencies ...
    init       🚀 Initialize a new APM project
    list       List available scripts in the current project         ← no emoji
    preview    Preview a script's compiled prompt files              ← no emoji
    prune      Remove APM packages not listed in apm.yml             ← no emoji
    run        Run a script with parameters                          ← no emoji
    uninstall  Remove APM packages from apm.yml and apm_modules      ← no emoji
    update     ⬆️  Update APM to the latest version
  

• Suggested Fix: Add appropriate emojis to the help text of uninstall, run, list, preview, and prune for consistency.

---

apm deps update has no options but sibling commands lack feature parity with apm install --update

• Command: apm deps update
• Problem: Minor documentation note in docs/cli-reference.md itself acknowledges incomplete implementation: "Package update functionality requires dependency downloading infrastructure from enhanced install command." This note is internal implementation detail that shouldn't be user-facing.
• Evidence:

  # docs/cli-reference.md (end of apm deps update section):
  **Note:** Package update functionality requires dependency downloading infrastructure
  from enhanced install command.
  

• Suggested Fix: Remove the internal implementation note from user-facing documentation. Either complete the implementation or document the current limitation in plain user-friendly language.

---

Clean Areas

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

• apm init — correct help, options match docs
• apm install — all flags documented and accurate
• apm deps list, apm deps tree, apm deps info, apm deps clean — all correct
• apm mcp search, apm mcp show — accurate docs and matching CLI
• apm config get, apm config set — matching CLI and docs
• apm runtime list, apm runtime remove — correct
• apm run, apm preview, apm list — CLI works correctly
• Error handling — all tested commands (--nonexistent-flag, missing required args) return clean error messages with no stack traces
• --help / -h works on every command and subcommand tested

Generated by CLI Consistency Checker · ◷

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