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

[github-actions]

CLI Consistency Report

Date: 2026-06-23
APM Version: 0.21.0 (a9a883b)
Commands Inspected: 49 (32 top-level + 17 subcommands, including one non-existent command)

Summary

Severity	Count
High	0
Medium	6
Low	4

---

Medium Severity

1. apm compile --target all deprecation note is in the wrong command's help text

• Command: apm install --help
• Problem: The deprecation notice for --target all on apm compile is embedded inside the apm install --target description, not in apm compile --help. Users running apm compile --target all will not see any deprecation warning from apm compile --help.
• Evidence: apm install --help --target section ends with:

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

  apm compile --help shows --all as "Compile for all canonical targets. Equivalent to --target all." with no deprecation note about --target all being deprecated.
• Suggested Fix: Move the deprecation note to apm compile --target (or apm compile --all) description. Remove it from apm install --target. Alternatively, add a runtime warning when apm compile --target all is invoked.

---

2. apm deps update --help does not show deprecation notice

• Command: apm deps update --help
• Problem: The docs (reference/cli/deps.md) explicitly mark apm deps update as deprecated in favor of apm update. The runtime does emit a deprecation warning when invoked. However, the --help text contains no deprecation indicator.
• Evidence:
  • apm deps update --help output:

    Usage: apm deps update [OPTIONS] [PACKAGES]...
    
      Update APM dependencies to latest refs
    
    Options:
    ...
    

    No deprecation mentioned.
  • Runtime output: [!] 'apm deps update' is deprecated; use 'apm update' instead.
  • deps.md: contains a caution admonition explicitly calling it deprecated.
• Suggested Fix: Add [DEPRECATED: use 'apm update' instead] to the command description string so it appears in --help output, not just at runtime.

---

3. apm mcp install --help has non-standard, unformatted options block

• Command: apm mcp install --help
• Problem: The help text shows only --help as a registered option, then appends an unformatted prose block titled "Common options" within the Options section. These options are NOT registered Click options -- they are forwarded to apm install --mcp at runtime. The display is inconsistent with every other command's help and misleads users about which flags are parsed at which level. Additionally, placing flags before the NAME positional argument yields a confusing error: "MCP name cannot start with '-'; did you forget a value for --mcp?" when Click treats unrecognized pre-positional options as the NAME argument.
• 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
  

  Every other command (e.g., apm install, apm update, apm compile) uses standard Click option formatting.
• Suggested Fix: Either register the forwarded options as proper Click params on apm mcp install, or move the prose note to the command description (not the Options section) and use standard formatting (e.g., a \b epilog block).

---

4. apm update --target description is truncated compared to related commands

• Command: apm update --help
• Problem: The --target flag for apm update gives a short description with example values but does not list all supported targets (copilot, claude, cursor, opencode, codex, gemini, antigravity, windsurf, kiro, agent-skills, all) and omits the copilot-cowork experimental target that appears in the equivalent flags for apm install and apm deps update.
• Evidence:
  • apm update --target: "Agent target(s) to update for (e.g. claude, copilot, cursor, windsurf, kiro, codex, opencode, gemini). Comma-separated for multiple: --target claude,cursor."
  • apm install --target: full enumeration of all targets, antigravity, agent-skills, all, and copilot-cowork experimental note.
  • apm deps update --target: same full enumeration as apm install.
• Suggested Fix: Align apm update --target description with apm install --target to include the full target list and the copilot-cowork experimental note. Similarly, ensure apm compile --target also includes the copilot-cowork note (currently absent).

---

5. apm doctor has no dedicated CLI reference page

• Command: apm doctor
• Problem: apm doctor is a top-level command (apm --help lists it; it runs and works correctly), but it has no dedicated page under docs/src/content/docs/reference/cli/ and is absent from the reference index table in docs/src/content/docs/reference/index.md. It is only mentioned incidentally in guide pages.
• Evidence:
  • apm doctor --help works: "Run environment diagnostics (git, network, auth, gh CLI, marketplace config). Reports a pass/fail table and exits non-zero if a critical check fails."
  • ls docs/src/content/docs/reference/cli/ -- no doctor.md
  • docs/src/content/docs/reference/index.md CLI table has no doctor row.
• Suggested Fix: Create docs/src/content/docs/reference/cli/doctor.md and add a doctor entry to the reference index table (e.g., under "Inspect and audit" alongside audit).

---

6. Reference index table omits 7 commands that have dedicated doc pages

• Command: docs/src/content/docs/reference/index.md
• Problem: The CLI commands table in the reference index lists a subset of commands, leaving out 7 commands that each have their own dedicated reference page.
• Evidence: The following commands have pages under reference/cli/ but are absent from the index table:
  • approve / deny -- covered in approve.md
  • find -- find.md
  • lock -- lock.md
  • pack -- pack.md
  • plugin -- plugin.md
  • publish -- publish.md
  • self-update -- self-update.md
