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

[github-actions]

CLI Consistency Report

Date: 2026-06-03
APM Version: 0.16.1 (d4e164b)
Commands Inspected: 25

Summary

Severity	Count
High	1
Medium	2
Low	2

---

High Severity

apm config output violates project ASCII encoding rules

• Command: apm config
• Problem: Running apm config with no subcommand renders a table using Unicode box-drawing characters (┏, ━, ┳, ┃, ┡, ╇, │, └, ─, ┘, etc.) from the rich library. The project's encoding rules explicitly require all CLI output strings to stay within printable ASCII (U+0020-U+007E) to avoid UnicodeEncodeError: 'charmap' codec can't encode character on Windows cp1252 terminals.
• Evidence (raw bytes via cat -v):

  M-bM-^TM-^OM-bM-^TM-^AM-bM-^TM-^AM-bM-^TM-^AM-bM-^TM-^AM-bM-^TM-^AM-bM-^TM-^A...
  M-bM-^TM-^C Category     M-bM-^TM-^C Setting          M-bM-^TM-^C Value ...
  

  The encoding rules (.github/instructions) state: "Do NOT use: Unicode box-drawing characters (e.g. ─, │, ┌)."
• Suggested Fix: Replace the rich table in the apm config output with an ASCII-safe table renderer. Use |, -, and + characters for table borders. The docs already note "Falls back to plain text if rich is unavailable" -- this fallback behavior should be the default, or the rich renderer should be restricted to Unicode-capable terminals detected at runtime.

---

Medium Severity

apm mcp install --help does not expose its options as registered CLI flags

• Command: apm mcp install --help
• Problem: The command only shows --help as a registered option. All other flags (--transport, --url, --env, --header, --registry, --mcp-version, --dev, --dry-run, --force, --verbose, --no-policy) appear as unformatted prose at the bottom of the Options section, not as proper Click-registered options. This makes the command's interface non-discoverable via --help.
• Evidence:

  Options:
    --help  Show this message and exit.
  
    Common options (see `apm install --help` for full list): --transport
    [stdio|http|sse|streamable-http] --url URL           Server URL for remote
    transports --env KEY=VALUE     Environment variable (repeatable) --header
    KEY=VALUE  HTTP header (repeatable) --registry URL      Custom registry URL
    --mcp-version VER    Pin registry entry to a specific version --dev / --dry-
    run / --force / --verbose / --no-policy
  

• Suggested Fix: Either register the common options explicitly in the mcp_install Click command (even if just forwarded to install), or move the prose block to a properly formatted epilog section with aligned option descriptions. At minimum, use a multi-line string with consistent indentation so each option appears on its own line.

apm config list missing -- user-expectation gap with no documentation bridge

• Command: apm config list
• Problem: The subcommand apm config list does not exist and returns an error. Users familiar with analogous tools (npm config list, git config --list) will instinctively try this. The CLI has get, set, and unset but no list. apm config (bare, no subcommand) does show all config values as a table, but this is undiscoverable.
• Evidence:

  $ apm config list
  Usage: apm config [OPTIONS] COMMAND [ARGS]...
  Try 'apm config --help' for help.
  
  Error: No such command 'list'.
  

  The apm config --help output shows only three subcommands: get, set, unset.
• Suggested Fix: Add apm config list as an alias subcommand for apm config get with no arguments (which already prints all keys). This would align with the mental model from npm config list and git config --list. Alternatively, add a note in apm config --help that apm config (bare) shows all values.

---

Low Severity

apm deps update deprecation not surfaced in help text

• Command: apm deps update --help
• Problem: The documentation (docs/src/content/docs/reference/cli/deps.md) prominently marks apm deps update as deprecated in favor of apm update, but the --help output contains no deprecation notice. Users who discover the command via apm deps --help will not learn it is deprecated.
• Evidence:

  $ apm deps update --help
  Usage: apm deps update [OPTIONS] [PACKAGES]...
  
    Update APM dependencies to latest refs
  

  (No deprecation warning shown. Docs mark it with a caution block: "apm deps update is deprecated in favor of apm update".)
• Suggested Fix: Prepend [DEPRECATED] to the command description string, or append a deprecation notice line to the help epilog. Click supports the deprecated=True parameter on commands natively, which auto-adds a deprecation warning on invocation.

Inconsistent --verbose flag descriptions across commands

• Commands: Multiple
• Problem: The --verbose / -v flag has inconsistent descriptions across commands. Some are terse and generic, others are command-specific.
• Evidence:
  • apm init: Show detailed output
  • apm install: Show detailed installation information
  • apm uninstall: Show detailed removal information
  • apm update: Show unchanged deps and detailed pipeline diagnostics
  • apm compile: Show detailed source attribution and optimizer analysis
  • apm run: Show detailed output
  • apm mcp search: Show detailed output
  • apm mcp show: Show detailed output
• Suggested Fix: Standardize to a consistent short form such as Show detailed output across all commands, or adopt command-specific descriptions uniformly (not a mix of both).

---

Clean Areas

• All 25 commands respond to --help / -h with usage information (no crashes).
• All commands produce sensible error messages on invalid input -- no stack traces observed:
  • apm install --nonexistent-flag -> Error: No such option: --nonexistent-flag
  • apm deps info (missing argument) -> Error: Missing argument 'PACKAGE'.
  • apm config set (missing argument) -> Error: Missing argument 'KEY'.
• --dry-run flag is consistently named across all commands that support it.
• --yes / -y is consistently available where applicable (apm update, apm deps clean).
• apm mcp subcommands (search, show, list) all expose --verbose and --help correctly.
• Documentation (docs/src/content/docs/reference/cli/config.md) correctly documents apm config subcommands as get, set, unset.
• apm deps subcommands are all present and match documentation.
• apm runtime setup correctly requires a positional argument from the allowed set {copilot|codex|llm|gemini}.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• astral.sh

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

network:
  allowed:
    - defaults
    - "astral.sh"

See Network Configuration for more information.

Generated by CLI Consistency Checker · sonnet46 1.8M · ◷

• expires on Jun 5, 2026, 2:41 PM UTC