fix: CLI consistency improvements (target aliases, deps clean flags, verbose shorthand, help text) by Copilot · Pull Request #303 · microsoft/apm

Copilot · 2026-03-14T19:19:06Z

Addresses all 6 findings from the CLI Consistency Report (2026-03-13). Standardizes option conventions across commands and aligns CLI help text with documentation.

Description

Medium severity

apm pack --target: Swapped choice order to [vscode|copilot|claude|all] — vscode is now primary, copilot is the alias. Matches apm compile convention. Docs updated to reflect new ordering and alias wording.
apm deps clean: Added --dry-run (preview without deleting, lists each package that would be removed) and --yes/-y (skip confirmation for CI). Package count now uses _scan_installed_packages() for accuracy (counts actual installed packages, not top-level org directories). Consistent with other destructive commands (prune, uninstall).
apm mcp list --limit: Added show_default=True → help now shows [default: 20], matching apm mcp search.

Low severity

apm install --verbose: Added -v short flag, matching apm compile.
apm deps update docs: Renamed argument from PACKAGE_NAME → PACKAGE to match the actual CLI usage string.
apm runtime status: Updated CLI help text and function docstring to "Show active runtime and preference order", aligning with docs phrasing.

Documentation in docs/src/content/docs/reference/cli-commands.md updated to reflect all changes.

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-13</issue_title>
<issue_description>## CLI Consistency Report

Date: 2026-03-13
APM Version: 0.7.8 (09fef91)
Commands Inspected: 30

All findings were verified by running the actual CLI. Every evidence block contains exact output.

Summary

Severity	Count
High	0
Medium	3
Low	3

Medium Severity

1. `--target` values differ between `apm pack` and `apm compile`

Commands: apm pack, apm compile
Problem: The two commands use opposite conventions for the same target concept. apm pack treats copilot as the canonical value (with vscode as an alias). apm compile treats vscode as the canonical value (with agents as an alias). Users switching between the two commands face inconsistent terminology.

Evidence:

# apm pack --help
-t, --target [copilot|vscode|claude|all]
                                Filter files by target (default: auto-
                                detect). 'vscode' is an alias for 'copilot'.

# apm compile --help
-t, --target [vscode|agents|claude|all]
                                Target platform: vscode/agents (AGENTS.md),
                                claude (CLAUDE.md), or all. Auto-detects if
                                not specified.
