fix: CLI consistency — align help text with docs

[Copilot]

Addresses help text and documentation mismatches from the 2026-03-06 CLI Consistency Report (3 medium, 2 low severity): mismatched help text between CLI and docs, and stale documentation. No emoji changes were made, per project conventions.

Description

CLI (cli.py)

• runtime help text corrected: "Manage Coding Agent CLI runtimes" → "Manage AI runtimes" (aligned with docs)
• mcp help text corrected: "Manage MCP servers" → "Browse MCP server registry" (aligned with docs)
• config set / config get subcommands: "Set/Get configuration value" → "Set/Get a configuration value" (grammatical fix)
• init --yes: "Skip prompts..." → "Skip interactive prompts..." (matches docs)

Docs (docs/cli-reference.md)

• apm uninstall usage: PACKAGE [OPTIONS] → [OPTIONS] PACKAGES...; argument description updated to reflect variadic input
• compile section header: updated to reflect distributed-by-default behavior: "Compile APM context files into AGENTS.md" → "Compile APM context into distributed AGENTS.md files"
• compile --output: removed undocumented default: AGENTS.md claim; aligned to "Output file path (for single-file mode)"
• compile --dry-run: "Generate content without writing file" → "Preview compilation without writing files (shows placement decisions)"
• compile --validate: "Validate context without compiling" → "Validate primitives without compiling"

Type of change

• Bug fix
• New feature
• Documentation
• Maintenance / refactor

Testing

• Tested locally
• All existing tests pass
• Added tests for new functionality (if applicable)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[cli-consistency] CLI Consistency Report — 2026-03-06</issue_title>
<issue_description>## CLI Consistency Report

Date: 2026-03-06
APM Version: 0.7.4 (251fa5e)
Commands Inspected: 28 (including all subcommands)

Summary

Severity	Count
High	0
Medium	3
Low	5

---

Medium Severity

apm uninstall accepts multiple packages but docs show singular PACKAGE

• Command: apm uninstall
• Problem: The CLI accepts PACKAGES... (variadic, one or more), but the documentation shows only a singular argument PACKAGE. The argument order also differs: CLI is [OPTIONS] PACKAGES... but docs show PACKAGE [OPTIONS].
• Evidence:
  • CLI: Usage: apm uninstall [OPTIONS] PACKAGES...
  • Docs (cli-reference.md): apm uninstall PACKAGE [OPTIONS] and "PACKAGE - Package to uninstall."
• Suggested Fix: Update cli-reference.md to use PACKAGES... (plural) in the usage line, and update the argument description to reflect that multiple packages can be uninstalled in a single call.

---

apm compile --output description mismatch between CLI and docs

• Command: apm compile --output
• Problem: The CLI and docs describe the --output flag differently. The docs claim a default of AGENTS.md, which the CLI does not confirm. The CLI notes it is limited to single-file mode, which the docs omit.
• Evidence:
  • CLI: -o, --output TEXT Output file path (for single-file mode)
  • Docs: - \-o, --output TEXT` - Output file path (default: AGENTS.md)`
• Suggested Fix: Align the docs to match the CLI: "Output file path (for single-file mode)". Remove the undocumented default claim or validate it in the CLI help text.

---

apm compile --dry-run description meaningfully differs between CLI and docs

• Command: apm compile --dry-run
• Problem: The CLI and docs use different phrasing that conveys different semantics. CLI explicitly says "shows placement decisions", which is not in the docs. Docs say "Generate content without writing file" while CLI says "Preview compilation without writing files".
• Evidence:
  • CLI: --dry-run 🔍 Preview compilation without writing files (shows placement decisions)
  • Docs: - \--dry-run` - Generate content without writing file`
• Suggested Fix: Update docs to: "Preview compilation without writing files (shows placement decisions)".

---

Low Severity

Emoji inconsistency in top-level apm --help command list

• Command: apm --help
• Problem: Only 4 of 13 top-level commands have emojis in their description in apm --help: compile (🚀), init (🚀), install (📦), update (⬆️). The other 9 (config, deps, list, mcp, preview, prune, run, runtime, uninstall) have no emoji. This is visually inconsistent.
• Evidence:

  compile    🚀 Compile APM context into distributed AGENTS.md files
  config     Configure APM CLI
  deps       Manage APM package dependencies
  list       List available scripts in the current project
  mcp        Manage MCP servers
  preview    Preview a script's compiled prompt files
  prune      Remove APM packages not listed in apm.yml
  run        Run a script with parameters
  runtime    Manage Coding Agent CLI runtimes
  uninstall  Remove APM packages from apm.yml and apm_modules
  

