[cli-consistency] CLI Consistency Report — 2026-04-27

[github-actions]

CLI Consistency Report

Date: 2026-04-27
APM Version: 0.9.4 (2153872)
Commands Inspected: 50 (top-level + all subcommands)

Summary

Severity	Count
High	1
Medium	4
Low	3

---

High Severity

apm policy status docs reference a non-existent apm install --policy flag

• Command: apm policy status
• Problem: The docs say the --policy-source option is "Same shape as apm install --policy", but apm install has no --policy flag. The install command only has --no-policy. This broken cross-reference misleads users trying to understand the policy source format.
• Evidence:
  • Docs (docs/src/content/docs/reference/cli-commands.md, line 523):

    --policy-source SOURCE - Override discovery: org, file path, or URL. Same shape as apm install --policy.

  • Actual apm install --help output: includes --no-policy and --registry, but no --policy flag.
  • apm audit --help: confirms --policy TEXT exists on audit, not install.
• Suggested Fix: Change the cross-reference in the docs from apm install --policy to apm audit --policy.

---

Medium Severity

apm run is labeled Experimental in docs but not in CLI

• Command: apm run
• Problem: The CLI reference docs section is titled ### apm run (Experimental) - Execute prompts, but the actual apm run --help output gives no indication the command is experimental.
• Evidence:
  • Docs heading (line 1284): ### apm run (Experimental) - Execute prompts
  • CLI output: Usage: apm run [OPTIONS] [SCRIPT_NAME] / Run a script with parameters
• Suggested Fix: Either add an (Experimental) or [experimental] note to the CLI help text (e.g., in the docstring or epilog), or remove the (Experimental) label from the docs if the command is now stable.

---

apm runtime is labeled Experimental in docs but not in CLI

• Command: apm runtime
• Problem: The docs section is titled ## Runtime Management (Experimental) and ### apm runtime (Experimental) - Manage AI runtimes, but apm runtime --help shows only Manage AI runtimes with no experimental indication.
• Evidence:
  • Docs (line 1671): ## Runtime Management (Experimental)
  • Docs (line 1673): ### apm runtime (Experimental) - Manage AI runtimes
  • CLI output: Manage AI runtimes (no experimental marker)
• Suggested Fix: Align the CLI help text with the docs by adding an experimental note (e.g., epilog text), or remove the label from docs if the feature is stable.

---

apm deps info has inconsistent description between CLI and docs

• Command: apm deps info
• Problem: The CLI help says "Show detailed package information", but the docs say it is a "Backward-compatible alias for apm view PACKAGE_NAME." The docs also say "Use apm view in new docs and scripts." A user reading the CLI help would not know this is a deprecated alias.
• Evidence:
  • CLI output: Usage: apm deps info [OPTIONS] PACKAGE / Show detailed package information
  • Docs (line 898): #### apm deps info - Alias for apm view / Backward-compatible alias for apm view PACKAGE_NAME. / Use apm view in new docs and scripts.
• Suggested Fix: Update the CLI help text for apm deps info to mention it is an alias for apm view and that apm view should be preferred, e.g.: Show package information (alias for 'apm view'; prefer 'apm view' in new scripts).

---

apm update docs show non-ASCII emoji in example CLI output

• Command: apm update
• Problem: The docs show a code block with ⚠️ A new version of APM is available... as example CLI output. However, the actual source (src/apm_cli/commands/_helpers.py) uses _rich_warning() which emits ASCII bracket notation ([!]). The docs show inaccurate output, and the emoji violates the project's cross-platform encoding rule (printable ASCII only).
• Evidence:
  • Docs (lines 696-701):

    ⚠️  A new version of APM is available: 0.7.0 (current: 0.6.3)
    Run apm update to upgrade
    

  • Source (src/apm_cli/commands/_helpers.py, line ~275): calls _rich_warning(...) with symbol="warning" which renders as [!]
• Suggested Fix: Replace the emoji example in docs with the actual ASCII output:

  [!] A new version of APM is available: 0.7.0 (current: 0.6.3)
  Run apm update to upgrade
  

---

Low Severity

apm config --help doesn't document the default "show config" behavior

• Command: apm config
• Problem: Running apm config without a subcommand displays a configuration table (current project + global settings), but the --help output gives no hint of this behavior. Users reading the help would not discover this useful feature.
• Evidence:
  • apm config --help shows only: Configure APM CLI and lists three subcommands (get, set, unset)
  • Docs (line 1534): Running apm config without subcommands displays the current configuration.
  • Actual behavior: apm config (no args) renders a Rich table of project and global settings.
• Suggested Fix: Add an epilog to the apm config command noting the default behavior, e.g.: Run without a subcommand to display the current configuration.

---

apm mcp list docs omit the -v, --verbose option

• Command: apm mcp list
• Problem: The docs list only --limit INTEGER as an option, but the CLI also exposes -v, --verbose.
• Evidence:
  • CLI output: --limit INTEGER Number of results to show [default: 20] AND -v, --verbose Show detailed output
  • Docs (line 1038 section): only documents --limit INTEGER - Number of results to show (default: 20) — no mention of --verbose.
• Suggested Fix: Add - \-v, --verbose` - Show detailed outputto theapm mcp list` options in the docs.

---

apm deps update --force description omits the security-findings context

• Command: apm deps update
• Problem: The --force flag description says "Overwrite locally-authored files on collision", while apm install --force (which deps update wraps internally) says "Overwrite locally-authored files on collision and deploy despite critical security findings". The deps update version is shorter and omits the security implication, which could lead users to underestimate the flag's impact.
• Evidence:
  • apm deps update --help: --force Overwrite locally-authored files on collision
  • apm install --help: --force Overwrite locally-authored files on collision and deploy despite critical security findings
• Suggested Fix: Update apm deps update --force description to match apm install --force: Overwrite locally-authored files on collision and deploy despite critical security findings.

---

Clean Areas

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

• apm init — help text, options, and docs are consistent
• apm install — comprehensive options, consistent descriptions, well-documented
• apm uninstall — consistent with install for shared flags
• apm compile — all options match docs
• apm audit — all options and docs are consistent
• apm prune — minimal but correct
• apm pack / apm unpack — consistent flags, docs match CLI
• apm outdated — well-documented with examples
• apm view — docs and CLI aligned
• apm search — consistent
• apm deps list / apm deps tree / apm deps clean / apm deps update — mostly consistent (minor --force note above)
• apm mcp search / apm mcp show / apm mcp install — functional and consistent with docs
• apm marketplace (all 6 subcommands) — consistent options and docs
• apm config set / apm config get / apm config unset — correct
• apm runtime setup / apm runtime list / apm runtime remove / apm runtime status — consistent
• apm policy status — options correct (doc cross-ref issue flagged separately)
• apm experimental (all 4 subcommands) — consistent
• apm run / apm preview / apm list — functional and consistent internally
• Exit behavior: all commands with missing required args produce clean error messages (no stack traces)
• Invalid flags: apm install --nonexistent-flag produces a clean "No such option" error

Warning

⚠️ Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• astral.sh

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "astral.sh"

See Network Configuration for more information.

Generated by CLI Consistency Checker · ● 1.5M · ◷

• expires on Apr 29, 2026, 1:38 PM UTC