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

[github-actions]

CLI Consistency Report

Date: 2026-03-03
APM Version: 0.7.4
Commands Inspected: 29 (27 exist; 2 tested but do not exist: apm mcp install, apm config list)

Summary

Severity	Count
High	2
Medium	7
Low	3

---

High Severity

apm search and apm show documented but do not exist

• Commands: apm search, apm show
• Problem: The Quick Start Workflow section and Tips section of docs/cli-reference.md reference apm search and apm show as top-level commands, but they do not exist. The correct commands are apm mcp search and apm mcp show.
• Evidence:
  • docs/cli-reference.md line 994–995:

    apm search filesystem
    apm show `@modelcontextprotocol/servers`/src/filesystem
    ```
    

  • docs/cli-reference.md line 1014: Use \apm search` to find available MCP servers before adding to apm.yml`
  • Running apm search filesystem returns: Error: No such command 'search'.
• Suggested Fix: Replace all references to apm search with apm mcp search and apm show with apm mcp show in the Quick Start Workflow and Tips & Best Practices sections of docs/cli-reference.md.

apm uninstall --verbose documented but does not exist

• Command: apm uninstall
• Problem: docs/cli-reference.md documents a --verbose option for apm uninstall, but the CLI does not have this flag.
• Evidence:
  • docs/cli-reference.md line 262: - \--verbose` - Show detailed removal information`
  • apm uninstall --help output:

    Options:
      --dry-run  Show what would be removed without removing
      --help     Show this message and exit.
    

  • No --verbose flag present.
• Suggested Fix: Remove --verbose from the apm uninstall options in docs/cli-reference.md, or implement the flag in the CLI.

---

Medium Severity

apm compile — four flags missing from documentation

• Command: apm compile
• Problem: Four flags present in apm compile --help are not documented in docs/cli-reference.md.
• Evidence (apm compile --help):

  --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 appear in the apm compile options table in docs/cli-reference.md.
• Suggested Fix: Add --single-agents, -v/--verbose, --local-only, and --clean to the options list for apm compile in docs/cli-reference.md.

apm mcp list exists in CLI but is not documented

• Command: apm mcp list
• Problem: apm mcp --help shows a list subcommand but docs/cli-reference.md only documents apm mcp search and apm mcp show.
• Evidence (apm mcp --help):

  Commands:
    list    List all available MCP servers
    search  Search MCP servers in registry
    show    Show detailed MCP server information
  

  The list command has no entry in the documentation.
• Suggested Fix: Add a section for apm mcp list to docs/cli-reference.md.

apm runtime setup argument description is a copy-paste error and is incomplete

• Command: apm runtime setup
• Problem: The argument description in docs says "Runtime to remove: codex, or llm" — copied from apm runtime remove. The description is wrong and omits copilot.
• Evidence:
  • docs/cli-reference.md line 868: - \RUNTIME_NAME` - Runtime to remove: `codex`, or `llm``
  • apm runtime setup --help:

    Usage: apm runtime setup [OPTIONS] {copilot|codex|llm}
    

  • copilot is a valid runtime but is absent from the docs argument description.
• Suggested Fix: Change line 868 to: - \RUNTIME_NAME` - Runtime to install: `copilot`, `codex`, or `llm``

apm runtime setup --version flag not documented

• Command: apm runtime setup
• Problem: The --version TEXT flag (to install a specific version) exists in the CLI but is not listed in the docs.
• Evidence (apm runtime setup --help):

  Options:
    --version TEXT  Specific version to install
    --vanilla       Install runtime without APM configuration ...
    --help          Show this message and exit.
  ```
  `docs/cli-reference.md` only mentions `--vanilla` in this section.
  

• Suggested Fix: Add --version TEXT to the apm runtime setup options in docs/cli-reference.md.

apm compile --target missing agents as valid value

