[cli-consistency] CLI Consistency Report — 2026-06-30

[github-actions]

CLI Consistency Report

Date: 2026-06-30
APM Version: 0.23.1 (d1d926d)
Commands Inspected: 43 (23 task-required + 20 additional)

Summary

Severity	Count
High	1
Medium	4
Low	1

---

High Severity

apm doctor has no dedicated CLI reference page

• Command: apm doctor
• Problem: apm doctor is a fully implemented, user-facing diagnostic command with --verbose support, but it has no dedicated page under docs/src/content/docs/reference/cli/. Every other top-level command has a reference page; doctor is the only exception. The command is referenced in guides (operating-installed-context.md, security.md, publish-to-a-marketplace.md) and in the approve.md page, meaning users following those cross-links have no reference target.
• 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/ returns no doctor.md.
• Suggested Fix: Create docs/src/content/docs/reference/cli/doctor.md documenting the command, its --verbose flag, exit codes, and the checks it runs (git, network, auth, gh CLI, marketplace config).

---

Medium Severity

Reference index table omits many existing commands

• Command: docs/src/content/docs/reference/index.md
• Problem: The CLI commands table in the reference index is missing the following commands that all exist in the CLI and have dedicated doc pages: approve/deny, find, lifecycle, lock, plugin, publish, self-update. A user browsing the reference index will not discover these commands.
• Evidence:
  The table in reference/index.md lists phases and commands, but these commands with their existing .md files are absent from every row:
  • approve.md (covers both apm approve and apm deny)
  • find.md
  • lifecycle.md
  • lock.md
  • plugin.md
  • publish.md
  • self-update.md
• Suggested Fix: Add the missing commands to the index table. Suggested groupings:
  • Project setup: add lock
  • Inspect and audit: add find
  • Author and distribute: add plugin, publish
  • Governance: add approve/deny, lifecycle
  • Utility: add self-update

README CLI Reference link uses wrong path

• Command: README.md line 9
• Problem: The README links to (microsoft.github.io/redacted) for the CLI Reference, but all actual CLI reference pages live under /reference/cli/(e.g.,/reference/cli/install/). The path cli-commands` does not appear anywhere in the docs source tree.
• Evidence:

  **[CLI Reference]((microsoft.github.io/redacted)
  

  Actual pages: docs/src/content/docs/reference/cli/install.md, docs/src/content/docs/reference/cli/config.md, etc. No cli-commands/ directory exists.
• Suggested Fix: Change the README link to (microsoft.github.io/redacted) (or the index page if one exists at /reference/cli/`).

--yes / -y flag description is inconsistent across commands

• Command: apm update, apm deps clean, apm init
• Problem: The -y, --yes flag has three different descriptions across commands that all use it for the same general purpose (skipping a confirmation prompt).
• Evidence:

  apm update:     -y, --yes   Skip the confirmation prompt (for CI / automation)
  apm deps clean: -y, --yes   Skip confirmation prompt
  apm init:       -y, --yes   Skip interactive prompts and use auto-detected defaults
  

  apm deps clean is missing "the" and the parenthetical. apm init uses completely different wording.
• Suggested Fix: Standardize to a consistent pattern. For example:
  • apm update / apm deps clean: Skip the confirmation prompt
  • apm init: Skip interactive prompts (use auto-detected defaults)

apm config get help does not describe its list-all behavior

• Command: apm config get
• Problem: Running apm config get with no argument prints all user-settable configuration keys and their effective values, but the help text gives no hint of this behavior. Users who want to see all config values might not discover this.
• Evidence:

  $ apm config get --help
  Usage: apm config get [OPTIONS] [KEY]
  
    Get a configuration value
  
  Options:
    --help  Show this message and exit.
  

  The description "Get a configuration value" does not mention the no-argument behavior. Compare with the docs (reference/cli/config.md): "With no argument, prints all user-settable keys with their effective values (defaults included)."
• Suggested Fix: Update the help string to: Get a configuration value (omit KEY to list all settable keys with effective values).

---

Low Severity

apm unpack deprecation notice lacks a replacement callout in top-level help

• Command: apm --help, apm unpack --help
• Problem: apm unpack is labeled [Deprecated] in the top-level command listing, which is good. However, the one-line summary in apm --help says only "[Deprecated] Extract an APM bundle..." without stating the replacement. Users unfamiliar with the tool may not see the replacement (apm install <bundle-path>) unless they read apm unpack --help.
• Evidence:

  $ apm --help
  ...
  unpack        [Deprecated] Extract an APM bundle into the current project.
  ...
  
  $ apm unpack --help
  ...
    [Deprecated] Extract an APM bundle into the current project. Use 'apm
    install <bundle-path>' instead -- this command will be removed in a future
    release.
  

• Suggested Fix: Minimal: append the replacement to the top-level summary line: [Deprecated] Use 'apm install <bundle-path>' instead.

---

Clean Areas

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

• Top-level flags: --version, --verbose / -v, --help all work correctly on every tested command and subcommand.
• Error handling: Invalid options, missing required arguments, and conflicting flags all produce clear, actionable error messages (no tracebacks observed).
• --dry-run flag: Present and consistently described on all destructive commands that support it (install, uninstall, update, compile, deps clean, prune, audit, publish).
• apm deps group: list, tree, info, clean, why all have correct help text matching the documentation.
• apm mcp group: list, search, show, install all have correct help text and default values matching the documentation (list default: 20, search default: 10).
• apm config: get, set, unset are accurately documented. No list subcommand exists or is documented.
• apm runtime: setup, list, status, remove all exist and match the documentation.
• apm install / apm update: Complex flag sets are accurately documented with defaults.
• Deprecation notices: apm deps update, apm init --plugin, apm init --marketplace, apm install --runtime, apm install --update all clearly state they are deprecated and provide the replacement.

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 · 130.5 AIC · ⌖ 10 AIC · ⊞ 6.6K · ◷

• expires on Jul 2, 2026, 1:42 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-07-02T13:42:47.300Z.

Closed by Workflow