[docs] Update aspire add command docs: exact-match requirement and interactive confirmation

[aspire-repo-bot]

Documents changes from microsoft/aspire#17728 by @mitchdenny.

Targeting release/13.4 based on the source PR milestone 13.4 (exact match on microsoft/aspire.dev).

Why this PR is needed

PR microsoft/aspire#17728 changed the behavior of aspire add in two ways:

1. Non-interactive mode (--non-interactive) now requires an exact friendly name or package ID. Previously, a partial/fuzzy match would silently auto-pick a candidate; now the command fails fast so scripts don't install the wrong integration.
2. Interactive mode now always prompts the user before adding a package when the result came from fuzzy or no-match fallback — even if only one candidate remains. Exact friendly-name/package-ID matches still skip the prompt.

The existing aspire-add.mdx described the old behavior (partial names silently auto-picked or listed without a confirmation step), which is now inaccurate.

Changes

• Updated the integration argument description in src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx to document the interactive vs. non-interactive difference.
• Added a new example showing non-interactive usage with an exact friendly name.

Files modified

• src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx (updated)

Generated by PR Documentation Check for issue #17728 · ● 10.1M · ◷

[Copilot]

Pull request overview

This PR updates the aspire add CLI reference to document the new exact-match behavior for non-interactive usage and confirmation prompts for fuzzy interactive matches.

Changes:

• Clarifies how exact, partial, and misspelled integration names are handled in interactive vs. non-interactive modes.
• Adds a CI/non-interactive example using an exact integration friendly name.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[IEvangelist]

🔍 Automated docs accuracy review — PR #1139

Source of truth

• microsoft/aspire branch: release/13.4
• SHA: 2574ef57e97fc393aff67592fd442afca6a6d02f
• Documents microsoft/aspire#17728 (commit 56e88661e)

Phase A — Claims verification (source-of-truth read)

• 5 verifiable claims + 1 narrative
• verified: 4 · verified-with-nuance: 1 · unverifiable: 0 · contradicted: 0

Phase B — Doc-tester run (blind user)

