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

[github-actions]

CLI Consistency Report

Date: 2026-03-20
APM Version: 0.8.3
Commands Inspected: 31

Summary

Severity	Count
High	0
Medium	4
Low	3

---

Medium Severity

--verbose flag is missing -v short alias on apm install

• Command: apm install --verbose
• Problem: apm compile and apm audit both expose -v, --verbose, but apm install --verbose has no -v short alias, breaking muscle-memory consistency across the three commands where verbose logging matters most.
• Evidence:

  # apm install --help
    --verbose                     Show detailed installation information
  
  # apm compile --help
    -v, --verbose                   Show detailed source attribution and optimizer analysis
  
  # apm audit --help
    -v, --verbose                   Show all findings including harmless ones
  ```
  

• Suggested Fix: Add -v as a short alias to the --verbose option in apm install.

---

--yes flag is missing -y short alias on apm runtime remove

• Command: apm runtime remove --yes
• Problem: apm init exposes -y, --yes, but apm runtime remove --yes has no -y short alias, inconsistent within the same CLI.
• Evidence:

  # apm init --help
    -y, --yes  Skip interactive prompts and use auto-detected defaults
  
  # apm runtime remove --help
    --yes   Confirm the action without prompting
  

• Suggested Fix: Add -y as a short alias to the --yes option in apm runtime remove.

---

apm mcp list --limit is missing default value display

• Command: apm mcp list --limit
• Problem: apm mcp search --limit shows [default: 10], but apm mcp list --limit does not display any default, leaving users unsure how many results will be returned.
• Evidence:

  # apm mcp list --help
    --limit INTEGER  Number of results to show
  
  # apm mcp search --help
    --limit INTEGER  Number of results to show  [default: 10]
  

• Suggested Fix: Add a default=10 (or the actual default) to the --limit option in apm mcp list so Click displays [default: N] consistently.

---

apm pack --format is missing default value in help text

• Command: apm pack --format
• Problem: The CLI help shows only Bundle format. with no default indicated, while the documentation states the default is apm. Other options in the same command (--target, --output) explicitly show their defaults.
• Evidence:

  # apm pack --help
    --format [apm|plugin]           Bundle format.
    -t, --target [copilot|vscode|claude|cursor|opencode|all]
                                    Filter files by target (default: auto-detect). 'vscode' is an alias for 'copilot'.
    -o, --output PATH               Output directory (default: ./build).
  

  Documentation (cli-commands.md, line 420): --format [apm|plugin] - Bundle format (default: apm)
• Suggested Fix: Add default="apm" or show_default=True to the --format option so the help text reads [default: apm].

---

Low Severity

apm audit command description is incomplete

• Command: apm audit
• Problem: The top-level description says "Scan installed packages for hidden Unicode characters", but apm audit also supports scanning arbitrary files via --file PATH. A user who doesn't read the full help may not discover this capability.
• Evidence:

  # apm --help
    audit      Scan installed packages for hidden Unicode characters
  
  # apm audit --help
    --file PATH    Scan an arbitrary file (not just APM-managed files)
  

• Suggested Fix: Update the description to something like: "Scan installed packages (or any file) for hidden Unicode characters".

---

apm config get description implies single-value retrieval

• Command: apm config get
• Problem: The help text says "Get a configuration value" (singular), but when KEY is omitted the command displays all configuration values. This is confusing.
• Evidence:

  # apm config get --help
  Usage: apm config get [OPTIONS] [KEY]
  
    Get a configuration value
  
  Options:
    --help  Show this message and exit.
  

  Documentation (cli-commands.md, line 1059): "If KEY is omitted, displays all configuration values."
• Suggested Fix: Update the description to "Get one or all configuration values".

---

apm compile -o references undocumented "single-file mode"

• Command: apm compile -o / --output
• Problem: The help text reads "Output file path (for single-file mode)", but "single-file mode" is unexplained jargon. It requires the --single-agents flag to activate and is described as "legacy mode" in that flag's help text.
• Evidence:

  # apm compile --help
    -o, --output TEXT               Output file path (for single-file mode)
    --single-agents                 Force single-file compilation (legacy mode)
  

• Suggested Fix: Update the description to "Output file path (use with --single-agents legacy mode)" or simply "Output file path for legacy single-file compilation".

---

Clean Areas

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

• apm init: Clear, consistent help text; -y/--yes and --plugin well-described.
• apm install: Comprehensive option descriptions, accurate defaults shown where applicable.
• apm uninstall: Simple, accurate, and consistent.
• apm prune: Accurate and concise.
• apm compile: Rich option set, well-documented targets and flags (except -o note above).
• apm run / apm preview / apm list: Consistent -p/--param usage; clean output.
• apm pack / apm unpack: Mostly consistent; --force, --dry-run, --skip-verify well-described.
• apm audit: Exit codes, option descriptions, and short aliases (-v, -f, -o) are well-implemented (except description wording above).
• apm deps (all subcommands): Accurate; update correctly marks [PACKAGE] as optional.
• apm mcp search / mcp show / mcp list: Functional; search has correct default.
• apm config set: Accurate; describes supported keys and accepted values.
• apm runtime setup / list / remove / status: Accurate; --version and --vanilla well-described.
• Error handling: All tested commands produce clean error messages (no stack traces) on invalid input.
• Documentation cross-reference: docs/src/content/docs/reference/cli-commands.md is accurate and complete. All documented commands exist in the CLI. References to apm audit --ci in other docs are correctly marked as "planned but not yet available".

Generated by CLI Consistency Checker · ◷

• expires on Mar 22, 2026, 1:31 PM UTC