```

Suggested Fix: Standardize on vscode as the primary value across both commands (matching the VSCode-facing branding). In apm pack, swap so the accepted values are [vscode|copilot|claude|all] with a note that copilot is the alias for vscode.

2. `apm deps clean` is missing `--dry-run` and `--yes` flags

Command: apm deps clean
Problem: apm deps clean removes the entire apm_modules/ directory but offers no --dry-run preview and no --yes flag for non-interactive/scripted use. Every other destructive operation in the CLI supports --dry-run (install, uninstall, prune, pack, unpack), and apm runtime remove has --yes. The asymmetry makes deps clean harder to use safely in CI pipelines.

Evidence:

# apm deps clean --help
Usage: apm deps clean [OPTIONS]

  Remove all APM dependencies

Options:
  --help  Show this message and exit.

# apm prune --help (for comparison — same category, has --dry-run)
Options:
  --dry-run  Show what would be removed without removing
  --help     Show this message and exit.

Suggested Fix: Add --dry-run (show what would be removed) and --yes / -y (skip the interactive confirmation prompt) to apm deps clean.

3. `apm mcp list --limit` does not display a default value; `apm mcp search --limit` does

Commands: apm mcp list, apm mcp search
Problem: Both commands expose a --limit INTEGER option, but only apm mcp search annotates the default value in the help text. Users running apm mcp list cannot tell how many results will be returned without reading the source or running the command.

Evidence:

# apm mcp list --help
  --limit INTEGER  Number of results to show

# apm mcp search --help
  --limit INTEGER  Number of results to show  [default: 10]

Suggested Fix: Add a default= parameter to the --limit option in apm mcp list so the help text displays [default: N], matching apm mcp search.

Low Severity

4. `--verbose` has a short flag (`-v`) in `apm compile` but not in `apm install`

Commands: apm install, apm compile
Problem: Both commands expose a --verbose flag but only apm compile adds the -v shorthand. Users who habitually type -v for verbose output in apm install get an error.

Evidence:

# apm install --help
  --verbose                     Show detailed installation information

# apm compile --help
  -v, --verbose                   Show detailed source attribution and
                                  optimizer analysis

Suggested Fix: Add -v as a short flag for --verbose in apm install.

5. `apm deps update` argument name differs between CLI and docs

Command: apm deps update
Problem: The CLI declares the optional positional argument as PACKAGE, but the documentation at docs/src/content/docs/reference/cli-commands.md refers to it as PACKAGE_NAME. While functionally harmless, it creates confusion when cross-referencing.

Evidence:

# apm deps update --help (CLI)
Usage: apm deps update [OPTIONS] [PACKAGE]

# docs/src/content/docs/reference/cli-commands.md (line 589)
- `PACKAGE_NAME` - Optional. Update specific package only

Suggested Fix: Align the documentation to use PACKAGE to match the actual CLI usage string, or update the CLI source to use PACKAGE_NAME for clarity.

6. `apm runtime status` description diverges between CLI and...

Fixes [cli-consistency] CLI Consistency Report — 2026-03-13 #284

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

Co-authored-by: sergio-sisternes-epam <207026618+sergio-sisternes-epam@users.noreply.github.com>

Copilot

Pull request overview

This PR addresses CLI consistency gaps across APM commands by standardizing target aliasing/help text, adding safety flags to destructive operations, and aligning documentation with the CLI.

Changes:

Reorders apm pack --target choices and updates alias wording to prefer vscode with copilot as an alias.
Adds --dry-run and --yes/-y to apm deps clean, and improves related docs/help defaults elsewhere (apm mcp list --limit, apm install --verbose shorthand).
Updates CLI help text (apm runtime status) and refreshes parts of the CLI reference docs.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
uv.lock	Bumps locked editable project version to 0.7.9.
src/apm_cli/commands/runtime.py	Updates `apm runtime status` command help text.
src/apm_cli/commands/pack.py	Reorders `--target` choices and flips alias wording to `copilot` → alias of `vscode`.
src/apm_cli/commands/mcp.py	Ensures `--limit` default is shown in help for `apm mcp list`.
src/apm_cli/commands/install.py	Adds `-v` shorthand for `--verbose`.
src/apm_cli/commands/deps.py	Adds `--dry-run` and `--yes/-y` to `apm deps clean`.
docs/src/content/docs/reference/cli-commands.md	Documents new `deps clean` flags, renames `deps update` arg in docs, updates `mcp list` default, and adjusts runtime status heading.

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

src/apm_cli/commands/deps.py

    # Show what will be removed
    package_count = len([d for d in apm_modules_path.iterdir() if d.is_dir()])

-    _rich_warning(f"This will remove the entire apm_modules/ directory ({package_count} packages)")
+    if dry_run:
+        _rich_info(f"Dry run: would remove apm_modules/ ({package_count} packages)")
+        return


src/apm_cli/commands/deps.py

 @deps.command(help="Remove all APM dependencies")
-def clean():
+@click.option("--dry-run", is_flag=True, default=False, help="Show what would be removed without removing")
+@click.option("--yes", "-y", is_flag=True, default=False, help="Skip confirmation prompt")
+def clean(dry_run: bool, yes: bool):


src/apm_cli/commands/runtime.py

-@runtime.command(help="Check which runtime will be used")
+@runtime.command(help="Show active runtime and preference order")
 def status():
    """Show which runtime APM will use for execution."""


docs/src/content/docs/reference/cli-commands.md

+apm deps clean [OPTIONS]
 ```

+**Options:**
+- `--dry-run` - Show what would be removed without removing
+- `--yes`, `-y` - Skip confirmation prompt (for non-interactive/scripted use)
+


sergio-sisternes-epam · 2026-03-14T23:02:21Z

@copilot review conflicts

…tring, and docs Co-authored-by: sergio-sisternes-epam <207026618+sergio-sisternes-epam@users.noreply.github.com>

Copilot · 2026-03-14T23:05:47Z

@copilot review conflicts

