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

[github-actions]

CLI Consistency Report

Date: 2026-06-12
APM Version: 0.20.0 (43a00c2)
Commands Inspected: 72 (30 top-level + 42 subcommands across deps, mcp, config, runtime, cache, marketplace, policy, plugin, experimental, and marketplace package groups)

Summary

Severity	Count
High	2
Medium	6
Low	5

---

High Severity

Inaccurate top-level description for apm compile

• Command: apm compile
• Problem: The command description says "Compile APM context into distributed AGENTS.md files" but the command actually produces AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, GEMINI.md, and per-client directories depending on the target. The singular focus on "AGENTS.md files" is factually inaccurate and misleading for new users who want to target Claude, Copilot, or Gemini.
• Evidence (CLI help):

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

  The CLI reference docs confirm the real output: "Compile your instructions primitives into the AGENTS.md / CLAUDE.md..." and the targets matrix lists: copilot -> .github/copilot-instructions.md, claude -> CLAUDE.md, gemini -> GEMINI.md, etc.
• Suggested Fix: Update the description to something like: "Compile APM context into agent configuration files (AGENTS.md, CLAUDE.md, copilot-instructions.md, etc.)"

---

apm doctor command has no CLI reference page

• Command: apm doctor
• Problem: apm doctor is a fully functional command (verified via apm doctor --help) and is referenced in the guides, but it has NO corresponding page in docs/src/content/docs/reference/cli/. Every other top-level command has a reference page; doctor is the only one missing.
• Evidence (directory listing):

  ls docs/src/content/docs/reference/cli/
  audit.md  cache.md  compile.md  config.md  deps.md  experimental.md
  find.md   init.md   install.md  list.md    lock.md  marketplace.md
  mcp.md    outdated.md  pack.md  plugin.md  policy.md  preview.md
  prune.md  publish.md  run.md   runtime.md  search.md  self-update.md
  targets.md  uninstall.md  unpack.md  update.md  view.md
  

  doctor.md is absent. The command itself is well-formed:

  Usage: apm doctor [OPTIONS]
  
    Run environment diagnostics (git, network, auth, gh CLI, marketplace
    config). Reports a pass/fail table and exits non-zero if a critical check
    fails.
  
  Options:
    -v, --verbose  Show detailed output
    --help         Show this message and exit.
  

• Suggested Fix: Create docs/src/content/docs/reference/cli/doctor.md following the same structure as sibling pages.

---

Medium Severity

apm deps update --target and apm update --target are missing kiro

• Command: apm deps update, apm update
• Problem: The --target flag in apm deps update omits kiro from its list of valid values. The apm update --target flag does not enumerate valid values at all (only gives informal examples, also without kiro). Both apm install --target and apm compile --target correctly list kiro.
• Evidence:
  • apm deps update --target lists: "copilot, claude, cursor, opencode, codex, gemini, windsurf, agent-skills, all" -- kiro missing
  • apm compile --target lists: "copilot, claude, cursor, opencode, codex, gemini, windsurf, kiro, agent-skills, all"
  • apm install --target lists: "copilot, claude, cursor, opencode, codex, gemini, windsurf, kiro, agent-skills, all"
  • apm update --target shows only: "e.g. claude, copilot, cursor, windsurf, codex, opencode, gemini" -- no full list, kiro missing from examples
• Suggested Fix: Add kiro to the apm deps update --target and apm update --target descriptions. Ensure apm update --target enumerates all valid values with the same format as apm install and apm compile.

---

--force has conflicting semantics across commands

• Command: apm marketplace migrate, apm cache clean
• Problem: In apm marketplace migrate, --force is an alias for --yes ("skip confirmation prompt"). In apm cache clean, -f, --force also means "skip confirmation prompt". But in apm install, apm update, apm pack, apm unpack, and apm deps update, --force means "overwrite locally-authored files on collision" -- a completely different, more destructive action. This inconsistency can mislead users who expect --force to overwrite files, not just skip a prompt.
• Evidence (apm marketplace migrate --help):

  -y, --force, --yes  Overwrite an existing 'marketplace:' block in apm.yml
                      (alias: --yes/-y)
  

  Evidence (apm cache clean --help):

  -f, --force  Skip confirmation prompt
  -y, --yes    Skip confirmation prompt
  

  Evidence (apm install --help):

  --force  Overwrite locally-authored files on collision and deploy despite
           critical security findings
  

• Suggested Fix: In apm cache clean and apm marketplace migrate, rename --force to --yes as the primary flag (keeping -f as a short alias if desired for CI compatibility), so that --force consistently means "overwrite files" across the CLI.

---

apm cache clean has two flags with identical descriptions

• Command: apm cache clean
• Problem: Both -f, --force and -y, --yes have exactly the same help text "Skip confirmation prompt" with no indication that one is an alias for the other, making the help text confusing. Users cannot determine which flag to prefer.
• Evidence:

  Options:
    -f, --force  Skip confirmation prompt
    -y, --yes    Skip confirmation prompt
    --help       Show this message and exit.
  

• Suggested Fix: Document the alias relationship explicitly, e.g.: -f, --force "Skip confirmation prompt" and -y, --yes "Alias for --force (preferred in CI scripts)".

---

apm outdated uses different flag name for concurrency

