[cli-consistency] CLI Consistency Report -- 2026-05-18

[github-actions]

CLI Consistency Report

Date: 2026-05-18
APM Version: 0.13.0 (ced3ef6)
Commands Inspected: 37 (25 top-level + 12 subcommands across deps, mcp, config, runtime, cache, marketplace, experimental groups)

Summary

Severity	Count
High	0
Medium	3
Low	2

---

Medium Severity

apm cache clean has two conflicting confirmation-skip flags

• Command: apm cache clean
• Problem: Both -f, --force and -y, --yes are documented with the exact same description: "Skip confirmation prompt". Every other command in APM uses only -y, --yes for this purpose (apm deps clean, apm runtime remove, apm uninstall all use -y, --yes exclusively). Having two flags with identical descriptions for the same behavior is confusing and inconsistent with the rest of the CLI.
• Evidence:

  $ apm cache clean --help
  Options:
    -f, --force  Skip confirmation prompt
    -y, --yes    Skip confirmation prompt
  

  Compare with apm deps clean --help which only has -y, --yes.
• Suggested Fix: Remove -f, --force from apm cache clean (or repurpose it with a distinct meaning like "force even if cache is in use"), leaving -y, --yes as the sole confirmation-skip flag consistent with other commands.

apm mcp install --help hides options in prose instead of exposing them as CLI flags

• Command: apm mcp install
• Problem: The --help output lists the available options (--transport, --url, --env, --header, --registry, --mcp-version, --dev, --dry-run, --force, --verbose, --no-policy) only as plain text inside the description block, not as parseable --flag entries in the Options section. Users cannot discover, autocomplete, or verify these flags through the standard help interface.
• Evidence:

  $ apm mcp install --help
  Usage: apm mcp install [OPTIONS] NAME
  
    Add an MCP server to apm.yml. Alias for 'apm install --mcp'.
    ...
  Options:
    --help  Show this message and exit.
  
    Common options (see `apm install --mcp --help` for full list): --transport
    [stdio|http|sse|streamable-http] --url URL  ...
  

  The "Common options" block is part of the help description text, not registered Click options.
• Suggested Fix: Either (a) register the shared options on apm mcp install so they appear in the Options section and are actually usable, or (b) make the description clearly state this is a pass-through alias and direct users to apm install --mcp --help at the top, not buried at the end.

apm audit one-line description understates the command's scope

• Command: apm audit
• Problem: The top-level apm --help shows the audit description as "Scan installed packages for hidden Unicode characters". This omits drift detection and CI gate capabilities that are central features of the command. The official docs title is "Scan installed primitives for hidden Unicode, drift, and lockfile/policy violations."
• Evidence:

  $ apm --help
  Commands:
    audit         Scan installed packages for hidden Unicode characters
  

  The actual apm audit --help synopsis covers Unicode scanning, --strip, drift detection (--no-drift), CI gating (--ci), policy checks (--policy), and SARIF/JSON/Markdown output formats.
• Suggested Fix: Update the short description to something like: Scan for hidden Unicode, detect drift, and run CI/CD lockfile integrity gates

---

Low Severity

apm prune is missing --verbose / -v flag

• Command: apm prune
• Problem: apm prune removes packages not listed in apm.yml but provides no verbose mode to show what it is doing step-by-step. The analogous destructive commands all support -v, --verbose: apm uninstall ("Show detailed removal information"), apm pack ("Show detailed packing information").
• Evidence:

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

• Suggested Fix: Add -v, --verbose Show detailed removal information to apm prune, consistent with apm uninstall.

apm outdated uses a non-standard -j short flag for parallelism

• Command: apm outdated
• Problem: --parallel-checks is aliased as -j, which is not used anywhere else in the APM CLI and breaks the pattern. All other parallel-download flags (apm install --parallel-downloads, apm deps update --parallel-downloads) use the long form only, with no short flag.
• Evidence:

  $ apm outdated --help
  Options:
    -j, --parallel-checks INTEGER  Max concurrent remote checks (default: 4, 0 =
                                   sequential)
  

• Suggested Fix: Remove the -j short alias so only --parallel-checks is exposed, matching the pattern of other parallel flags in the CLI.

---

Clean Areas

• All 25 top-level commands exist and match documentation: Every command in docs/src/content/docs/reference/cli/ has a corresponding working command in the CLI, and vice versa. No phantom commands or missing entries found.
• README command examples: All commands referenced in README.md (apm install, apm compile, apm marketplace add) are valid and functional.
• Invalid-input error handling: All tested commands produce clean, human-readable error messages (not stack traces) when given missing arguments or unknown flags. Examples verified: apm install --nonexistent-flag, apm deps info (missing PACKAGE), apm config set (missing KEY), apm mcp show (missing SERVER_NAME).
• --help / -h availability: Works on every tested command and subcommand.
• -y, --yes consistency: Present and consistent on all confirmation-prompting commands except the cache clean duplication noted above.
• --dry-run consistency: Named identically across all commands that support it (apm install, apm uninstall, apm prune, apm deps clean, apm compile, apm pack, apm audit, apm update).
• -v, --verbose short flag: Consistent short flag usage across all commands that have it.
• Deprecation disclosures: Deprecated flags and commands (apm install --update, apm pack --target, apm unpack) are clearly labeled in help text.

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• astral.sh
• index.crates.io

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "astral.sh"
    - "index.crates.io"

See Network Configuration for more information.

Generated by CLI Consistency Checker · ● 1M · ◷

• expires on May 20, 2026, 2:38 PM UTC