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

[github-actions]

CLI Consistency Report

Date: 2026-05-27
APM Version: 0.15.0 (3f3d8ad)
Commands Inspected: 27 (top-level + 6 core + 6 deps subcommands + 4 mcp subcommands + 3 config subcommands + 2 runtime subcommands + extras)

Summary

Severity	Count
High	1
Medium	3
Low	2

---

High Severity

CLI output contains non-ASCII Unicode box-drawing characters

• Commands: apm config, apm runtime list
• Problem: Both commands render Rich table output using Unicode box-drawing characters (U+250F ┏, U+2501 ━, U+2503 ┃, U+2533 ┳, etc.). The project encoding rules explicitly prohibit all characters outside printable ASCII (U+0020-U+007E) in CLI output to prevent UnicodeEncodeError: 'charmap' codec can't encode character on Windows cp1252 terminals.
• Evidence:

  $ apm config
                     Current APM Configuration
  ┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
  ┃ Category     ┃ Setting          ┃ Value                      ┃
  ┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
  │ Project      │ Name             │ apm                        │
  ...
  
  $ apm runtime list
  ┏━━━━━━━━━━┳━━━━━━━━━━━━┳...┓
  ┃ Status   ┃ Runtime    ┃...┃
  

  Python verification: apm config output contains 45 lines with non-ASCII bytes (codepoints 0x250f, 0x2501, 0x2533).
• Suggested Fix: Replace rich.table.Table rendering in apm config and apm runtime list with ASCII-safe output. Use tabulate with tablefmt="simple" or a custom formatter, and the STATUS_SYMBOLS dict from src/apm_cli/utils/console.py for status indicators. The apm config docs already note it "Falls back to plain text if rich is unavailable" -- the ASCII fallback should become the default.

---

Medium Severity

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

• Command: apm mcp install --help
• Problem: apm mcp install is documented as an alias for apm install --mcp. However, its --help output lists only --help as a formal option; all other flags (--transport, --url, --env, --header, --registry, --mcp-version, --dev, --dry-run, --force, --verbose, --no-policy) appear only as inline prose in a footer note. Users cannot discover or tab-complete these options from apm mcp install --help. The inline note is also poorly formatted with mid-flag line breaks.
• 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           Server URL for remote
    transports --env KEY=VALUE     Environment variable (repeatable) --header
    KEY=VALUE  HTTP header (repeatable) ...
  

• Suggested Fix: Either (a) propagate all forwarded options as actual Click parameters on apm mcp install so they appear in --help properly, or (b) state clearly in the command description that this is a thin forwarder and direct users to apm install --mcp --help, removing the malformed inline note.

apm install --help embeds cross-command deprecation note inside --target description

• Command: apm install --help
• Problem: The --target option description in apm install --help ends with a note about a different command: "Note: '--target all' on 'apm compile' is deprecated; use 'apm compile --all' instead." This note is about apm compile, not apm install, and is confusing in context.
• Evidence:

  $ apm install --help
  ...
  -t, --target TARGET   ... 'all' = copilot+claude+cursor+opencode+codex+gemini+
                            windsurf (excludes agent-skills); ... Note: '--target
                            all' on 'apm compile' is deprecated; use 'apm compile
                            --all' instead.
  

• Suggested Fix: Remove the apm compile-specific deprecation note from apm install --help. The deprecation should live in apm compile's own help text or docs. If a cross-reference is needed, add a "See also" note in the apm install description section rather than embedding it inside an option description.

apm config group inconsistently lacks a list subcommand

• Command: apm config --help
• Problem: Every other major command group exposes a list subcommand (apm deps list, apm mcp list, apm runtime list). apm config has no list subcommand -- to view config, users run bare apm config. This breaks the consistent pattern and produces a confusing error when users try apm config list by analogy.
• Evidence:

  $ apm config --help
  Commands:
    get    Get a configuration value
    set    Set a configuration value
    unset  Unset a configuration value
  
  $ apm config list
  Error: No such command 'list'.
  
  $ apm deps --help    -> has: list    List installed APM dependencies
  $ apm runtime --help -> has: list    List available and installed runtimes
  $ apm mcp --help     -> has: list    List all available MCP servers
  

• Suggested Fix: Add apm config list as an alias for bare apm config (showing the merged project + global config table). Alternatively, document the bare apm config behavior prominently in the help group description so the intentional pattern difference is clear to users.

---

Low Severity

apm runtime list Status column truncates text mid-word

• Command: apm runtime list
• Problem: The "Status" column renders truncated values ("Install...", "Not install...") with the [+] symbol and status text on separate lines within the same cell, making the table hard to read. This is a secondary symptom of the Unicode table rendering issue.
• Evidence:

  $ apm runtime list
  │ [+]      │ copilot │ GitHub Copilot CLI ... │ Path: /usr/local/bin/copilot │
  │ Install... │         │                        │ Version: GitHub Copilot CLI  │
  │  Not     │ codex   │ OpenAI Codex CLI ...   │                              │
  │ install... │         │                        │                              │
  

• Suggested Fix: Use a fixed-width ASCII status token such as [+] installed and [ ] not installed that fits on one line per row. This also resolves the Unicode issue in this command.

apm deps update and apm update lack differentiation guidance

• Commands: apm deps update, apm update
• Problem: Both commands update dependencies. Their one-line descriptions are nearly identical and give users no guidance on when to use each. apm install --update is deprecated in favour of apm update, but apm deps update carries no similar guidance.
• Evidence:

  $ apm deps update --help
    Update APM dependencies to latest refs
    Options: --verbose, --force, --target, --parallel-downloads, --global, --legacy-skill-paths
  
  $ apm update --help
    Refresh APM dependencies to the latest matching refs
    Options: --yes, --dry-run, --verbose, --target
  

• Suggested Fix: Add a one-sentence distinction to each description. Example: apm update -- "Interactive upgrade planner (use --yes for CI)." apm deps update -- "Low-level re-install of specific packages; prefer 'apm update' for routine upgrades."

---

Clean Areas

• All 27 commands return helpful error messages (not stack traces) for invalid inputs (--nonexistent-flag, missing required arguments like apm deps info, apm config set).
• --help / -h works on every tested command and subcommand.
• apm init, apm install, apm uninstall, apm compile, apm run help text is well-structured and consistent.
• apm deps list, apm deps tree, apm deps info, apm deps clean, apm deps why are clean and well-documented.
• apm mcp search, apm mcp show, apm mcp list are consistent with docs.
• apm config get, apm config set, apm config unset are well-documented.
• apm runtime setup is clean.
• All 27 help pages use imperative mood for descriptions consistently.
• Flag naming (--dry-run, --verbose, -v, --yes, -y, -g/--global) is consistent across all commands that share them.
• The reference docs in docs/src/content/docs/reference/cli/ are comprehensive and accurately reflect the CLI -- no phantom commands or missing command pages found.

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 · sonnet46 1.9M · ◷

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