Addressed all 4 review conflicts in commit b408d07:

Accurate package count — apm deps clean now uses _scan_installed_packages() from _helpers.py to count actual installed packages (e.g. testorg/testrepo) instead of top-level directories. --dry-run also lists each package that would be removed.
Tests — Added 6 unit tests in tests/unit/test_deps_clean_command.py covering: --dry-run leaves apm_modules/ intact, --dry-run lists packages, --yes removes without prompting, -y short flag, no apm_modules/ exits cleanly.
status() docstring — Updated from "Show which runtime APM will use for execution." to "Show active runtime and preference order." to match the CLI help text and docs.
apm pack docs — Updated from [copilot|vscode|claude|all] / "vscode is an alias for copilot" to [vscode|copilot|claude|all] / "copilot is an alias for vscode", matching the code and apm compile convention.

Initial plan

773a2a6

Copilot AI assigned Copilot and sergio-sisternes-epam Mar 14, 2026

Copilot started work on behalf of sergio-sisternes-epam March 14, 2026 19:19 View session

Copilot AI and others added 2 commits March 14, 2026 19:20

Initial plan for CLI consistency fixes

b7b1ae2

Co-authored-by: sergio-sisternes-epam <207026618+sergio-sisternes-epam@users.noreply.github.com>

fix: CLI consistency improvements across 6 reported findings

af9fc94

Co-authored-by: sergio-sisternes-epam <207026618+sergio-sisternes-epam@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] [cli-consistency] Fix target values inconsistency in CLI~~ fix: CLI consistency improvements (target aliases, deps clean flags, verbose shorthand, help text) Mar 14, 2026

Copilot AI requested a review from sergio-sisternes-epam March 14, 2026 19:25

Copilot finished work on behalf of sergio-sisternes-epam March 14, 2026 19:25

sergio-sisternes-epam requested review from Copilot and removed request for sergio-sisternes-epam March 14, 2026 19:58

Copilot started reviewing on behalf of sergio-sisternes-epam March 14, 2026 19:59 View session

Copilot AI reviewed Mar 14, 2026

View reviewed changes

sergio-sisternes-epam marked this pull request as ready for review March 14, 2026 23:01

sergio-sisternes-epam requested a review from danielmeppiel as a code owner March 14, 2026 23:01

Copilot started work on behalf of sergio-sisternes-epam March 14, 2026 23:02 View session

fix: address PR review feedback - accurate package count, tests, docs…

b408d07

…tring, and docs Co-authored-by: sergio-sisternes-epam <207026618+sergio-sisternes-epam@users.noreply.github.com>

Copilot AI requested a review from sergio-sisternes-epam March 14, 2026 23:06

Copilot finished work on behalf of sergio-sisternes-epam March 14, 2026 23:06

sergio-sisternes-epam approved these changes Mar 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: CLI consistency improvements (target aliases, deps clean flags, verbose shorthand, help text)#303

fix: CLI consistency improvements (target aliases, deps clean flags, verbose shorthand, help text)#303
Copilot wants to merge 4 commits intomainfrom
copilot/cli-consistency-fix-target-values

Copilot AI commented Mar 14, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

sergio-sisternes-epam commented Mar 14, 2026

Uh oh!

Copilot AI commented Mar 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Testing

Summary

Medium Severity

1. --target values differ between apm pack and apm compile

2. apm deps clean is missing --dry-run and --yes flags

3. apm mcp list --limit does not display a default value; apm mcp search --limit does

Low Severity

4. --verbose has a short flag (-v) in apm compile but not in apm install

5. apm deps update argument name differs between CLI and docs

6. apm runtime status description diverges between CLI and...

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

sergio-sisternes-epam commented Mar 14, 2026

Uh oh!

Copilot AI commented Mar 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Mar 14, 2026 •

edited

Loading

1. `--target` values differ between `apm pack` and `apm compile`

2. `apm deps clean` is missing `--dry-run` and `--yes` flags

3. `apm mcp list --limit` does not display a default value; `apm mcp search --limit` does

4. `--verbose` has a short flag (`-v`) in `apm compile` but not in `apm install`

5. `apm deps update` argument name differs between CLI and docs

6. `apm runtime status` description diverges between CLI and...