[cli-consistency] CLI Consistency Report — 2026-05-21

[github-actions]

CLI Consistency Report

Date: 2026-05-21
APM Version: 0.12.4 (6fa1427)
Commands Inspected: 30 (all top-level commands + subcommands listed in task spec plus additional commands found via apm --help)

Summary

Severity	Count
High	1
Medium	3
Low	2

---

High Severity

windsurf runtime missing from CLI but documented in commands.md

• Command: apm runtime setup, apm runtime remove

• Problem: The internal documentation (packages/apm-guide/.apm/skills/apm-usage/commands.md) lists windsurf as a valid runtime option for both setup and remove, but the actual CLI only accepts {copilot|codex|llm|gemini}.

• Evidence:

  Documentation (commands.md):

  apm runtime setup {copilot|codex|llm|gemini|windsurf}
  apm runtime remove {copilot|codex|llm|gemini|windsurf}
  

  Actual CLI (apm runtime setup --help):

  Usage: apm runtime setup [OPTIONS] {copilot|codex|llm|gemini}
  

  Actual CLI (apm runtime remove --help):

  Usage: apm runtime remove [OPTIONS] {copilot|codex|llm|gemini}
  

• Suggested Fix: Either add windsurf to the Click choice tuple in both runtime setup and runtime remove commands, or remove it from the documentation in commands.md if windsurf runtime management is not yet implemented.

---

Medium Severity

apm config list subcommand does not exist

• Command: apm config list
• Problem: Running apm config list or apm config list --help fails with an error. The apm config group only exposes get, set, and unset. While bare apm config (no subcommand) prints a configuration table, there is no list subcommand for programmatic or scripted listing of all config keys. Users familiar with other CLIs (e.g., git config --list, npm config list) will naturally try apm config list.
• Evidence:

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

  apm config --help output shows only:

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

• Suggested Fix: Add a list alias or subcommand that prints the same output as bare apm config, or document in apm config --help that running apm config with no subcommand lists all configuration values.

---

apm mcp install options shown informally rather than as parsed CLI flags

• Command: apm mcp install
• Problem: The help text for apm mcp install lists supported options as an informal prose block rather than proper Click-parsed flags. All other commands show options as proper --flag DESCRIPTION entries. While the options do work (they pass through to apm install --mcp), the inconsistent help format makes the command harder to discover and use.
• Evidence:

  $ apm mcp install --help
  ...
  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
  

  Compare to any other command where --dry-run, --verbose, etc. appear as proper Click option entries with full descriptions.
• Suggested Fix: Expose the common apm install --mcp options as real Click parameters on apm mcp install, or restructure it as a true alias so users see the full help naturally. At minimum, move the informal options list out of the --help epilog and into a proper section or note.

---

apm deps update missing --dry-run and -y/--yes flags present on apm update

• Command: apm deps update

• Problem: apm update (the canonical update command) supports both --dry-run (preview without changes) and -y/--yes (skip confirmation prompt). apm deps update, which performs a similar operation, supports neither. This creates inconsistency and may surprise users who switch between the two commands.

• Evidence:

  apm update --help:

  Options:
    -y, --yes      Skip the confirmation prompt (for CI / automation)
    --dry-run      Render the update plan and exit without changing anything
    -v, --verbose  Show unchanged deps and detailed pipeline diagnostics
  

  apm deps update --help:

  Options:
    -v, --verbose                 Show detailed update information
    --force                       Overwrite locally-authored files on collision
    -t, --target TARGET           ...
    --parallel-downloads INTEGER  ...
    -g, --global                  ...
    --legacy-skill-paths          ...
  

  No --dry-run or -y/--yes.

• Suggested Fix: Add --dry-run and -y/--yes to apm deps update for parity with apm update, or add a note in apm deps update --help pointing users to apm update as the preferred command with the richer flag set.

---

Low Severity

apm compile description mentions only "AGENTS.md" but multiple file types are generated

• Command: apm compile
• Problem: The apm compile --help description says "Compile APM context into distributed AGENTS.md files", but the command actually generates target-specific files: .github/copilot-instructions.md, CLAUDE.md, .cursor/rules, etc., depending on the selected target. Mentioning only AGENTS.md is misleading to new users.
• Evidence:

  $ apm compile --help
  Usage: apm compile [OPTIONS]
  
    Compile APM context into distributed AGENTS.md files
  

• Suggested Fix: Update the description to something like "Compile APM context into target-specific agent instruction files" or "Compile APM context and deploy to configured runtime targets".

---

apm update and apm deps update have inconsistent descriptions for the same conceptual action

• Command: apm update, apm deps update

• Problem: Both commands update dependencies, but their one-line descriptions differ slightly:

  • apm update: "Refresh APM dependencies to the latest matching refs"
  • apm deps update: "Update APM dependencies to latest refs"

  The differences ("Refresh" vs "Update", "to the latest matching refs" vs "to latest refs") suggest these are the same operation but give no clear signal to users about which to prefer or when to use each.

• Evidence: Both apm update --help and apm deps update --help headers shown above.

• Suggested Fix: Add a note to apm deps update --help directing users to apm update as the preferred command (which provides an interactive plan, --dry-run, and -y for CI), or deprecate apm deps update if apm update fully supersedes it.

---

Clean Areas

The following commands and areas passed all consistency checks with no issues:

• apm init --help — clear description, consistent flags (-y, --verbose, --target)
• apm install --help — comprehensive flag coverage, deprecation notices clearly labeled
• apm uninstall --help — clean and minimal
• apm run --help — appropriately labeled as experimental
• apm deps list --help, apm deps tree --help, apm deps info --help, apm deps clean --help — all consistent
• apm mcp search --help, apm mcp show --help, apm mcp list --help — consistent and clear
• apm config get --help, apm config set --help — clean
• apm runtime --help, apm runtime setup --help — clean (aside from windsurf issue above)
• apm audit --help — extensive and well-documented
• apm search --help, apm cache --help, apm outdated --help — clean
• apm marketplace --help — comprehensive subcommand listing
• Error handling — all tested error cases (--nonexistent-flag, missing required args) produce clean error messages with usage hints, no stack traces
• --help / -h — works on every command and subcommand tested

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

• expires on May 23, 2026, 2:15 PM UTC

[mrjf]

Closing as part of resetting githubnext/apm to match the current state of upstream microsoft/apm. The Python-to-Go migration experiment has been wound down. See commit ccdafc4 on main.