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

[github-actions]

CLI Consistency Report

Date: 2026-05-20
APM Version: 0.12.4 (14b9a73)
Commands Inspected: 28 (top-level + all core, deps, mcp, config, runtime subcommands)

Summary

Severity	Count
High	1
Medium	3
Low	2

---

High Severity

apm config list does not exist

• Command: apm config list
• Problem: The command apm config list fails with an error. The subcommands for apm config are get, set, and unset. There is no list subcommand. Running bare apm config (no subcommand) shows the current configuration table, but this is undiscoverable from apm config --help, which only lists subcommands and gives no indication that running it without arguments produces output.
• Evidence:

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

  The apm config --help output only shows:

  Commands:
    get    Get a configuration value
    set    Set a configuration value
    unset  Unset a configuration value
  

• Suggested Fix: Either (a) add apm config list as an alias or explicit subcommand that runs the same table display as bare apm config, or (b) add a note in apm config --help that running apm config without a subcommand shows the current configuration. Option (a) is preferred for discoverability.

---

Medium Severity

apm deps list missing -v / --verbose flag

• Command: apm deps list
• Problem: Every other inspection/list command that produces output has -v, --verbose for detailed output. apm deps list has no verbose flag at all, making it inconsistent with mcp list (-v), mcp search (-v), mcp show (-v), deps update (-v), install (-v), uninstall (-v), etc.
• Evidence:

  $ apm deps list --help
  Usage: apm deps list [OPTIONS]
  
    List installed APM dependencies
  
  Options:
    -g, --global  List user-scope dependencies (~/.apm/) instead of project
    --all         Show both project and user-scope dependencies
    --insecure    Show only installed dependencies locked to (redacted) sources
    --help        Show this message and exit.
  

  Compare with apm mcp list --help which has -v, --verbose Show detailed output.
• Suggested Fix: Add -v, --verbose to apm deps list to show additional metadata (e.g., resolved refs, install paths) consistent with other list commands.

apm deps update missing --dry-run flag

• Command: apm deps update
• Problem: All other mutating commands (install, uninstall, update, compile, deps clean, pack, prune) support --dry-run to preview changes without applying them. apm deps update does not, making it the only mutating command without this safety flag.
• Evidence:

  $ apm deps update --help
  Usage: apm deps update [OPTIONS] [PACKAGES]...
  
    Update APM dependencies to latest refs
  
  Options:
    -v, --verbose                 Show detailed update information
    --force                       Overwrite locally-authored files on collision
    -t, --target TARGET           ...
    --parallel-downloads INTEGER  ...
    -g, --global                  Update user-scope dependencies (~/.apm/)
    --legacy-skill-paths          ...
    --help                        Show this message and exit.
  

  No --dry-run present.
• Suggested Fix: Add --dry-run to apm deps update to show what would be updated without applying changes, consistent with all other mutating commands.

apm mcp install --help uses non-standard help format

• Command: apm mcp install
• Problem: The apm mcp install --help output renders its options as raw text in the command description rather than as structured Click options. This means --transport, --url, --env, --header, --registry, etc. are not individually listed as options with their types, defaults, and descriptions. Every other command with options displays them in the standard Options: block. This makes apm mcp install help non-uniform and harder to parse.
• 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) --registry URL      Custom registry URL
    --mcp-version VER    Pin registry entry to a specific version --dev / --dry-
    run / --force / --verbose / --no-policy
  

  The "Common options" are appended to the --help option's description text rather than being real Click options.
• Suggested Fix: Either (a) expose the full set of --mcp-related options as real Click options on apm mcp install, or (b) clearly separate the "see also" reference from the Options block using an epilog section so it does not appear to be part of the --help option description.

---

Low Severity

apm update and apm deps update have nearly identical descriptions, causing confusion

• Commands: apm update, apm deps update
• Problem: Both commands are described as updating dependencies to latest refs, making it unclear when to use one vs the other. apm update ("Refresh APM dependencies to the latest matching refs") offers an interactive plan with -y/--yes for CI, while apm deps update ("Update APM dependencies to latest refs") takes optional package names and has --force/--target flags but no --yes. Users may not know which command to use.
• Evidence:
  • apm update --help: "Refresh APM dependencies to the latest matching refs" -- Options: -y, --dry-run, -v
  • apm deps update --help: "Update APM dependencies to latest refs" -- Options: -v, --force, -t, --parallel-downloads, -g
• Suggested Fix: Clarify in each command's description what distinguishes them. For example, apm update could say "Interactive update plan for all dependencies (preferred for day-to-day use)" and apm deps update could say "Low-level update for specific packages with target/force control".

docs/cli-reference.md does not exist

• Command: N/A (documentation gap)
• Problem: There is no docs/cli-reference.md file. The docs/ directory contains only an Astro site scaffold with docs/src/content/docs/index.mdx and a progress file. There is no CLI reference documentation in a browsable markdown format.
• Evidence: ls docs/ shows only Astro framework files; docs/src/content/docs/ contains only 404.md and index.mdx.
• Suggested Fix: Create a docs/src/content/docs/reference/cli.mdx (or equivalent) as a Starlight page that documents all commands. The packages/apm-guide/.apm/skills/apm-usage/commands.md already has comprehensive content that could be adapted.

---

Clean Areas

The following commands and areas passed all checks:

• Error handling: apm install --nonexistent-flag, apm deps info (no arg), apm config set (no arg) all produce clean, user-friendly error messages with no stack traces.
• Core commands: apm init, apm install, apm uninstall, apm update, apm compile, apm run -- all have consistent help structure, -v/--verbose, and --dry-run where appropriate.
• apm deps group: list, tree, info, clean have clean help text (except list missing -v as noted above).
• apm mcp group: search, show, list have consistent help format.
• apm config: get, set, unset have clean, consistent help text. Bare apm config correctly shows configuration table.
• apm runtime: setup, list, status, remove all have clean help text and consistent structure.
• Flag naming: --dry-run (not --dryrun), --verbose/-v naming is consistent across all commands that support it.
• --help / -h: Works on all commands and subcommands tested.
• --yes / -y: Consistent where applicable (apm update, apm deps clean, apm runtime remove).
• Documentation in packages/apm-guide/.apm/skills/apm-usage/commands.md: Accurately reflects actual CLI commands and flags (no phantom commands documented).
• README.md: Minimal (8 lines, experimental migration notice) -- no CLI commands documented, so no drift possible.

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

• expires on May 22, 2026, 2:10 PM UTC