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

[github-actions]

CLI Consistency Report

Date: 2026-03-09
APM Version: 0.7.4 (4690b96)
Commands Inspected: 28

Command	Status
apm (top-level)	✅
apm init	✅
apm install	✅
apm uninstall	✅
apm update	✅
apm compile	✅
apm run	✅
apm list	✅
apm preview	✅
apm prune	✅
apm deps	✅
apm deps list	✅
apm deps tree	✅
apm deps info	✅
apm deps clean	✅
apm deps update	✅
apm mcp	✅
apm mcp list	✅
apm mcp search	✅
apm mcp show	✅
apm config	✅
apm config get	✅
apm config set	✅
apm runtime	✅
apm runtime setup	✅
apm runtime list	✅
apm runtime remove	✅
apm runtime status	✅

Summary

Severity	Count
High	0
Medium	3
Low	2

---

Medium Severity

Documentation claims apm config shows current config when run without subcommands — it doesn't

• Command: apm config
• Problem: docs/cli-reference.md states: "Running apm config without subcommands displays the current configuration." However, running apm config with no arguments prints the help text and exits with code 2 (error), not a config display.
• Evidence:
  • Docs (docs/cli-reference.md, line 827–828): "Manage APM CLI configuration settings. Running apm config without subcommands displays the current configuration."
  • Actual CLI output:

    $ apm config
    Usage: apm config [OPTIONS] COMMAND [ARGS]...
    
      Configure APM CLI
    
    Options:
      --help  Show this message and exit.
    
    Commands:
      get  Get a configuration value
      set  Set a configuration value
    

    (exits with code 2)
• Suggested Fix: Either implement apm config (no args) to show current config (use apm config get output), or update docs/cli-reference.md to remove the claim and document that apm config get is the correct way to display config values.

---

Inconsistent emoji usage across apm --help command listing

• Command: apm --help (top-level)
• Problem: Only 4 of 12 top-level commands have emojis in their one-line descriptions, making the help output visually inconsistent. The project owner has confirmed the policy: "we don't want any emojis in any output." Both violations of that policy and cross-command inconsistency are present.
• Evidence:

  Commands:
    compile    🚀 Compile APM context into distributed AGENTS.md files  ← emoji
    config     Configure APM CLI                                         ← no emoji
    deps       Manage APM package dependencies                           ← no emoji
    init       🚀 Initialize a new APM project                          ← emoji
    install    📦 Install APM and MCP dependencies (auto-creates...     ← emoji
    list       List available scripts in the current project             ← no emoji
    mcp        Browse MCP server registry                                ← 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
    runtime    Manage AI runtimes                                        ← no emoji
    uninstall  Remove APM packages from apm.yml and apm_modules          ← no emoji
    update     ⬆️  Update APM to the latest version                     ← emoji
  ```
  

• Suggested Fix: Remove emojis from the help strings of compile, init, install, and update to match the style of the other 8 commands (and comply with the "no emojis in output" policy).

---

apm compile option descriptions contain emojis — no other command does this

• Command: apm compile --help
• Problem: Five option descriptions in apm compile include emojis. This is unique to this command; no other command's option descriptions use emojis, making apm compile a visual outlier.
• Evidence:

  --dry-run           🔍 Preview compilation without writing files (shows placement decisions)
  --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
  

  Compare with apm install --help options (no emojis):

  --verbose    Show detailed installation information
  --dry-run    Show what would be installed without installing
  --force      Overwrite locally-authored files on collision
  

• Suggested Fix: Remove emojis from the five option descriptions in apm compile.

---

Low Severity

apm runtime remove --yes option description has a trailing period

• Command: apm runtime remove --help
• Problem: The --yes option description ends with a period, while no other option description across the entire CLI uses trailing punctuation.
• Evidence:

  --yes   Confirm the action without prompting.    ← trailing period
  

  Compare with all other options (e.g.):

  --dry-run  Show what would be removed without removing     ← no period
  --check    Only check for updates without installing       ← no period
  --vanilla  Install runtime without APM configuration (uses runtime's native defaults)  ← no period
  

• Suggested Fix: Remove the trailing period: --yes Confirm the action without prompting

---

apm uninstall one-line description understates scope of the command

• Command: apm uninstall --help
• Problem: The brief description says "Remove APM packages from apm.yml and apm_modules" but the command actually also removes integrated prompt/agent/hook files from .github/, .claude/, and entries from apm.lock. The brief description underrepresents what the command does.
• Evidence:

  $ apm uninstall --help
  Usage: apm uninstall [OPTIONS] PACKAGES...
  
    Remove APM packages from apm.yml and apm_modules
  

  The full uninstall scope per docs includes: package entry in apm.yml, package folder in apm_modules/, transitive deps, integrated prompts, agents, chatmodes, Claude commands, skill folders, hooks, Claude hook settings, and lockfile entries.
• Suggested Fix: Update to something like: Remove APM packages, their integrated files, and apm.yml entries

---

Clean Areas

• All commands return sensible error messages (not stack traces) on invalid input
• --help / -h works correctly on every command and subcommand tested
• --dry-run flag is consistently named across all commands that support it (install, uninstall, prune, compile)
• --verbose / -v flags are consistently named
• All documented subcommands exist in the CLI (apm mcp list, apm runtime list/remove/status, etc.)
• No crashes or tracebacks observed on any tested command path
• Error messages are helpful and suggest --help for recovery
• apm mcp list and apm mcp search both correctly support --limit INTEGER
• apm deps info PACKAGE correctly requires the argument and surfaces a clean error when omitted
• All documented apm runtime setup options (--version, --vanilla) are present in the CLI

Generated by CLI Consistency Checker · ◷

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