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

[github-actions]

CLI Consistency Report

Date: 2026-05-06
APM Version: 0.12.2 (aa584f6)
Commands Inspected: 62 (top-level, all core, deps, mcp, config, runtime, cache, marketplace, policy, experimental, and remaining commands)

Summary

Severity	Count
High	0
Medium	3
Low	3

---

Medium Severity

apm deps update --target missing windsurf value

• Command: apm deps update --help
• Problem: The --target flag for apm deps update does not list windsurf as a valid value, but apm install --target does include it, and the CLI reference docs document windsurf as valid for deps update.
• Evidence (CLI):

  apm deps update --target help:
    -t, --target TARGET   Valid values: copilot, claude, cursor, opencode, codex,
                          gemini, agent-skills, all.
  

  vs

  apm install --target help:
    -t, --target TARGET   Values: copilot, claude, cursor, opencode, codex,
                          gemini, windsurf, agent-skills, all.
  

  And docs (cli-commands.md line 1023): Valid values: copilot, claude, cursor, opencode, codex, gemini, windsurf, agent-skills, vscode, agents (deprecated), all.
• Suggested Fix: Add windsurf to the --target choices for apm deps update to match apm install, or document the intentional difference.

---

apm install --runtime missing windsurf

• Command: apm install --help
• Problem: The CLI help for --runtime does not list windsurf as a supported value, but the documentation explicitly includes it.
• Evidence (CLI):

  --runtime TEXT   Target specific runtime only (copilot, codex, vscode, cursor,
                   opencode, gemini, claude)
  

• Evidence (docs, cli-commands.md line 91):

  - `--runtime TEXT` - Target specific runtime only (copilot, codex, vscode, cursor, opencode, gemini, claude,windsurf)
  

• Suggested Fix: Either add windsurf to the --runtime help text, or update the docs to remove it if windsurf is not supported via --runtime.

---

apm install --target undocumented copilot-cowork value

• Command: apm install --help
• Problem: The CLI help for --target in apm install does not list copilot-cowork as a valid value, but the documentation does. This creates confusion about whether the value is accepted.
• Evidence (CLI):

  -t, --target TARGET   Values: copilot, claude, cursor, opencode, codex, gemini,
                        windsurf, agent-skills, all.
  

• Evidence (docs, cli-commands.md line 94):

  --target [copilot|claude|cursor|codex|opencode|gemini|windsurf|agent-skills|copilot-cowork|all]
  

• Suggested Fix: If copilot-cowork is a gated/experimental-only target, the docs should clearly caveat it (e.g., "only when copilot-cowork experimental flag is enabled"). If it is always valid, add it to the CLI help text.

---

Low Severity

apm mcp install options not in Options section

• Command: apm mcp install --help
• Problem: Unlike all other commands, apm mcp install does not list its options in a proper Options section. Instead, common options are embedded in the description body text, making it harder to parse.
• Evidence:

  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  ...
  

• Suggested Fix: Move the common options out of the description/help text and into a proper Options block, or at minimum keep the freeform list outside the Options: section for clarity.

---

apm run not labeled as experimental in CLI help

• Command: apm run --help
• Problem: The documentation (cli-commands.md) labels apm run as (Experimental), but the CLI help text just says "Run a script with parameters" with no mention of experimental status.
• Evidence (docs, cli-commands.md line 1606):

  ### `apm run` (Experimental) - Execute prompts
  

• Evidence (CLI):

  Usage: apm run [OPTIONS] [SCRIPT_NAME]
  
    Run a script with parameters
  

• Suggested Fix: Either add "(experimental)" to the CLI help description if the feature is still experimental, or remove the "(Experimental)" label from the docs if the feature has graduated.

---

apm runtime not labeled as experimental in CLI help

• Command: apm runtime --help
• Problem: The documentation (cli-commands.md) labels apm runtime as (Experimental), but the CLI help text just says "Manage AI runtimes" with no indication of experimental status.
• Evidence (docs, cli-commands.md line 2003):

  ### `apm runtime` (Experimental) - Manage AI runtimes
  

• Evidence (CLI):

  Usage: apm runtime [OPTIONS] COMMAND [ARGS]...
  
    Manage AI runtimes
  

• Suggested Fix: Same as above -- align the experimental label between docs and CLI, in whichever direction is accurate.

---

Clean Areas

• Error handling: All tested invalid-input cases (apm install --nonexistent-flag, apm deps info with no arg, apm config set with no args) produce clean usage errors without stack traces.
• --help / -h: Works correctly on every tested command and subcommand.
• Core commands: apm init, apm install, apm uninstall, apm compile, apm uninstall, apm prune, apm outdated, apm pack, apm audit, apm view, apm search -- help text is clear and consistent.
• deps subgroup: deps list, deps tree, deps info, deps clean -- consistent formatting, flags, and descriptions.
• mcp subgroup: mcp search, mcp show, mcp list -- consistent use of --limit and -v, --verbose.
• config subgroup: config get, config set, config unset -- consistent format; unset is not documented in the task checklist but works correctly.
• runtime subgroup: runtime setup, runtime list, runtime remove, runtime status -- consistent and clear.
• marketplace subgroup: All 13+ subcommands have coherent help text.
• experimental subgroup: list, enable, disable, reset -- clean and consistent.
• --dry-run: Consistently present on install, uninstall, deps clean, prune, pack, audit where applicable.
• --verbose / -v: Consistently named and described across all commands that support it.
• -g, --global: Consistently described as "user scope" in all commands that support it.

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.6M · ◷

• expires on May 8, 2026, 1:39 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-05-08T13:39:30.568Z.

Closed by Workflow