• Pages exercised: /reference/cli/commands/aspire-add/ (1 page, local frontend at http://localhost:54056)
• Critical issues: 1 · warnings: 0 · knowledge gaps: 1
• HTML rendering of the new content is clean; the new CLI behavior the PR documents could not be reproduced against any currently-installable Aspire CLI (staging 13.4.0 GA or dev 13.5.0-preview daily).

The single Phase A nuance is left as an inline review comment. The Phase B critical issue is in the Phase B report below.

---

📐 Phase A — Claim verification (release/13.4 @ 2574ef57e)

All non-narrative claims map cleanly to release/13.4 source. The new guard, the resource string, the friendly-name algorithm and the selection-flow plumbing all check out.

Verified claims (4) — click to expand evidence

Claim 2 — Interactive fuzzy fallback prompts before adding ✅ verified

Interactive mode (default): If the name doesn't exactly match, the CLI searches NuGet for approximate matches and prompts you to select from the results before adding.

• src/Aspire.Cli/Commands/AddCommand.cs:194-206 — GetIntegrationSearchMatches is the fuzzy fallback path
• src/Aspire.Cli/Commands/AddCommand.cs:217-235 — selection-flow switch routes the non-exact path through GetPackageByInteractiveFlow

Claim 3 — Single fuzzy / no-match candidate still prompts ✅ verified

This prompt is also shown when only a single fuzzy or no-match fallback candidate is found, so a package is never silently added without your confirmation.

• src/Aspire.Cli/Commands/AddCommand.cs:208-211 — promptForSingleFuzzyPackage = packageMatchKind == AddPackageMatchKindFuzzy
• src/Aspire.Cli/Commands/AddCommand.cs:397-400 — 1 when promptForSinglePackage && SupportsInteractiveInput => PromptForIntegrationAsync(...)
• src/Aspire.Cli/Commands/AddCommand.cs:219-225 — no-match path passes promptForSinglePackage: integrationName is not null

Claim 4 — Non-interactive mode requires an exact match ✅ verified

Non-interactive mode (--non-interactive): The command fails immediately if the name does not exactly match a friendly name or package ID.

• src/Aspire.Cli/Commands/AddCommand.cs:186 — throw new EmptyChoicesException(NonInteractiveRequiresExactPackageMatch.Format(integrationName))
• src/Aspire.Cli/Resources/AddCommandStrings.resx (NonInteractiveRequiresExactPackageMatch): "No exact match was found for '{0}'. In non-interactive mode the integration name must exactly match a package id or friendly name; fuzzy fallback is disabled to prevent silently selecting the wrong package."
• src/Aspire.Cli/CommonOptionNames.cs:20 — public const string NonInteractive = "--non-interactive";
• src/Aspire.Cli/Utils/CliHostEnvironment.cs:74-79 — SupportsInteractiveInput is set to false when the flag is passed

Claim 5 — aspire add kubernetes --non-interactive CI example ✅ verified

Add the kubernetes integration in a CI script (non-interactive mode requires the exact friendly name or package ID; partial names such as kube produce an error).

• Friendly name algorithm in IntegrationPackageSearchService.GenerateFriendlyName (strips Aspire.Hosting., replaces . with -, lowercases) yields Aspire.Hosting.Kubernetes → kubernetes
• PR #17728's commit body explicitly calls out aspire add kube --non-interactive as the buggy scenario it fixes by routing through the new guard above

Verified with nuance (1)

Claim 1 — Exact friendly/full IDs are added directly ⚠️ verified-with-nuance

Exact friendly names or full package IDs (for example, redis or Aspire.Hosting.Redis) are added directly.

The package selection is direct (no fuzzy search, no package-selection prompt) — confirmed by AddCommand.cs:175 (p.FriendlyName == integrationName || p.Package.Id == integrationName) and the Exact short-circuit at AddCommand.cs:217-235.

However, in interactive mode without an explicit --version, the user can still see a version prompt if multiple versions of the matched package are available. "Added directly" reads as "no prompts at all", which slightly oversells the behavior. See the inline review comment on the integration argument description for a suggested wording.

---

🧪 Phase B — Doc-tester report

Focus area: PR #1139 — aspire add command reference page
Page exercised: /reference/cli/commands/aspire-add/ (rendered locally from this PR's branch)
Tested CLIs:

• Staging quality: 13.4.0+11bea2eb9 (latest 13.4 release stream available via install.ps1 -Quality staging)
• Dev quality: 13.5.0-preview.1.26280.2+afbc0b96b8 (latest main daily)

Summary

Category	Passed	Failed	Warnings
Content rendering	4	0	0
CLI happy paths	3	0	0
CLI error paths	0	1	0
Knowledge gaps	—	—	1

Critical issues

Issue 1: Documented "partial names produce an error" behavior is not observable in any currently-installable CLI

Location: /reference/cli/commands/aspire-add/ — both the new "Non-interactive mode" bullet and the new aspire add kubernetes --non-interactive example.

What the documentation says:

Non-interactive mode (--non-interactive): The command fails immediately if the name does not exactly match a friendly name or package ID.

Add the kubernetes integration in a CI script (non-interactive mode requires the exact friendly name or package ID; partial names such as kube produce an error).

What actually happens (blind reproduction, fresh aspire-starter project):

Command	Expected per docs	Actual (staging 13.4.0)	Actual (dev 13.5.0-preview)
aspire add kubernetes --non-interactive	success	✅ success — Aspire.Hosting.Kubernetes added	✅ success
aspire add kube --non-interactive	error	❌ silent success — Aspire.Hosting.Kubernetes added	❌ silent success
aspire add postgr --non-interactive	error	not tested	❌ silent success — Aspire.Hosting.PostgreSQL added
aspire add red --non-interactive	error	not tested	❌ silent success — Aspire.Hosting.Redis added
aspire add nonexistentpackagexyz --non-interactive	error	not tested	❌ silent success — Aspire.Hosting.AgentFramework.DevUI added (CLI prints "No packages matched your search term … Showing all available packages" then picks one)

Evidence — aspire add kube --non-interactive on dev CLI:

==== TEST: aspire add kube --non-interactive (should FAIL per docs) ====
EXIT CODE: 0
OUTPUT: Searching for Aspire integrations...
Adding Aspire hosting integration...
✅ The package Aspire.Hosting.Kubernetes::13.3.5-preview.1.26270.6 was added successfully.

Evidence — aspire add nonexistentpackagexyz --non-interactive on dev CLI:

EXIT CODE: 0
OUTPUT: Searching for Aspire integrations...
No packages matched your search term 'nonexistentpackagexyz'. Showing all available packages.
Adding Aspire hosting integration...
✅ The package Aspire.Hosting.AgentFramework.DevUI::1.8.0-preview.260528.1 was added successfully.

This is the exact silent auto-pick scenario the docs (and PR #17728's commit body) describe as fixed, but it is still observable in every Aspire CLI a reader can install today.

Why this is critical for the docs reader: a user who follows the new example to validate their understanding will see success, not an error — making the doc's claim feel incorrect. CI scripts that rely on the documented "fails immediately" guarantee will continue to silently install unexpected packages.

Recommended actions (any one of these would resolve it):

• Hold this doc PR until a staging (or daily) 13.4.x CLI build that includes PR #17728 is published, then re-verify
• Add a version note such as "Available in Aspire CLI 13.4.x (build YYYYMMDD or later)" next to the new bullet and example
• If the implementation guard does NOT in fact fire for the "single fuzzy match" path (i.e. for kube → kubernetes), soften the wording — e.g. "partial names with no NuGet matches produce an error" — and update the example to use a clearly-nonexistent name (note: per the dev CLI test above, even zero-NuGet-match silently auto-picks, so this softening alone is insufficient)

This finding doesn't contradict Phase A (the source on release/13.4 does carry the new guard). It is a release-timing / shipping-coordination concern that affects what a reader experiences today.

Knowledge gaps

Knowledge Gap: Exactly which Aspire CLI version enforces the new behavior

What I needed to know: The minimum installable Aspire CLI version that implements the "fails immediately on inexact match" behavior described by this PR.
Source of my knowledge: Could only infer from Phase A source reads — no signal from the docs themselves.
User impact: Readers on any current CLI (13.4.0 GA or main daily) will observe the opposite of what's documented and may file bug reports or distrust subsequent docs.
Recommendation:

• Add a "Requires" / "Available in" version note on the affected bullet + example
• Reasonable to assume the latest stable CLI matches the latest release-branch docs (counter: empirically it does not, as shown above)

Passed checks

• Page returns HTTP 200 at /reference/cli/commands/aspire-add/ (815 KB rendered)
• All new prose fragments render in the live HTML: "Exact friendly names or full package IDs", "Interactive mode", "Non-interactive mode", "never silently added without your confirmation", "fails immediately if the name does not exactly match", "partial names such as", "aspire add kubernetes --non-interactive"
• New bullet list under the integration argument renders with correct <ul><li><strong>Interactive mode</strong>…</li><li><strong>Non-interactive mode</strong>…</li></ul> structure, and inline <code> spans for --non-interactive, redis, Aspire.Hosting.Redis
• New example code block renders with the existing copy-to-clipboard widget (data-code="aspire add kubernetes --non-interactive") and matches the page's bash highlight style
• --non-interactive option is correctly listed under Options (via existing partial option-non-interactive); cross-reference is intact
• Happy-path commands (aspire add kubernetes --non-interactive, aspire add redis --non-interactive, aspire add Aspire.Hosting.Redis --non-interactive) behave exactly as documented on both tested CLIs

Recommendations

1. Coordinate doc ship with CLI ship. The author should confirm a published 13.4.x CLI that enforces PR #17728's guard before this page goes live — or add a clear "Available in X.Y.Z and later" badge.
2. Clarify the version-prompt nuance for exact-match interactive adds (see inline comment on Claim 1).
3. Consider strengthening the example by also showing the expected error message a user should see in a CI log, once the enforcing CLI is published — that makes the behavior testable instead of being a prose claim.

---

Automated review. Phase A reads microsoft/aspire@release/13.4 source as the source of truth. Phase B uses only the local docs site + public Aspire CLI installs (no source reads).

[IEvangelist]

Phase B critical finding — documented error is not reproducible

A blind reader running this exact example today will not see the documented error. Tested on the latest publicly-installable Aspire CLIs:

CLI	aspire add kube --non-interactive
staging quality: 13.4.0+11bea2eb9	❌ silently adds Aspire.Hosting.Kubernetes
dev quality: 13.5.0-preview.1.26280.2+afbc0b96b8	❌ silently adds Aspire.Hosting.Kubernetes

Even aspire add nonexistentpackagexyz --non-interactive silently picks Aspire.Hosting.AgentFramework.DevUI after printing "No packages matched your search term … Showing all available packages" — exactly the silent auto-pick PR #17728 is meant to prevent.

Phase A confirms release/13.4 source (AddCommand.cs:186 + NonInteractiveRequiresExactPackageMatch resource) carries the guard, so this is a release-timing issue: please verify a published 13.4.x CLI build that actually enforces this guard before merging, or add an "Available in X.Y.Z and later" note. See the full Phase B report on the review for the complete reproduction.

[IEvangelist]

Deferring this to a human because the release/13.4 source at microsoft/aspire@2574ef5 contains the non-interactive exact-match guard in src/Aspire.Cli/Commands/AddCommand.cs:186-191 and the corresponding error string in src/Aspire.Cli/Resources/AddCommandStrings.resx:226-228, but the published builds cited in this thread do not exhibit that behavior. I cannot verify the first published 13.4.x build containing the guard from the source branch alone, so a maintainer should decide whether to hold the PR for the build or add a version-specific availability note.