• Suggested Fix: Add the missing commands to the reference index table under appropriate phase categories (e.g., approve/deny under Governance; find under Inspect and audit; lock under Project setup; pack/publish/plugin under Author and distribute; self-update under Cache and config).

---

Low Severity

7. --verbose / -v flag descriptions are inconsistent across commands

• Commands: Multiple
• Problem: The description for the -v, --verbose flag varies significantly across commands with no clear pattern.
• Evidence:
  • apm init: "Show detailed output"
  • apm install: "Show detailed installation information"
  • apm uninstall: "Show detailed removal information"
  • apm update: "Show unchanged deps and detailed pipeline diagnostics"
  • apm compile: "Show detailed source attribution and optimizer analysis"
  • apm run, apm mcp search, apm mcp show: "Show detailed output"
  • apm deps update: "Show detailed update information"
• Suggested Fix: Adopt a consistent base pattern. Command-specific additions are fine ("Show detailed output" as base; add context where it adds value). Standardize at minimum the base wording.

---

8. apm deps list has no --verbose flag while peer deps subcommands do

• Command: apm deps list
• Problem: apm deps list --help shows no -v, --verbose flag, while apm deps update and apm deps why both support --verbose. For a listing command, verbose output (e.g., showing source URLs or primitive counts) would be expected.
• Evidence: apm deps list --help options: -g, --global, --all, --insecure, --help. No verbose flag.
• Suggested Fix: Add -v, --verbose to apm deps list to show additional detail (source URL, primitive type breakdown), or document in the help text that --insecure adds the Origin column as the available detail level.

---

9. apm outdated --parallel-checks uses non-standard default format and inconsistent short flag

• Command: apm outdated --help
• Problem: The parallel flag uses (default: 4, 0 = sequential) inline in the description rather than Click's standard [default: 4] display. The short flag -j is also inconsistent -- all other parallel flags (e.g., apm install --parallel-downloads, apm update --parallel-downloads) have no short flag. The flag name itself (--parallel-checks) differs from --parallel-downloads used elsewhere.
• Evidence:
  • apm outdated: -j, --parallel-checks INTEGER Max concurrent remote checks (default: 4, 0 = sequential)
  • apm install: --parallel-downloads INTEGER Max concurrent package downloads (0 to disable parallelism) [default: 4]
  • apm update: --parallel-downloads INTEGER Max concurrent package downloads (0 to disable parallelism) [default: 4]
• Suggested Fix: Rename to --parallel-checks -> keep or align to --parallel-downloads style, remove -j short flag for consistency, and use Click's default=4 parameter so the standard [default: 4] appears in help.

---

10. apm audit help description is too narrow for its actual scope

• Command: apm audit --help
• Problem: The one-line description "Scan installed packages for hidden Unicode characters" understates the command's scope. apm audit also performs drift detection, lockfile integrity CI checks, and policy enforcement -- all shown in the extensive options list.
• Evidence: apm audit --help description vs. options including --ci (lockfile CI gates), --no-drift (install-replay drift check), --policy (policy enforcement), and --external (SARIF scanner ingestion).
• Suggested Fix: Expand the description to something like: "Scan for hidden Unicode characters, detect install drift, and run lockfile integrity checks for CI gates." This avoids documenting the full feature set in the one-liner while still representing the command's breadth.

---

Clean Areas

The following commands and areas passed all checks:

• Core install/uninstall lifecycle: apm install, apm uninstall, apm update -- flags are well-described and consistent with docs.
• apm compile: Comprehensive help text with clear flag descriptions; --all alias is properly documented.
• apm deps subcommands (list, tree, info, clean, why): Help text matches docs.
• apm mcp search/show/list: Consistent format, defaults match docs (list --limit defaults to 20, search --limit defaults to 10).
• apm config subcommands (get, set, unset): Match docs precisely; apm config (bare) renders project+global config table correctly.
• apm runtime subcommands (setup, list, status): Clean, minimal, accurate.
• apm init: Deprecated --plugin and --marketplace flags are properly labeled with redirects.
• apm unpack: Deprecated properly labeled with [Deprecated] prefix and redirect message.
• apm run: Simple and consistent with docs.
• apm lock: Comprehensive options, export subcommand present and accessible.
• apm doctor: Functional with --verbose flag; runtime diagnostics work correctly.
• Error handling: All tested invalid inputs (--nonexistent-flag, missing required args) return clean error messages with usage hints -- no stack traces.
• --help / -h: Works on every tested command and subcommand.
• --dry-run: Present and consistently described on all commands where applicable (install, update, compile, deps clean, audit, publish, unpack).

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

• expires on Jun 25, 2026, 2:03 PM UTC