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

[github-actions]

CLI Consistency Report

Date: 2026-06-22
APM Version: 0.21.0 (a9a883b)
Commands Inspected: 74

Summary

Severity	Count
High	2
Medium	6
Low	3
Total	11

---

High Severity

deny command has no CLI reference documentation page

• Command: apm deny
• Problem: apm deny is a fully implemented command (apm deny --help works, it revokes executable approval), but docs/src/content/docs/reference/cli/ has no deny.md page. Every other top-level command has a corresponding reference page.
• Evidence:

  $ apm deny --help
  Usage: apm deny [OPTIONS] PACKAGES...
  
    Revoke executable approval for packages.
  
    Removes entries from the ``allowExecutables`` block in ``apm.yml``.
  
    Example:
  
        apm deny owner/repo
  
  Options:
    --help  Show this message and exit.
  

  ls docs/src/content/docs/reference/cli/ contains no deny.md.
• Suggested Fix: Create docs/src/content/docs/reference/cli/deny.md covering synopsis, description, options, examples, and relationship to apm approve.

---

doctor command has no CLI reference documentation page

• Command: apm doctor
• Problem: apm doctor is a fully implemented diagnostic command, but docs/src/content/docs/reference/cli/ has no doctor.md page. It is also absent from the reference index command table.
• Evidence:

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

  ls docs/src/content/docs/reference/cli/ contains no doctor.md.
• Suggested Fix: Create docs/src/content/docs/reference/cli/doctor.md covering what diagnostics are run, exit codes, and usage in CI/onboarding flows.

---

Medium Severity

apm cache clean: --force and --yes have identical descriptions

• Command: apm cache clean
• Problem: Two distinct flags (-f/--force and -y/--yes) share the exact same description: "Skip confirmation prompt". --force conventionally means "overwrite/ignore collision" (as it does in apm install, apm update, apm pack). Having it mean "skip confirmation" here is semantically inconsistent with every other use of --force in the CLI and may confuse users.
• Evidence:

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

  Contrast with apm install --force: "Overwrite locally-authored files on collision".
• Suggested Fix: Remove -f/--force from apm cache clean (or change its description to match --yes). Standardize on -y/--yes for "skip confirmation" across all commands.

---

apm install --runtime help text is stale: lists vscode but not --target-compatible values

• Command: apm install --runtime
• Problem: --runtime is a legacy alias for --target, but its help text lists vscode as a valid value while --target does not list vscode. Additionally, --runtime omits agent-skills and all which --target supports. This creates confusion about what values each flag accepts.
• Evidence:

  $ apm install --help
  --runtime TEXT    Target specific runtime only (copilot, claude, codex,
                    cursor, gemini, antigravity, intellij, kiro, opencode,
                    vscode, windsurf)
  
  -t, --target TARGET   ...Values: copilot, claude, cursor, opencode, codex,
                    gemini, antigravity, windsurf, kiro, intellij, agent-
                    skills, all...
  

  vscode appears in --runtime but not --target. agent-skills and all appear in --target but not --runtime.
  The compile.md docs note: "vscode and agents are accepted as deprecated aliases for copilot".
• Suggested Fix: Update --runtime help text to note it is a deprecated legacy alias for --target and either list the same values as --target (noting deprecated aliases) or simply redirect users to --target.

---

apm install --runtime has no deprecation notice in help text

• Command: apm install --runtime
• Problem: The CLI reference docs (docs/src/content/docs/reference/cli/install.md) describe --runtime as "Legacy alias for --target (single value only). Still accepted; prefer --target." However, the CLI help text contains no deprecation marker, so users do not see any indication that the flag is legacy.
• Evidence:

  # CLI help shows no deprecation notice:
  --runtime TEXT    Target specific runtime only (copilot, claude, codex, ...)
  
  # Docs say (install.md):
  "--runtime VALUE | Legacy alias for `--target` (single value only). Still accepted;
   prefer `--target`."
  

• Suggested Fix: Add "(deprecated: use --target)" to the --runtime help string, consistent with how apm install --update is annotated: "deprecated: prefer 'apm update'...".

---

apm compile --no-dedup / --no-force-instructions double-negative flag naming

• Command: apm compile
• Problem: The flag is displayed as --no-dedup / --no-force-instructions. The description says "Include the instructions section in CLAUDE.md..." (the positive action), but the primary flag name --no-dedup uses a "no" prefix meaning "disable deduplication = include instructions". The complementary flag --no-force-instructions is also prefixed with "no". Both options in the pair use "no", making it hard to remember which enables the behavior.
• Evidence:

  $ apm compile --help
    --no-dedup / --no-force-instructions
                          Include the instructions section in CLAUDE.md even
                          when .claude/rules/ is already populated. Overrides
                          the default deduplication...
                          Alias: --force-instructions.
  

  Users must mentally parse "no-dedup = force include instructions" vs "no-force-instructions = keep dedup (default)". The alias --force-instructions is clearer but is only mentioned at the end of the description.
• Suggested Fix: Rename the primary flag to --force-instructions (the alias is already clearer), making the pair --force-instructions / --no-force-instructions. Drop --no-dedup as the primary name (keep as an alias if backward compatibility is needed).

---

Reference index command table is missing 8 commands

• Command: docs/src/content/docs/reference/index.md

• Problem: The phase-based command reference table omits 8 commands that exist in the CLI and each have their own docs pages.

• Evidence:
  The table in reference/index.md covers: init, install, update, uninstall, view, deps, outdated, list, audit, compile, prune, targets, runtime, cache, config, run, pack, unpack, preview, marketplace, search, policy, mcp, experimental.

  Missing from the table (but present in CLI and with docs pages):

  • approve (approve.md exists)
  • deny (no docs page -- separate issue above)
  • doctor (no docs page -- separate issue above)
  • find (find.md exists)
  • lock (lock.md exists)
  • plugin (plugin.md exists)
  • publish (publish.md exists)
  • self-update (self-update.md exists)