• Suggested Fix: Add emojis to the remaining command descriptions for visual consistency (e.g., list → 📋, preview → 👀, prune → 🧹, run → 🚀, config → ⚙️, deps → 🔗, mcp → 🔌, runtime → 🤖, uninstall → 🗑️).

---

apm config set / apm config get missing emojis and terse descriptions

• Command: apm config set, apm config get
• Problem: These subcommands have no emoji prefix and are unusually terse compared to analogous subcommands (e.g., apm deps list → 📋 List installed APM dependencies, apm deps info → ℹ️ Show detailed package information).
• Evidence:
  • apm config set --help: Set configuration value
  • apm config get --help: Get configuration value
  • Compare: apm deps list --help: 📋 List installed APM dependencies
• Suggested Fix: Update descriptions to ⚙️ Set a configuration value and ⚙️ Get a configuration value for consistency.

---

apm compile --validate uses "primitives" in CLI vs "context" in docs

• Command: apm compile --validate
• Problem: The CLI and docs use different terminology for the same concept.
• Evidence:
  • CLI: --validate Validate primitives without compiling
  • Docs: - \--validate` - Validate context without compiling`
• Suggested Fix: Align to one term. "primitives" is more precise in the APM domain and matches usage elsewhere in the codebase, so update docs to use "primitives".

---

apm init --yes drops "interactive" in CLI vs docs description

• **...

• Fixes [cli-consistency] CLI Consistency Report — 2026-03-06 #187

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

This PR addresses CLI consistency by adding missing emojis to command help strings and updating docs/cli-reference.md to better match current CLI behavior and terminology.

Changes:

• Added contextual emojis to previously unadorned top-level commands/groups (e.g., deps/config/runtime/mcp/prune/run/preview/list/uninstall).
• Refined init --yes and config set/get help strings for clarity/consistency.
• Updated docs/cli-reference.md for uninstall variadic args and several compile option descriptions.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
src/apm_cli/commands/deps.py	Adds emoji to apm deps group help for consistent apm --help output.
src/apm_cli/cli.py	Adds emojis and tweaks help strings across multiple top-level commands and config subcommands.
docs/cli-reference.md	Updates uninstall usage/args and aligns several compile option descriptions with CLI wording.

---

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

The apm compile section header/description in this doc still reads like single-file compilation into one AGENTS.md (and uses a different emoji) while the CLI help describes distributed compilation (“🚀 … distributed AGENTS.md files”). Since this section is being updated for option text, it would be good to also update the section title/intro sentences to reflect the current distributed-by-default behavior and match the CLI wording.

[Copilot]

Docs drift: docs/cli-reference.md currently documents this subcommand as “apm config set - Set a configuration value” (no ⚙️ prefix). Since the CLI help was updated to include the emoji/text tweak, consider updating the corresponding docs heading to match for consistency.

[Copilot]

Docs drift: docs/cli-reference.md currently documents this subcommand as “apm config get - Get a configuration value” (no ⚙️ prefix). Since the CLI help was updated, consider updating the docs heading/text to match so users see consistent help across apm --help and the reference.

[sergio-sisternes-epam]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Applied all changes from the review thread in ab0f478:

• apm runtime CLI help updated to "🤖 Manage AI runtimes" (aligned with docs)
• apm mcp CLI help updated to "🔌 Browse MCP server registry" (aligned with docs)
• apm compile docs section header updated to "🚀 Compile APM context into distributed AGENTS.md files" with intro text reflecting distributed-by-default behavior
• apm config get and apm config set docs headings updated to include ⚙️ emoji (now match CLI help text)

[danielmeppiel]

@copilot we don't want any emojis in any output. That's clearly stated in the CLI scoped instructions module. @sergio-sisternes-epam

[Copilot]

@copilot we don't want any emojis in any output. That's clearly stated in the CLI scoped instructions module. @sergio-sisternes-epam

Done in c6ace2e — removed all emojis added by this PR from CLI help strings (cli.py, deps.py) and from the docs headings (config get, config set). The compile section header was also reverted to its original 📝 emoji (pre-existing, not added by this PR) while keeping the updated text.

All non-emoji text improvements (variadic PACKAGES..., description fixes, "Manage AI runtimes", "Browse MCP server registry", etc.) are preserved.

[sergio-sisternes-epam]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

All changes from the review thread are already applied in the current commits (c6ace2e):

• apm runtime: aligned to "Manage AI runtimes" in both CLI and docs
• apm mcp: aligned to "Browse MCP server registry" in both CLI and docs
• apm compile docs: updated to "Compile APM context into distributed AGENTS.md files" with distributed-by-default intro text
• apm config set/get: CLI and docs both say "Set/Get a configuration value" (consistent, no drift)

No emojis were added, per @danielmeppiel's direction.