[cli-consistency] CLI Consistency Report — 2026-09-17

CLI Consistency Report

Date: 2026-09-17
APM Version: Agent Package Manager (APM) CLI version 0.31.0 (b914b1b)
Commands Inspected: 32 top-level commands + 22 subcommand --help invocations (top-level --help, init, install, uninstall, update, compile, run, deps + 5 subcommands, mcp + 3 subcommands, config + 3 subcommands, runtime + 1 subcommand), plus spot-checks of list, view, cache, policy, marketplace.

Summary

Medium Severity

Documentation example shows wrong success-message symbol for apm init

• Command: apm init
• Problem: docs/src/content/docs/reference/cli/init.md shows the example output for a successful init using a [+] prefix on the success line, but the actual CLI emits [*] for this message (the success status maps to [*] in STATUS_SYMBOLS, not [+], which is reserved for check). Anyone copy-pasting the documented "expected output" to verify their install will see a mismatch.
• Evidence:
  Documented (init.md):

  $ apm init my-app --yes
  [*] Created project directory: my-app
  [+] APM project initialized successfully!
  Created Files
    * apm.yml  Project configuration
  

  Actual CLI output (verified by running apm init test_apm_proj2 --yes):

  [>] Created project directory: test_apm_proj2
  [>] Initializing APM project: test_apm_proj2
  [*] APM project initialized successfully!
      Created Files
  ┏━━━━━━┳━━━━━━━━━━━━━┓
  ┃ File ┃ Description ┃
  ┡━━━━━━╇━━━━━━━━━━━━━┩
  │ *    │ apm.yml     │
  └──────┴─────────────┘
  

  Note the doc also shows [*] Created project directory: while the actual symbol used there is [>] (running), and the success line is [*] not [+]. Source: src/apm_cli/utils/console.py STATUS_SYMBOLS maps "success": "[*]" and "check": "[+]"; commands/init.py calls logger.success(...) (i.e. [*]), not the [+] check symbol.
• Suggested Fix: Update the two example blocks in docs/src/content/docs/reference/cli/init.md (the plain init example and the --plugin example) to use [>] for the "Created project directory" line and [*] for the "APM project initialized successfully!" line, matching real output. Also drop the rich-table rendering discrepancy in the doc (the doc shows a plain "Created Files / * apm.yml Project configuration" list; actual output is a Rich box-drawn table without a "Description" value populated the same way) or note that Rich-table formatting varies by terminal — at minimum align the status symbols.

Low Severity

Inconsistent trailing-period usage in top-level command summaries (apm --help)

• Command: apm --help
• Problem: Some command one-line summaries in the top-level command list end with a period while most do not, with no discernible pattern (not simply "short vs. long" or "single vs multi-sentence").
• Evidence:

  config        Configure APM CLI.
  lifecycle     Inspect, test, and scaffold lifecycle scripts.
  pack          Pack distributable artifacts from your APM project.
  publish       Publish a package to a registry.
  self-update   Update the APM CLI binary itself to the latest version.
  targets       Show resolved targets for the current project.
  

  versus (no trailing period):

  cache         Manage the local package cache
  compile       Compile APM context into distributed AGENTS.md files
  deps          Manage APM package dependencies
  init          Initialize a new APM project
  list          List available scripts in the current project
  marketplace   Manage marketplaces for discovery and governance
  mcp           Discover, inspect, and install MCP servers
  outdated      Show outdated locked dependencies
  run           Run a script with parameters (experimental)
  runtime       Manage AI runtimes (experimental)
  update        Refresh APM dependencies to the latest matching refs
  view          View package metadata or list remote versions
  

• Suggested Fix: Standardize all top-level command help summaries (the Click help= / docstring first line for each command group) to omit the trailing period, matching the majority style already used across most commands (cache, compile, deps, init, etc.).

Clean Areas

• CLI installs and runs correctly; apm --version and apm --help work as expected.
• All 32 top-level commands documented under docs/src/content/docs/reference/cli/ have a matching CLI command and vice versa (verified via diff of sorted command lists) -- no orphaned docs or undocumented commands.
• apm deps, apm mcp, apm config, apm runtime subcommand trees and their flags match their respective doc pages (deps.md, mcp.md, config.md, runtime.md) exactly, including defaults (e.g. mcp search --limit default 10, mcp list --limit default 20).
• Error handling is consistent and sane: invalid flags (apm install --nonexistent-flag), missing required arguments (apm deps info, apm config set, apm mcp show), and invalid choice values (apm runtime setup badvalue) all produce clean Usage: + Error: messages with exit code 2 -- no stack traces observed.
• --verbose/-v, --dry-run, -y/--yes, and --help flags are present and functioning everywhere expected across init, install, uninstall, update, compile, deps update, mcp search, mcp show, deps clean, and runtime remove; wording varies slightly command-to-command but remains accurate to each command's actual behavior (not flagged as a defect, just noted for awareness).
• README.md command references (apm install, apm compile -t copilot, apm lock export --format cyclonedx|spdx, apm marketplace add, apm install --mcp ... --transport http) all verified against actual CLI output -- no drift found.
• Spot-checked apm list, apm view, apm cache, apm policy, apm marketplace -- all clean, no typos, consistent structure.

[!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 · copilot · auto · 109.9 AIC · ⌖ 5.34 AIC · ⊞ 9.3K · ◷

• expires on Sep 19, 2026, 1:14 PM UTC

Start with docs/src/content/docs/reference/cli/init.md and compare both init examples with src/apm_cli/utils/console.py and commands/init.py. Then inspect the Click help definitions for the listed top-level commands and standardize their summary punctuation. Re-run the documented apm init examples and apm --help; done means the output symbols, table note, and command summaries match the agreed style.