• Command: apm compile
• Problem: The CLI accepts agents as a valid --target value, but docs only list vscode, claude, and all.
• Evidence (apm compile --help):

  -t, --target [vscode|agents|claude|all]
  

  docs/cli-reference.md line 632 (compile options table):

  `-t, --target TEXT` - Target agent format: `vscode`, `claude`, or `all`. Auto-detects if not specified.
  

  The agents value is undocumented.
• Suggested Fix: Add agents to the documented values for --target, and note that agents is an alias for vscode.

apm runtime setup section in docs uses stale "Supported Runtimes" list

• Command: apm runtime
• Problem: The apm runtime section states "Currently supports two runtimes: codex, and llm" — omitting copilot, which both apm runtime setup and apm runtime remove accept.
• Evidence (docs/cli-reference.md):

  **Supported Runtimes:**
  - **`codex`** - OpenAI Codex CLI with GitHub Models support
  - **`llm`** - Simon Willison's LLM library with multiple providers
  

  But apm runtime setup --help shows {copilot|codex|llm}.
• Suggested Fix: Add copilot to the Supported Runtimes list in docs/cli-reference.md.

apm deps update contains a leftover developer note in user-facing docs

• Command: apm deps update
• Problem: The documentation for apm deps update ends with a note that reads like internal developer commentary rather than user documentation.
• Evidence (docs/cli-reference.md):

  **Note:** Package update functionality requires dependency downloading infrastructure from enhanced install command.
  

• Suggested Fix: Remove or replace this note with meaningful user-facing information (e.g., a caveat about what update does or a cross-reference to apm install --update).

---

Low Severity

Inconsistent emoji usage in top-level command help text

• Commands: apm uninstall, apm run, apm list, apm preview, apm prune
• Problem: Several commands lack emojis in their one-line help descriptions shown by apm --help, while others (apm init, apm install, apm compile) have them. This creates visual inconsistency in the help output.
• Evidence (apm --help):

  compile    🚀 Compile APM context into distributed AGENTS.md files
  init       🚀 Initialize a new APM project
  install    📦 Install APM and MCP dependencies ...
  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
  

• Suggested Fix: Add relevant emojis to the help strings for uninstall, run, list, preview, and prune to match the style of the other commands.

apm compile --target described as free-form TEXT in docs, but CLI enforces specific choices

• Command: apm compile
• Problem: The docs table lists --target TEXT (implying any string), while the CLI enforces a strict choice set [vscode|agents|claude|all].
• Evidence:
  • Docs: -t, --target TEXT
  • CLI: -t, --target [vscode|agents|claude|all]
• Suggested Fix: Update docs to show -t, --target [vscode|agents|claude|all] to accurately reflect the accepted values.

apm runtime remove --yes flag not documented

• Command: apm runtime remove
• Problem: apm runtime remove --help shows a --yes flag (to skip confirmation prompt) but docs do not mention it.
• Evidence (apm runtime remove --help):

  Options:
    --yes   Confirm the action without prompting.
    --help  Show this message and exit.
  

• Suggested Fix: Add --yes to the options for apm runtime remove in docs/cli-reference.md.

---

Clean Areas

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

• apm init — Help text, options, and docs are consistent.
• apm install — All flags (--runtime, --exclude, --only, --update, --dry-run, --verbose) match docs.
• apm update — Help text and docs are consistent.
• apm deps list, apm deps tree, apm deps info, apm deps clean — All consistent with docs.
• apm mcp search, apm mcp show — Consistent with docs.
• apm config get, apm config set — Consistent with docs.
• apm runtime list, apm runtime status — Consistent with docs.
• Error handling — All tested invalid invocations (--nonexistent-flag, missing required args) produce clean Click error messages with usage hints. No tracebacks observed.

Generated by CLI Consistency Checker

• expires on Mar 5, 2026, 1:30 PM UTC

[danielmeppiel]

Closing as superseded by #152 (next day's report). All shared findings plus the unique apm search/apm show reference issue from this report are addressed in the doc-sync PR #153.

The one finding unique to this issue (apm search and apm show referenced as top-level commands instead of apm mcp search/apm mcp show) is included in the fix.