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

[github-actions]

CLI Consistency Report

Date: 2026-05-19
APM Version: 0.14.0 (a4957b9)
Commands Inspected: 23 (apm, init, install, uninstall, update, compile, run, deps, deps list, deps tree, deps info, deps clean, deps update, mcp, mcp list, mcp search, mcp show, mcp install, config, config set, config get, runtime, runtime setup)

Summary

Severity	Count
High	0
Medium	3
Low	3

---

Medium Severity

apm mcp install --help options are rendered as unformatted inline text, not as proper CLI option entries

• Command: apm mcp install --help
• Problem: All forwarded flags (--transport, --url, --env, --header, --registry, --mcp-version, --dev, --dry-run, --force, --verbose, --no-policy) are listed as a single run-on paragraph in the help text rather than as structured --flag description entries. This breaks the formatting convention of every other command in APM and makes the help text hard to read.
• Evidence:

  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) --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 proxy the full option list from apm install --mcp so Click renders them properly, or add a structured epilog section that clearly lists each flag on its own line with a short description and a "See apm install --mcp --help for full details" note.

---

apm config list fails with "No such command" -- not discoverable from help

• Command: apm config list
• Problem: apm config --help shows subcommands get, set, unset but no list. Running apm config list produces an error. However, apm deps has a prominent list subcommand, so users coming from apm deps list will naturally try apm config list expecting similar behavior. The bare apm config (no subcommand) does show a config table, but this is undiscoverable from the subcommand list. The docs correctly describe the bare apm config invocation, but the help output does not hint at it.
• Evidence:

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

  $ apm config --help
  Commands:
    get    Get a configuration value
    set    Set a configuration value
    unset  Unset a configuration value
  

  The apm config docs say: "With no subcommand, apm config prints a table..." -- but the help text does not mention this behavior at all.
• Suggested Fix: Add a line to apm config --help's description explaining that running apm config with no subcommand prints the merged project + global config table. Example: "Run with no subcommand to print the current configuration table."

---

apm deps update and apm update have divergent interfaces with no guidance on which to prefer

• Command: apm deps update vs apm update
• Problem: Two commands serve similar purposes but expose different options with no cross-reference or deprecation notice:
  • apm update has --yes/-y (skip confirmation), --dry-run (render plan without applying).
  • apm deps update has --force, --parallel-downloads, --global, --legacy-skill-paths.
    Neither command's help text mentions the other or explains when each should be used. The apm install --help text already deprecates --update in favor of apm update, but there is no equivalent guidance for apm deps update.
• Evidence:

  $ apm update --help    # has: --yes, --dry-run, --verbose, --target
  $ apm deps update --help  # has: --force, --parallel-downloads, --global, --legacy-skill-paths, --verbose, --target
  # Neither mentions the other
  

• Suggested Fix: Add a "See also" or note in both commands' help text. For example, apm deps update could note "For an interactive update plan with dry-run preview, use apm update." And apm update could note "For per-package control, global scope, or parallel download tuning, use apm deps update."

---

Low Severity

Trailing period inconsistency in apm mcp --help command list

• Command: apm mcp --help
• Problem: The install subcommand description ends with a period while list, search, and show do not.
• Evidence:

  Commands:
    install  Add an MCP server to apm.yml.
    list     List all available MCP servers
    search   Search MCP servers in registry
    show     Show detailed MCP server information
  

• Suggested Fix: Remove the trailing period from install's description to match the other three entries.

---

apm compile --all deprecation note is misplaced in apm install --help

• Command: apm install --help
• Problem: The --target option description in apm install ends with: "Note: '--target all' on 'apm compile' is deprecated; use 'apm compile --all' instead." This note is about apm compile, not apm install. While technically correct, embedding a deprecation notice for a different command inside apm install's option text is confusing and unexpected.
• Evidence: End of the --target description in apm install --help:

  Note: '--target all' on 'apm compile' is deprecated; use 'apm compile
  --all' instead.
  

• Suggested Fix: Move this deprecation note to apm compile --help (inside the --all option description or the general description), and remove it from apm install's option text.

---

apm mcp install --help common-options block has broken line wrapping

• Command: apm mcp install --help
• Problem: The "Common options" block at the bottom of apm mcp install --help wraps at terminal width in a way that splits flag names across lines (e.g., "--dry-" on one line and "run / --force" on the next), making it very hard to parse.
• Evidence:

    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) --registry URL      Custom registry URL
    --mcp-version VER    Pin registry entry to a specific version --dev / --dry-
    run / --force / --verbose / --no-policy
  

  ("--dry-" wraps to the next line before "run")
• Suggested Fix: Format the common options as a bullet list or newline-separated entries in the epilog, which avoids mid-flag line breaks regardless of terminal width.

---

Clean Areas

• All commands return proper error messages (no stack traces) for invalid flags or missing required arguments.
• --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: help text and docs are in sync.
• apm mcp list, apm mcp search, apm mcp show: consistent flag naming and formatting.
• apm config get, apm config set: correct and consistent.
• apm runtime, apm runtime setup: help text matches documentation.
• --dry-run is consistently named (no --dryrun variants found).
• --verbose / -v is consistently present across commands that support it.
• --target / -t is consistently named and described across install, update, compile, deps update.
• Documentation in docs/src/content/docs/reference/cli/ is generally well-maintained and matches CLI behavior.

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 · ● 1.2M · ◷

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

[github-actions]

This issue was automatically closed because it expired on 2026-05-21T14:20:34.491Z.

Closed by Workflow