• Command: apm outdated
• Problem: apm outdated uses -j, --parallel-checks INTEGER for controlling concurrency, while all other commands that support concurrent operations use --parallel-downloads INTEGER (with no short flag). The naming inconsistency (checks vs downloads) plus the unique -j short flag makes the API surface unpredictable.
• Evidence:

  # apm outdated --help
  -j, --parallel-checks INTEGER  Max concurrent remote checks (default: 4, 0 = sequential)
  
  # apm install --help, apm update --help, apm lock --help, apm deps update --help
  --parallel-downloads INTEGER  Max concurrent package downloads (0 to disable parallelism)  [default: 4]
  

• Suggested Fix: Rename to --parallel-checks for semantic clarity (it does checks, not downloads), but align the short flag and default-value documentation style with sibling commands, or use a shared --parallel flag name across the board.

---

apm mcp install --help shows options as unformatted plain text

• Command: apm mcp install
• Problem: The --help output for apm mcp install does not register its forwarded options as proper Click options -- they appear as raw unformatted prose under --help. This makes the help text hard to read and prevents flag discovery via tab completion.
• Evidence:

  Options:
    --help  Show this message and exit.
  
    Common options (see `apm install --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 register the forwarded options as proper Click options (even if they just pass through), or move the "Common options" note into the command's docstring (above the Options: block) so it renders as description text rather than appearing to be a broken options list.

---

Low Severity

--dry-run description wording is inconsistent across commands

• Commands: apm install, apm uninstall, apm update, apm compile, apm audit, apm prune, apm pack, apm deps clean
• Problem: Eight commands support --dry-run but describe it in four different ways, making it harder to build a mental model.
• Evidence:

  install:    "Show what would be installed without installing"
  uninstall:  "Show what would be removed without removing"
  update:     "Render the update plan and exit without changing anything"
  compile:    "Preview compilation without writing files (shows placement decisions)"
  audit:      "Preview what --strip would remove without modifying files"
  prune:      "Show what would be removed without removing"
  pack:       "Show what would be packed without writing"
  deps clean: "Show what would be removed without removing"
  

• Suggested Fix: Standardize to a consistent pattern, e.g.: "Preview what apm <command> would do without making changes."

---

apm compile --no-dedup / --no-force-instructions naming is confusing

• Command: apm compile
• Problem: The flag is displayed as --no-dedup / --no-force-instructions (using the --no-X / --no-Y pattern that typically indicates mutually exclusive boolean values). However both names activate the same behavior. Furthermore the help text says "Alias: --force-instructions" (without the --no- prefix), introducing a third name. The naming implies these options negate each other but they do not.
• Evidence:

  --no-dedup / --no-force-instructions
                                Include the instructions section in
                                CLAUDE.md even when .claude/rules/ is
                                already populated. ... Alias: --force-instructions.
  

• Suggested Fix: Consolidate to a single canonical name. Given the behavior is "force-include instructions", --force-instructions is the most readable name. Deprecate --no-dedup with a note.

---

apm prune is missing -v, --verbose

• Command: apm prune
• Problem: apm prune removes packages and has no -v, --verbose flag for detailed output, while the similar apm uninstall command does provide -v, --verbose. Users removing packages expect to be able to see what was done.
• Evidence:

  # apm prune --help
  Options:
    --dry-run  Show what would be removed without removing
    --help     Show this message and exit.
  
  # apm uninstall --help
  Options:
    --dry-run      Show what would be removed without removing
    -v, --verbose  Show detailed removal information
  

• Suggested Fix: Add -v, --verbose Show detailed removal information to apm prune.

---

apm search and apm mcp search have different --limit defaults and description wording

• Commands: apm search, apm mcp search
• Problem: Both commands have a --limit flag but with different defaults (20 vs 10) and subtly different description wording ("Max results to show" vs "Number of results to show"). The defaults may be intentional but the description inconsistency is not.
• Evidence:

  # apm search --help
  --limit INTEGER  Max results to show  [default: 20]
  
  # apm mcp search --help
  --limit INTEGER  Number of results to show  [default: 10]
  

• Suggested Fix: Use identical description text, e.g. "Maximum results to show", for --limit across both commands. Explicitly document if the different defaults are intentional.

---

Clean Areas

The following commands passed all checks with no issues found:

• apm init -- consistent flags, clear description
• apm install -- comprehensive, well-structured help with full target list
• apm uninstall -- concise and accurate
• apm run / apm preview -- minimal, accurate
• apm deps list / apm deps tree / apm deps info / apm deps why -- accurate and consistent
• apm deps clean -- accurate (excluding shared --dry-run wording issue above)
• apm mcp search / apm mcp show -- accurate (excluding shared --limit note above)
• apm config set / apm config get / apm config unset -- accurate, well documented
• apm runtime setup / apm runtime list / apm runtime remove / apm runtime status -- consistent
• apm audit -- comprehensive and well-structured
• apm cache info / apm cache prune -- clear and accurate
• apm lock -- accurate
• apm outdated -- accurate (excluding flag naming issue above)
• All apm marketplace subcommands -- consistent and well-structured
• apm policy status -- clear and accurate
• apm plugin init -- concise and consistent
• apm experimental group -- consistent across all four subcommands
• apm self-update -- accurate
• apm view / apm find / apm list -- accurate
• apm pack / apm publish -- comprehensive
• apm targets -- accurate
• apm unpack -- correctly marked as deprecated
• Error handling -- all tested commands (apm install --nonexistent-flag, apm deps info (no args), apm config set (no args), apm uninstall (no args)) produce clean, non-traceback error messages with usage hints
• Documentation cross-reference -- all 30 top-level CLI commands (except doctor) have corresponding reference pages; no docs reference commands that do not exist in the CLI

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 4.5M · ◷

• expires on Jun 14, 2026, 2:15 PM UTC