• Suggested Fix: Add all 8 missing commands to the reference index table under appropriate phases (e.g., approve/deny under Governance; doctor/self-update under a new "Maintenance" phase; find/lock under Inspect and audit; plugin/publish under Author and distribute).

---

apm config --help does not mention the no-subcommand config display behavior

• Command: apm config
• Problem: Running apm config with no subcommand displays a useful merged project+global configuration table. This behavior is documented in docs/src/content/docs/reference/cli/config.md but is completely absent from the CLI --help text. Users relying only on --help will not discover it.
• Evidence:

  $ apm config --help
  Usage: apm config [OPTIONS] COMMAND [ARGS]...
  
    Configure APM CLI
  
  Options:
    --help  Show this message and exit.
  
  Commands:
    get    Get a configuration value
    set    Set a configuration value
    unset  Unset a configuration value
  

  No mention of bare apm config showing the table. Contrast with actual behavior:

  $ apm config
  Current APM Configuration
  +----------+------------------+--------------------------+
  | Category | Setting          | Value                    |
  +----------+------------------+--------------------------+
  | Project  | Name             | apm                      |
  | ...
  

• Suggested Fix: Add a note to the apm config group description, e.g.: "With no subcommand, prints the merged project + global configuration table."

---

Low Severity

apm mcp list and apm mcp search have inconsistent --limit defaults

• Commands: apm mcp list, apm mcp search
• Problem: Both commands expose a --limit flag for the same conceptual purpose (cap the number of results), but default to different values: list defaults to 20, search defaults to 10.
• Evidence:

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

• Suggested Fix: Align both to the same default (20 seems reasonable for both). The docs (mcp.md) correctly reflect the current values, so update whichever command is changed.

---

apm targets --help shows COMMAND [ARGS]... in usage with no listed subcommands

• Command: apm targets
• Problem: The usage line reads apm targets [OPTIONS] COMMAND [ARGS]... suggesting subcommands exist, but no Commands: section appears in the help. CLI-only users have no way to discover this is intentional (future subcommands are reserved). The targets.md docs explain it clearly, but the help text does not.
• Evidence:

  $ apm targets --help
  Usage: apm targets [OPTIONS] COMMAND [ARGS]...
  
    Show resolved targets for the current project...
  
  Options:
    --json  Output as JSON instead of a table.
    --all   Include the agent-skills meta-target in JSON output...
    --help  Show this message and exit.
  

  No Commands: section shown. The targets.md docs note: "no subcommands ship today... reserved for future use."
• Suggested Fix: Add a note to the help text such as "(subcommands reserved for future use)" or restructure apm targets as a plain command (not a group) until subcommands are implemented.

---

apm deps update is listed in apm deps --help without a visible deprecation marker

• Command: apm deps update
• Problem: apm deps update is deprecated in favor of apm update, which the docs note prominently. However, the apm deps --help output lists update with the plain description "Update APM dependencies to latest refs" -- no deprecation signal. Users must run apm deps update --help to see the deprecation caution block in the detailed docs.
• Evidence:

  $ apm deps --help
  Commands:
    clean   Remove all APM dependencies
    info    Show detailed package information
    list    List installed APM dependencies
    tree    Show dependency tree structure
    update  Update APM dependencies to latest refs   <-- no deprecated marker
    why     Explain why a package is installed...
  

  Compare with apm install --update: "Update dependencies to latest Git references (deprecated: prefer 'apm update'...)" -- which clearly labels the deprecation inline.
• Suggested Fix: Prefix the apm deps update description with "(deprecated: use 'apm update' instead)" to match the inline deprecation pattern used by apm install --update.

---

Clean Areas

The following commands/areas passed all checks with no issues found:

• apm init -- clear help, consistent -v/--verbose, -y/--yes flags
• apm install (core behavior) -- comprehensive flag documentation, good error messages for missing args
• apm uninstall -- consistent flags, sensible error handling
• apm update -- consistent deprecation labeling of --update
• apm compile (except --no-dedup) -- thorough option docs
• apm run / apm preview -- symmetric, consistent flag set
• apm deps list/tree/info/clean/why -- clear descriptions, correct required-arg error messages
• apm mcp search/show/install -- well-documented, consistent verbose flag
• apm config get/set/unset -- correct behavior, good validation error messages
• apm runtime setup/list/remove/status -- consistent, complete help
• apm audit -- exceptionally thorough flag documentation
• apm cache info/prune -- clean, minimal, clear
• apm marketplace (all subcommands) -- comprehensive and consistent
• apm experimental (all subcommands) -- clear flag behavior, good JSON flag
• apm lock / apm lock export -- dual command/group pattern works well
• apm approve -- clear with good examples in help
• apm outdated -- concise and correct
• apm pack -- very detailed, good exit code documentation
• apm publish -- clear experimental gating
• apm search -- minimal and correct
• apm self-update -- clear check-only mode
• apm find -- good exit code behavior
• apm list -- simple, correct
• apm plugin init -- consistent with apm init
• apm policy status -- thorough output format options
• apm prune -- consistent --dry-run usage
• apm view -- clear field documentation
• apm unpack -- clear deprecation notice inline
• Error handling -- All tested commands (apm install --nonexistent-flag, apm deps info, apm config set, apm mcp show) produce clean "Missing argument" / "No such option" messages with usage hints. No stack traces observed.

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

• expires on Jun 24, 2026, 3:12 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-06-24T15:12:35.186Z.

Closed by Workflow