[cli-consistency] CLI Consistency Report -- 2026-07-15

[github-actions]

CLI Consistency Report

Date: 2026-07-15
APM Version: 0.25.0 (defafe3)
Commands Inspected: 56 (all top-level commands plus all documented subcommands)

Summary

Severity	Count
High	0
Medium	3
Low	3

---

Medium Severity

apm pack: Multi-line examples section garbled in help output

• Command: apm pack
• Problem: The Examples: block and Exit codes: block in _PACK_HELP are reflowed by Click into single run-on lines, making them unreadable. Click merges adjacent lines in a paragraph unless they are preceded by \b (form-feed). The source (pack.py lines 36-59) has correct multi-line formatting, but the rendered output collapses it.
• Evidence (rendered terminal output with COLUMNS=200):

    Examples:
  
      # Bundle only (most common -- just dependencies: in apm.yml):   apm pack
      # Claude Code plugin (default)   apm pack --target claude --archive   apm
      pack --format apm -o ./dist       # Legacy APM bundle layout
  
      # Marketplace only (marketplace: in apm.yml, no dependencies:):   apm pack
      apm pack --offline --dry-run
  
    Exit codes:   0  Success   1  Build or runtime error   2  Manifest schema
    validation error   3  Version alignment check failed (--check-versions)   4
    Marketplace working-tree drift detected (--check-clean)
  

• Suggested Fix: Prefix each block that should not be reflowed with \b\n (Click's no-reformat sentinel). For example:

  Examples:
  \b
    # Bundle only (most common -- just dependencies: in apm.yml):
    apm pack

  Apply the same fix to the "Exit codes:" block and the "Reads apm.yml to decide what to produce:" bullet list.

---

apm publish: Multi-line examples garbled and RST backticks visible in terminal

• Command: apm publish
• Problem: Same Click paragraph-reflow issue as apm pack -- the Examples: section in _PUBLISH_HELP (publish.py lines 34-47) collapses into run-on lines. Additionally, the description body uses RST-style double backticks ( apm.yml , .apm/ ) that render literally in the terminal instead of as code.
• Evidence (terminal output):

    Reads apm.yml for the package name/version, packs a flat registry zip
    archive (``apm.yml`` + ``.apm/`` at the archive root -- not ``apm pack``
    plugin bundles), or uses a pre-built zip via --zip, then uploads to the
    registry via PUT /v1/packages/{owner}/{repo}/versions/{version}.
  
    Requires the 'registries' experimental feature:   apm experimental enable
    registries
  
    Examples:
  
      # Auto-pack and publish to the only configured registry:   apm publish
      --package acme/my-skill
  

• Suggested Fix: (1) Replace `` RST backticks with single backticks or plain text since Click does not render RST. (2) Protect the Examples: section with \b\n same as apm pack fix above.

---

apm cache clean: -f/--force and -y/--yes both described as "Skip confirmation prompt"

• Command: apm cache clean
• Problem: The command exposes two flags that do the same thing (-f/--force and -y/--yes) with identical help text. Everywhere else in the APM CLI, --force means "overwrite locally-authored files on collision" (install, uninstall, update, compile, pack). Using --force to skip a confirmation prompt in cache clean is semantically inconsistent with the rest of the CLI. A user who reads --force will expect file-overwrite semantics, not "skip confirmation".
• Evidence (apm cache clean --help):

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

  Compare apm deps clean --help (the analogous clean command for the same workflow):

  Options:
    --dry-run  Show what would be removed without removing
    -y, --yes  Skip confirmation prompt
    --help     Show this message and exit.
  

• Suggested Fix: Remove -f/--force from apm cache clean. Keep only -y/--yes to be consistent with apm deps clean and the rest of the CLI. If backward compatibility requires keeping --force, at minimum update the help text to say "Alias for --yes; skip confirmation prompt" to flag it as non-standard.

---

Low Severity

apm targets usage line advertises [COMMAND] [ARGS]... but has no subcommands

• Command: apm targets
• Problem: The usage line reads Usage: apm targets [OPTIONS] [COMMAND] [ARGS]... implying users can run subcommands, but no subcommands are listed and none exist. The code comment in targets.py acknowledges this is a click.group reserved for future subcommands, but it creates a confusing experience for users who see the [COMMAND] placeholder.
• 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 follows -- the placeholder [COMMAND] has no corresponding entries.
• Suggested Fix: Either (a) add invoke_without_command=True and note in the description that subcommands are coming, or (b) keep the current group structure but suppress the [COMMAND] [ARGS]... from the usage line via context_settings={"max_content_width": ...} or a custom formatter. The simplest short-term fix is to add a one-line note: "No subcommands yet; run apm targets to print the table."

---

apm deps update and apm unpack use inconsistent deprecation styles

• Command: apm deps update, apm unpack
• Problem: The two deprecated commands use different visual formats for their deprecation notice. apm deps update embeds the deprecation as a prefix in the description text (DEPRECATED: use 'apm update'...), while apm unpack wraps it in square brackets at the start ([Deprecated] Extract an APM bundle...). This inconsistency makes deprecations harder to scan.
• Evidence:

  # apm deps --help (Commands section):
  update  DEPRECATED: use 'apm update' instead (strict superset).
  
  # apm uninstall --help is clean; compare apm unpack --help:
  [Deprecated] Extract an APM bundle into the current project.
  

• Suggested Fix: Adopt a single style. The square-bracket prefix [Deprecated] used by apm unpack is more consistent with standard CLI conventions and scans better in the command list. Update apm deps update to match.

---

apm run description adds "(experimental)" in apm --help listing but not in its own help header

• Command: apm run
• Problem: In the top-level apm --help command listing, run appears as "Run a script with parameters (experimental)". But apm run --help prints "Run a script with parameters (experimental)" (this is consistent). Small note: the apm runtime --help synopsis also says "(experimental)", so the labeling is consistent -- this is a very minor observation.
• Evidence: Both apm --help and apm run --help say "(experimental)" -- no real inconsistency found; listing for completeness.
• Suggested Fix: No change needed; this passes on closer inspection.

---

Clean Areas

• All 33 top-level commands exist in the CLI and have corresponding documentation pages under docs/src/content/docs/reference/cli/. No undocumented commands found; no documented commands missing from the CLI.
• --help / -h: Works on every command and subcommand tested (56 total). No crashes or stack traces.
• --verbose / -v: Present and consistent across all commands that support it.
• --dry-run: Present and consistently named across all commands that support it (install, compile, update, uninstall, deps clean, audit, pack, prune, unpack, publish).
• --yes / -y: Consistent across deps clean, runtime remove, update, cache clean.
• Error handling: apm install --nonexistent-flag, apm deps info (no arg), apm config set (no args) all produce clean usage errors -- no stack traces.
• apm deps subcommands: list, tree, info, clean, update, why -- all present and documented.
• apm mcp subcommands: list, search, show, install -- all present and documented.
• apm config subcommands: get, set, list, unset -- all present and documented.
• apm runtime subcommands: list, setup, remove, status -- all present and documented.

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 · 114 AIC · ⌖ 7.01 AIC · ⊞ 6.6K · ◷

• expires on Jul 17, 2026, 1:45 PM UTC