[cli-consistency] CLI Consistency Report - 2026-09-18

CLI Consistency Report

Date: 2026-09-18
APM Version: Agent Package Manager (APM) CLI version 0.31.0 (c6d99eb)
Commands Inspected: 27 (apm --help, init, install, uninstall, update, compile, run, deps, deps list, deps tree, deps info, deps clean, deps update, deps why, mcp, mcp list, mcp search, mcp show, mcp install, config, config set, config get, config list, runtime, runtime setup, plus invalid-argument checks for install, deps info, config set, mcp show, runtime setup)

Summary

Medium Severity

apm mcp install doc omits --trust-transitive-mcp from the forwarded-options table

• Command: apm mcp install
• Problem: The actual CLI help for apm mcp install lists --trust-transitive-mcp as a forwarded install option, but the "Forwarded install options" table in docs/src/content/docs/reference/cli/mcp.md does not mention it. Every other flag shown by the CLI (--transport, --url, --env, --header, --registry, --mcp-version, --dev, --dry-run, --force, -g/--global, --no-policy, --verbose) is present in the doc table, so this is a documentation gap rather than an intentional omission.
• Evidence:
  • CLI output (apm mcp install --help):

    Forwarded install options (see 'apm install --help' for the full list):
      --transport [stdio|http|sse|streamable-http]
      --url URL              Server URL for remote transports
      --env KEY=VALUE        Environment variable (repeatable)
      --header KEY=VALUE     HTTP header (repeatable)
      -t, --target TARGET    Agent target(s) to deploy to
      --registry URL         Custom registry URL
      --mcp-version VER      Pin registry entry to a specific version
      -g, --global           Install to user scope (~/.apm/)
      --trust-transitive-mcp Trust MCP servers from transitive dependencies
      --dev / --dry-run / --force / --verbose / --no-policy
    

  • Doc excerpt (docs/src/content/docs/reference/cli/mcp.md, "Forwarded install options" table):

    | Flag | Description |
    |---|---|
    | `--transport [stdio\|http\|sse\|streamable-http]` | Transport type. |
    | `--url URL` | Server URL for remote transports. |
    | `--env KEY=VALUE` | Environment variable. Repeatable. |
    | `--header KEY=VALUE` | HTTP header. Repeatable. |
    | `--registry URL` | Custom registry URL for this install; persisted on the dependency in `apm.yml`. |
    | `--mcp-version VER` | Pin the registry entry to a specific version. |
    | `--dev` | Add to `devDependencies`. |
    | `--dry-run` | Resolve and print without writing `apm.yml`. |
    | `--force` | Overwrite an existing entry. |
    | `-g`, `--global` | Install through `~/.apm/apm.yml` into global-capable runtimes. |
    | `--no-policy` | Skip policy checks. |
    | `--verbose`, `-v` | Verbose output. |
    

    (No --trust-transitive-mcp row; also missing -t, --target, though that one is implied elsewhere in the doc's synopsis/examples.)
• Suggested Fix: Add a --trust-transitive-mcp row to the "Forwarded install options" table in docs/src/content/docs/reference/cli/mcp.md, e.g. | \--trust-transitive-mcp` | Trust self-defined MCP servers from transitive dependencies (skip re-declaration requirement). |, matching the description used in apm install --help`.

Clean Areas

• Installation & version check: apm --version and apm --help work correctly; top-level command list is accurate.
• Core commands (init, install, uninstall, update, compile, run): help text is well-structured, uses consistent Usage: / Options: layout, and flag descriptions read naturally.
• deps subcommands (list, tree, info, clean, update, why): all flags cross-checked against docs/src/content/docs/reference/cli/deps.md with no discrepancies (aside from the mcp install finding above, which is unrelated to deps).
• mcp subcommands other than install (list, search, show): match documentation exactly.
• config subcommands (set, get, list): match docs/src/content/docs/reference/cli/config.md with no gaps.
• runtime subcommands (setup): matches docs/src/content/docs/reference/cli/runtime.md, including the {copilot|codex|gemini|llm} choice validation.
• Flag consistency audit: --verbose/-v, --dry-run, --yes/-y, and --global/-g are spelled and described consistently across every command that supports them. No --dryrun or other misspelled variants found.
• Exit behavior: Invalid invocations (apm install --nonexistent-flag, apm deps info with no argument, apm config set with no arguments, apm mcp show with no argument, apm runtime setup badruntime) all produce clean Usage: + Error: messages and exit code 2 -- no stack traces or unhandled exceptions observed.
• Typos/grammar: No spelling errors, doubled words, or placeholder/TODO text found in any inspected help output.
• README.md cross-reference: Commands and flags referenced in README.md (apm install, apm compile -t copilot, apm install --mcp ... --transport http, apm marketplace add, apm lock export --format cyclonedx|spdx) all exist and behave as described.

Note: the task's Step 3.4 instructions referenced docs/cli-reference.md, which does not exist in this repository. The current documentation lives at docs/src/content/docs/reference/cli/*.md, with /reference/cli-commands configured as a redirect to /reference/cli/install. This is a stale instruction path, not a CLI/doc defect, so it is not counted as a finding, but is called out here for reference.

[!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 · 99 AIC · ⌖ 3.93 AIC · ⊞ 8.8K · ◷

• expires on Sep 20, 2026, 1:13 PM UTC

Open docs/src/content/docs/reference/cli/mcp.md and inspect the “Forwarded install options” table. Compare it with the documented apm mcp install --help output, then update the table so the documented forwarded options match the CLI; the issue is done when the missing option is represented consistently.