[docs] Document argument-based built-in resource commands (set-parameter/delete-parameter)

[aspire-repo-bot]

Documents changes from microsoft/aspire#17021, authored by @JamesNK.

Targeting release/13.4 based on the source PR milestone 13.4.

Why this PR is needed

Aspire 13.4 updates built-in resource commands to use structured Arguments on ResourceCommandAnnotation so callers (dashboard, CLI, MCP) can supply values directly without interactive prompting. Two built-in parameter commands were renamed for CLI consistency:

• parameter-set → set-parameter
• parameter-delete → delete-parameter

The old names are kept as aliases. The renamed commands now accept named option flags (--value, --save-to-user-secrets, --delete-from-user-secrets), enabling non-interactive use from scripts and automation.

Documentation changes

Updated pages

• src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx — Added a new Built-in parameter commands section documenting set-parameter (with --value and --save-to-user-secrets options) and delete-parameter (with --delete-from-user-secrets), including the rename note.
• src/frontend/src/content/docs/whats-new/aspire-13-4.mdx — Added an Argument-based built-in resource commands section explaining the feature, CLI examples, and the command rename table.

Generated by PR Documentation Check for issue #17021 · ● 21.7M · ◷

[Copilot]

Pull request overview

Documents Aspire 13.4’s updated built-in parameter resource commands for aspire resource, including the move to argument-based (named option) invocation and the canonical rename to set-parameter / delete-parameter (with old names retained as aliases).

Changes:

• Adds a “what’s new” entry describing argument-based built-in resource commands and the command rename mapping.
• Updates the aspire resource CLI reference to include a new “Built-in parameter commands” section with options and examples.
• Expands the <command> argument description to include the new canonical parameter command names as examples.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/frontend/src/content/docs/whats-new/aspire-13-4.mdx	Adds a new “Argument-based built-in resource commands” section with examples and a rename table.
src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx	Documents set-parameter / delete-parameter built-ins, their options, and notes the rename/aliases.

Comments suppressed due to low confidence (1)

src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx:142

• The options table lists --delete-from-user-secrets as a value-less flag, but the examples pass an explicit boolean value (--delete-from-user-secrets true). Consider updating the option documentation to show the boolean value syntax (e.g., --delete-from-user-secrets <true|false>) or adjusting the example to match the intended usage.

  | Option | Description |
  | --- | --- |
  | `--delete-from-user-secrets` | Also remove the value from the .NET user secrets store. Optional. |

  ```bash title="Aspire CLI"
  aspire resource mydb-password delete-parameter
  aspire resource mydb-password delete-parameter --delete-from-user-secrets true

</details>



---

💡 <a href="/microsoft/aspire.dev/new/release/13.4?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.

[IEvangelist]

Generated by running the doc-tester skill against PR #974 — built the docs locally with aspire run, browsed the changed pages on the local Astro frontend (not aspire.dev), inspected the rendered HTML, and validated link/component usage. The skill's "user-centric" rules were followed (no Aspire product source code was consulted).

Summary

The PR adds new docs for two argument-based built-in resource commands (set-parameter, delete-parameter) in two files:

• src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx — new Built-in parameter commands section. Renders correctly on the local site: the H2 anchor #built-in-parameter-commands is present, the option tables, code samples, and <Aside type="note"> all render as expected.
• src/frontend/src/content/docs/whats-new/aspire-13-4.mdx — new top-level Argument-based built-in resource commands section plus a "This release introduces:" bullet and a <LearnMore> callout.

The reference page changes are good. The whats-new changes have two blocking problems when considered against release/13.4: a broken <LearnMore> (the link silently disappears at render time) and a hard merge conflict against the page that release/13.4 has since grown.

Verdict

Request changes. The doc would mislead a reader on a key navigation step (the LearnMore renders as plain text, not a link), and the PR currently can't be merged into release/13.4 without manual conflict resolution that also has to reconcile content that already covers part of this topic.

Findings

🔴 Blocker — <LearnMore link="…"> renders as plain text, not a link

File: src/frontend/src/content/docs/whats-new/aspire-13-4.mdx, line 59

<LearnMore link="/reference/cli/commands/aspire-resource/#built-in-parameter-commands">Built-in parameter commands</LearnMore>

The LearnMore.astro component (src/frontend/src/components/LearnMore.astro) does not accept a link prop. It only renders its children:

<div class="learn-more">
  <Icon class="icon" name="open-book" />
  <span><slot /></span>
</div>

I verified this against the locally-built site. The rendered HTML for this LearnMore is literally:

<div class="learn-more …"><svg …open-book…></svg><span …>Built-in parameter commands</span></div>

No <a href>, no clickable target. The reader sees the open-book icon next to dead text — there is no way to navigate to the reference page from the whats-new page.

For comparison, every existing <LearnMore> on release/13.4's whats-new/aspire-13-4.mdx uses the standard pattern with a markdown link in the slot:

<LearnMore>
  For more information, see [`aspire resource`](/reference/cli/commands/aspire-resource/).
</LearnMore>

Suggested fix:

<LearnMore>
  For details and options, see [Built-in parameter commands](/reference/cli/commands/aspire-resource/#built-in-parameter-commands).
</LearnMore>

The destination anchor (#built-in-parameter-commands) is rendered correctly on the reference page and resolves locally, so only the source markup needs fixing.

Note: the PR also introduces (or carries over from a stale base) a second instance of the same bad pattern on line 72: <LearnMore link="/whats-new/upgrade-aspire/">Upgrade Aspire</LearnMore>. If that line is in the final merge, it should be fixed the same way.

🔴 Blocker — Merge conflict and topic duplication against release/13.4

GitHub reports mergeStateStatus: DIRTY, mergeable: CONFLICTING. Reproduced locally:

$ git merge --no-commit --no-ff upstream/release/13.4
Auto-merging src/frontend/src/content/docs/whats-new/aspire-13-4.mdx
CONFLICT (content): Merge conflict in src/frontend/src/content/docs/whats-new/aspire-13-4.mdx

The PR was authored against a near-empty stub of whats-new/aspire-13-4.mdx (~73 lines). The current release/13.4 version of that file is ~22 KB and already covers this area:

• An existing top-level "This release introduces:" bullet covers it: "Richer resource commands with typed arguments, visibility controls, immediate result display, named CLI options, resource-scoped help, …".
• An existing ### Resource command CLI improvements H3 (under 🛠️ CLI enhancements) already says: "Resource command inputs are now passed as named CLI options instead of positional arguments. … Running aspire resource <resource> --help also shows the commands available for that specific resource."
• An existing ### Resource command arguments, visibility, and results H3 covers typed-argument command authoring.

The PR's new H2 ## Argument-based built-in resource commands and its "This release introduces:" bullet aren't just hard to merge — they overlap with content already shipped on the page. The resolution should not be a mechanical "keep both"; the new material needs to be folded into the existing structure.

(reference/cli/commands/aspire-resource.mdx merges cleanly against release/13.4 and that file's surrounding ## Arguments / ## Options context is unchanged, so the conflict is isolated to whats-new.)

Suggested fix (whats-new only):

• Drop the new top-level "This release introduces:" bullet (it's redundant with the existing "Richer resource commands" bullet, which already lists named CLI options as a 13.4 highlight).
• Promote the renamed-commands content to a new H3 underneath the existing ### Resource command CLI improvements (or as a sibling H3 in the same section), instead of adding a brand-new top-level ## Argument-based built-in resource commands. Suggested heading: ### Built-in parameter commands (renamed).
• Move the parameter-set → set-parameter / parameter-delete → delete-parameter rename table into that H3, since today the rename isn't documented anywhere on the whats-new page.
• Use the corrected <LearnMore> pattern from the previous finding.

🟡 Major — Examples reference an undefined mydb-password parameter resource

Every example on both pages uses aspire resource mydb-password set-parameter … / aspire resource mydb-password delete-parameter …, but neither page shows how that resource gets into the AppHost. A reader following these docs as a "new user" has no way to reach a working aspire resource mydb-password … invocation without already knowing about AddParameter(...).

Both pages should either:

• Add a one-liner AppHost snippet showing where mydb-password comes from (e.g. builder.AddParameter("mydb-password", secret: true);), or
• Link to /fundamentals/external-parameters/ (which the aspire-resource.mdx page does not currently reference at all) the first time mydb-password appears.

A short cross-reference next to the ## Built-in parameter commands heading would be enough:

These commands operate on parameter resources declared in your AppHost (see External parameters).

🟡 Major — Boolean option syntax is shown but never explained

The examples use a --flag true form for the boolean options:

aspire resource mydb-password set-parameter --value "MyStr0ngP@ssword" --save-to-user-secrets true
aspire resource mydb-password delete-parameter --delete-from-user-secrets true

But the option tables describe these flags as if they were bare switches:

--save-to-user-secrets — Save the value to the .NET user secrets store…
--delete-from-user-secrets — Also remove the value from the .NET user secrets store. Optional.

This leaves the reader uncertain whether:

• --save-to-user-secrets alone (no value) works,
• --save-to-user-secrets false is meaningful,
• and what the default is when the flag is omitted (set-parameter says "defaults to preserving any existing saved state" — but doesn't say what that resolves to in practice).

For docs targeting "scripts, CI/CD pipelines, and AI coding agents," this ambiguity is worth tightening up. Either show the accepted forms in the table (<true|false>) or pick one canonical syntax and use it consistently.

🟢 Minor — --help discoverability example only on whats-new

whats-new/aspire-13-4.mdx shows:

aspire resource mydb-password set-parameter --help

…but the reference page aspire-resource.mdx, which is the page a reader actually lands on for command reference, never demonstrates set-parameter --help / delete-parameter --help. The reference page should include the per-command --help example so users discover the option list the canonical way, especially since the page already establishes elsewhere that "the help output lists each argument with its type, whether it's required, its default value…".

🟢 Minor — "Required" for --value is buried in the cell description

In the set-parameter option table:

| `--value <value>` | The value to assign to the parameter. Required. |

Visually this looks like every other row. Other CLI reference pages in this repo use bold or a leading Required. tag, or a separate Required column. Minor consistency nit — not worth blocking on.

Knowledge Gaps

I followed the doc-tester skill rule of not reading Aspire product source. Two things in this PR I could not verify end-to-end from documentation + a working AppHost:

1. That set-parameter / delete-parameter actually exist on parameter resources in 13.4 today, and that parameter-set / parameter-delete still work as aliases. I have aspire CLI 13.4.0-preview.1.26269.1 installed and the docs site running, but a quick scratch AppHost with AddParameter("mydb-password", secret: true) couldn't successfully start under that SDK preview ("AppHost process has exited unexpectedly" — backchannel never came up). I did not chase this further to keep the review under user-centric rules.

   • User impact: Following these docs literally is the only way a new user would learn these commands exist — so when the docs ship, please confirm both the canonical and alias forms still resolve on the actual 13.4 release CLI, and that --save-to-user-secrets / --delete-from-user-secrets accept the <flag> true form shown.
   • Recommendation: A maintainer with a working 13.4 AppHost containing an AddParameter(...) resource should run aspire resource <param> set-parameter --help and paste the actual help output into the reference page (similar to the existing Echo a message… example on the page).

2. --save-to-user-secrets default behavior wording. The phrase "defaults to preserving any existing saved state" in the set-parameter option table is not something I could derive from any other page on the local site. I assumed it meant "if the parameter was previously saved to user secrets and you omit this flag, the saved copy is left as-is" — but the doc never says that explicitly. Worth either expanding or dropping the half-sentence.

What I checked that passed

• Both pages load with HTTP 200 from the locally-built site (http://localhost:59516).
• ## Built-in parameter commands renders as an H2 with id="built-in-parameter-commands" on the reference page, is in the page's right-rail TOC, and the section anchor resolves.
• The <Aside type="note"> callouts on both pages render with the correct note styling.
• Code samples (```bash title="Aspire CLI") render with the expected title and copy-to-clipboard control.
• The rename callout (parameter-set → set-parameter, parameter-delete → delete-parameter) is consistent across both pages.
• The aspire-resource.mdx patch applies cleanly to release/13.4 (no conflict in that file).

---

Review generated by an AI agent running the doc-tester skill end-to-end against this PR on the release/13.4 base. No files in the repo were modified.

[IEvangelist]

@IEvangelist Applied in 17bef8f.

Addressed the review-level findings by fixing the LearnMore usage, resolving the release/13.4 merge conflict by folding the parameter-command content into the existing resource command CLI section, adding parameter-resource context with the external parameters link, clarifying boolean option syntax, adding the command-specific --help example, and making the required --value option clearer.

Verified against microsoft/aspire@56e88661e4d6026cea423827c62c067e11fdf192 on release/13.4 and edited per the doc-writer skill.

[IEvangelist]

Automated docs-from-code review — PR 974

Automated 3-phase review: Phase A verifies factual claims against the matching microsoft/aspire branch; Phase B exercises the rendered docs and Aspire CLI as a "blind" user via the doc-tester skill; Phase C combines both into this review.

Summary

• Source of truth: microsoft/aspire branch release/13.4 at SHA 2574ef57e97fc393aff67592fd442afca6a6d02f (source PR commit 486c044bdf0cfa8b8e7fb8db29fc71fc2381845b — #17021).
• PR head reviewed: 17bef8f606fd454f321991eb532a5324ad07d1f8.
• Phase A — Claim verification: 19 verifiable claims extracted across both changed files. 15 verified · 4 contradicted · 0 unverifiable.
• Phase B — Doc-tester run: Local frontend served the new aspire-resource.mdx and aspire-13-4.mdx content cleanly; anchor #built-in-parameter-commands resolves. CLI behavior tested end-to-end against a 13.4-SDK file-based AppHost with a parameter resource using both staging GA (13.4.0+11bea2eb9) and dev preview (13.5.0-preview.1.26280.2+afbc0b96b8) CLIs. 1 critical issue · 0 warnings · 8 passed checks.

The Phase A contradictions and the Phase B critical issue are the same root cause: the documented bare-flag form for the --save-to-user-secrets and --delete-from-user-secrets boolean options does not work with either currently-installable CLI, and the source code confirms it never will (those options carry DynamicLoading and are therefore wrapped as Option<string?> with ArgumentArity.ExactlyOne).

Verdict — REQUEST_CHANGES

Per the review matrix: at least one Phase A contradicted claim and a Phase B critical issue. The PR is otherwise solid — the rename, both legacy aliases, the option names, the --value required label, the per-command --help behavior, the rendered anchor target, and the worked examples (other than the bare-flag one) all match the source and behave as documented.

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

Contradicted (4)

#	File	Line	Claim	Evidence
C-3	src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx	121	"Boolean options for these commands accept either a bare flag or an explicit true or false value. For example, --save-to-user-secrets and --save-to-user-secrets true both request saving the value to user secrets."	src/Aspire.Hosting/Orchestrator/ParameterProcessor.cs lines 228-253 give SaveToUserSecrets (and lines 268-289 give DeleteFromUserSecrets) a DynamicLoading callback. In src/Aspire.Cli/Commands/ResourceCommand.cs line 393, parseAsString = parseMode == CommandArgumentParseMode.LoadArguments || argument.DynamicLoading is not null ⇒ true for these options, which makes line 406-411 wrap them as Option<string?> with Arity = ArgumentArity.ExactlyOne. Only the non-dynamic Option<bool> branch (lines 414-418) explicitly sets ZeroOrOne arity for bare-flag support. The dynamic-load string option requires a value.
C-8	src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx	132	Worked example: aspire resource mydb-password set-parameter --value "MyStr0ngP@ssword" --save-to-user-secrets	Same source-side wrapping as C-3 above. The example is a direct consequence of the (contradicted) bare-flag rule and reproducibly fails (see Phase B).
C-10	src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx	139	"The value is removed only when this option is supplied as a bare flag or with true."	The "with true" half is correct — ParameterProcessor.cs lines 442-446 only delete when the parsed value is true. The "bare flag" half is contradicted for the same reason as C-3.
C-18	src/frontend/src/content/docs/whats-new/aspire-13-4.mdx	179	"Boolean resource command options can be supplied as bare flags or with explicit true or false values. For example, --delete-from-user-secrets and --delete-from-user-secrets true both request deletion from user secrets."	Duplicate of C-3 with the delete-parameter option as the example; same source-side rebuttal.

Verified (15) — full details

Click to expand verified claims and evidence

#	File / line	Claim	Source evidence (release/13.4 @ 2574ef57e)
C-1	aspire-resource.mdx L115	<command> list now includes set-parameter and delete-parameter	src/Aspire.Hosting/ApplicationModel/KnownResourceCommands.cs defines SetParameterCommand = "set-parameter" (L36) and DeleteParameterCommand = "delete-parameter" (L41)
C-2	aspire-resource.mdx L119	"Aspire provides two built-in resource commands for managing parameter resources at runtime. These commands accept named options and can be used non-interactively..."	src/Aspire.Hosting/Orchestrator/ParameterProcessor.cs registers set-parameter with arguments: [valueInput, saveInput] (L256-266) and delete-parameter with arguments: [deleteFromSecretsInput] (L292-300)
C-4	aspire-resource.mdx L123	set-parameter is the canonical name; parameter-set is accepted as a legacy alias	src/Aspire.Cli/Commands/ResourceCommand.cs s_legacyCommandNameMap["parameter-set"] = "set-parameter" (L75-78); CLI test in PR 17021 uses parameter-set ⇒ resolved to canonical
C-5	aspire-resource.mdx L127	--value <value> is Required	ParameterProcessor.cs constructs valueInput with required: true (L200); ResourceCommand.cs:299 enforces Required option ... was not provided
C-6	aspire-resource.mdx L128	--save-to-user-secrets [true|false] option name and "Defaults to preserving any existing saved state"	Argument constant SaveToUserSecretsName = "SaveToUserSecrets" (L30) → kebab via ResourceCommand.cs:552-579 → --save-to-user-secrets. The DynamicLoading callback in ParameterProcessor.cs:240-253 sets context.Input.Value = "true" when an existing user-secrets section is present, otherwise leaves it null ⇒ default behavior preserves whichever state was previously saved.
C-7	aspire-resource.mdx L131	Example: aspire resource mydb-password set-parameter --value "MyStr0ngP@ssword"	Maps directly to set-parameter with the required --value; Phase B confirms it succeeds.
C-9	aspire-resource.mdx L135	delete-parameter is canonical; parameter-delete legacy alias accepted	s_legacyCommandNameMap["parameter-delete"] = "delete-parameter" (ResourceCommand.cs:78) and LegacyDeleteParameterCommand = "parameter-delete" (KnownResourceCommands.cs:47)
C-11	aspire-resource.mdx L142	Example: aspire resource mydb-password delete-parameter (no flags)	delete-parameter accepts a no-args invocation because deleteFromSecretsInput is not required: true and defaults to false (no user-secrets deletion). Phase B confirms.
C-12	aspire-resource.mdx L143	Example: aspire resource mydb-password delete-parameter --delete-from-user-secrets true	Maps to the option, parses to true, triggers user-secrets deletion per ParameterProcessor.cs:442-446. Phase B confirms.
C-13	aspire-resource.mdx L149	Per-command help: aspire resource mydb-password set-parameter --help	Resource-scoped help was already a 13.4 feature; Phase B confirms set-parameter --help prints the command's option list.
C-14	aspire-resource.mdx L153 (Aside)	"parameter-set was renamed to set-parameter and parameter-delete was renamed to delete-parameter. The old names are accepted as aliases and continue to work."	Matches PR 17021's actual diff in KnownResourceCommands.cs (rename) and ResourceCommand.cs (legacy alias map).
C-15	aspire-13-4.mdx L30 (summary bullet)	"Richer resource commands ... [+] built-in parameter command options" added to the feature line	Narrative summary; aligns with PR 17021's scope.
C-16	aspire-13-4.mdx L169	"The built-in set-parameter and delete-parameter commands now use named options too, so scripts can manage parameter resources without interactive prompts."	True per ParameterProcessor.cs registering named arguments on both commands (L256-266, L292-300).
C-17	aspire-13-4.mdx L173-176 (code block)	aspire resource mydb-password set-parameter --value "...", ... delete-parameter --delete-from-user-secrets true, ... set-parameter --help	All three invocations verified in Phase B (the first two against the running AppHost, --help against the same).
C-19	aspire-13-4.mdx L183 (LearnMore)	Link target changed to /reference/cli/commands/aspire-resource/#built-in-parameter-commands	Phase B confirms <h2 id="built-in-parameter-commands">Built-in parameter commands</h2> exists on the rendered resource page.

Phase B — Doc-tester results

Pages exercised: http://localhost:56807/reference/cli/commands/aspire-resource/, http://localhost:56807/whats-new/aspire-13-4/ (worktree-served, PR 974 head).

Test bed: Fresh aspire-empty file-based AppHost (apphost.cs, #:sdk Aspire.AppHost.Sdk@13.4.0) with builder.AddParameter("mydb-password", secret: true). Started via staging CLI; verified via both staging GA CLI (13.4.0+11bea2eb9) and dev preview CLI (13.5.0-preview.1.26280.2+afbc0b96b8).

Critical issue (1)

🔴 Bare-flag boolean form does not work for --save-to-user-secrets / --delete-from-user-secrets

• Where the doc says it works:
  • aspire-resource.mdx line 121 — explicit rule
  • aspire-resource.mdx line 132 — worked example: aspire resource mydb-password set-parameter --value "MyStr0ngP@ssword" --save-to-user-secrets
  • aspire-resource.mdx line 139 — --delete-from-user-secrets "supplied as a bare flag or with true"
  • aspire-13-4.mdx line 179 — duplicate rule using --delete-from-user-secrets as the example
• What actually happens (reproduced on both staging and dev CLIs):

  > aspire resource mydb-password set-parameter --value 'BareFlagPass' --save-to-user-secrets --non-interactive
  Scanning for running AppHosts...
  ❌ Required argument missing for option: '--save-to-user-secrets'.
  
  > aspire resource mydb-password delete-parameter --delete-from-user-secrets --non-interactive
  Scanning for running AppHosts...
  ❌ Required argument missing for option: '--delete-from-user-secrets'.
  

• What does work: Explicit value forms — --save-to-user-secrets true, --save-to-user-secrets false, --delete-from-user-secrets true, --delete-from-user-secrets false.
• User impact: The worked example on line 132 is the second thing a reader will copy-paste; it fails immediately with a confusing message that says "Required argument missing" even though the doc says the argument is optional.
• Suggested fix: Either (a) remove the bare-flag claim and rewrite both examples and the rule to require an explicit true/false value, or (b) ship a CLI change that adds Arity = ZeroOrOne (and a sensible implicit value) to the Option<string?> path when the underlying input is Boolean, then re-test — but the docs should not assert behavior the released CLIs don't deliver.

Passed checks (8)

#	Check	Result
1	aspire-resource.mdx renders the new "Built-in parameter commands" section with a heading anchor #built-in-parameter-commands	✅ Anchor present and the whats-new LearnMore link target resolves to it
2	Both legacy aliases mentioned (parameter-set, parameter-delete) render in HTML	✅
3	aspire resource mydb-password set-parameter --value "MyStr0ngP@ssword" (no save flag)	✅ "Resource 'mydb-password' set successfully."
4	aspire resource mydb-password set-parameter --value "..." --save-to-user-secrets true	✅
5	aspire resource mydb-password delete-parameter (no flags) after a value is set	✅ "Resource 'mydb-password' deleted successfully."
6	aspire resource mydb-password delete-parameter --delete-from-user-secrets true	✅
7	Legacy aspire resource mydb-password parameter-set --value "..." and parameter-delete invocations	✅ Both still work
8	aspire resource mydb-password set-parameter --help lists the command's options	✅ Help shows --value <value> and --save-to-user-secrets, matching the documented per-command-help flow

Knowledge gap (optional)

The set-parameter --help output shows the --save-to-user-secrets description with literal Markdown-link syntax:

--save-to-user-secrets    Save value to [user secrets](https://aka.ms/aspire/user-secrets) for future use.

This is a CLI/source-resource issue (the description text in InteractionStrings is rendered verbatim in a terminal), not a docs PR issue. Flagging only because a "blind user" reading the docs will be told to use --help and may be confused by the rendered output. Out of scope for this PR.

Houskeeping

• The other Phase A claims that depend on dynamic-loading semantics (defaults, "preserve existing saved state") were not directly exercised in Phase B since they require a multi-run user-secrets persistence test; source-side verification is in C-6 above.
• Recommended follow-up if option (a) above is chosen: also update the on-page Aside (line 152-154) is fine as-is; only the bare-flag rule and the affected example/cell need to change.

---

_{Automated review by IEvangelist (docs-from-code workflow). Phase A executed against microsoft/aspire@release/13.4 at 2574ef57e; Phase B executed against worktree head 17bef8f6 using the doc-tester skill and locally-installed CLIs.}

[IEvangelist]

Applied the review-level bare-flag correction in 6504c21. The docs now require explicit true/false values for --save-to-user-secrets and --delete-from-user-secrets, matching microsoft/aspire@2574ef57e97fc393aff67592fd442afca6a6d02f on release/13.4.

[IEvangelist]

Automated docs accuracy review

Source of truth: microsoft/aspire @ release/13.4 (commit becb48e2d61099e35ae336d527d3875e928d6594)

Phase A — Claim verification: 10 claims extracted · 8 verified · 1 contradicted (asserted in 2 places) · 0 unverifiable · 1 narrative

Phase B — Doc tester run: 2 doc routes targeted · 1 rendered cleanly, 1 could not render locally · 0 critical, 2 warnings, 1 knowledge gap

---

Phase A — Claim verification

Contradicted claim (commented inline on both occurrences)

Boolean options for these commands require an explicit true or false value (and the parallel wording in the What's New page) is contradicted by the CLI implementation.

In src/Aspire.Cli/Commands/ResourceCommand.cs, boolean command arguments are bound to Option<bool> with ArgumentArity.ZeroOrOne (lines 396–418), with no custom parser that requires a value. The existing test ResourceCommand_ForwardsKebabCaseEqualsAndBareBooleanArgumentsByName confirms this — it parses configure --timeout-milliseconds=500 --proxy and asserts the bare --proxy flag is forwarded as "true" (line 863).

So in practice all four of the following work and yield the same backend value:

• --save-to-user-secrets true → "true"
• --save-to-user-secrets=true → "true"
• --save-to-user-secrets → "true" (bare flag, per the test above)
• --save-to-user-secrets false → "false"

The docs say only the first two forms are valid. Two reasonable fixes:

1. Soften the wording to "we recommend passing an explicit true or false value to make scripts self-documenting" (descriptive, not prescriptive); or
2. Drop the sentence and let the --save-to-user-secrets [true|false] syntax in the table communicate the intended usage.

If the product actually intends to require an explicit value, the CLI implementation needs to enforce that (e.g., a custom parser that rejects bare flags) — but that's a product change, not a docs change.

Verified claims

8 verified claims (click to expand)

#	Page	Claim	Evidence in microsoft/aspire@becb48e2
1	aspire-resource.mdx	set-parameter and delete-parameter are valid resource command names	src/Aspire.Hosting/ApplicationModel/KnownResourceCommands.cs lines 36 (SetParameterCommand = "set-parameter") and 41 (DeleteParameterCommand = "delete-parameter")
2	aspire-resource.mdx	set-parameter accepts legacy alias parameter-set	KnownResourceCommands.cs line 46 (LegacyParameterSetCommand = "parameter-set"); test ResourceCommand_LegacyParameterCommandName_UsesCurrentCommandMetadata parses resource greeting parameter-set --value "..."
3	aspire-resource.mdx	delete-parameter accepts legacy alias parameter-delete	KnownResourceCommands.cs line 47 (LegacyParameterDeleteCommand = "parameter-delete")
4	aspire-resource.mdx	--value <value> is required for set-parameter	src/Aspire.Hosting/Orchestrator/ParameterProcessor.cs line 200 (required: true on the value input)
5	aspire-resource.mdx	--save-to-user-secrets [true|false] defaults to preserving existing saved state	ParameterProcessor.cs lines 242–253: LoadCallback sets Input.Value = "true" only when the persisted parameter section has data; SetParameterCoreAsync line 429 then treats a missing input as false (no save)
6	aspire-resource.mdx	--delete-from-user-secrets true is what triggers removal from user secrets	ParameterProcessor.cs lines 442–455: the DeleteFromUserSecrets branch runs only when bool.TryParse(...) returns true
7	aspire-resource.mdx	aspire resource <resource> <command> --help shows per-command help	ResourceCommand.cs lines 728–748 (TryGetResourceOnlyHelp) and 756–780 (WriteResourceCommandHelp)
8	aspire-resource.mdx & aspire-13-4.mdx	CLI option flags --save-to-user-secrets, --delete-from-user-secrets, --value are derived from input names SaveToUserSecrets, DeleteFromUserSecrets, Value via ToKebabCase	ResourceCommand.cs line 389 (var optionName = ToKebabCase(argument.Name);) and 552; ParameterProcessor.cs lines 30–32

Narrative (not verified against code)

• The <Aside type="note"> "The canonical command names changed in Aspire 13.4. parameter-set was renamed to set-parameter and parameter-delete was renamed to delete-parameter." This is a release-history claim; the canonical/legacy mapping does exist on the release/13.4 branch (verified) but I did not check the prior release/13.3 branch to confirm the "changed in 13.4" timing.

---

Phase B — Doc tester run (blind to source)

Pages exercised:

Route	Outcome
/reference/cli/commands/aspire-resource/	Rendered cleanly with PR head content overlaid; new "Built-in parameter commands" section parses, tables render, anchor #built-in-parameter-commands resolves, /fundamentals/external-parameters/ link returns 200
/whats-new/aspire-13-4/	Could not render locally — this PR adds new lines to a page that does not exist on the worktree's base branch, and the supporting topic registration / sibling pages from release/13.4 are not present. Reviewed raw MDX content instead. The LearnMore anchor #built-in-parameter-commands is confirmed valid (the heading is present in the rendered aspire-resource page above)

Critical issues

None.

Warnings

W1. "Require explicit true or false" reads as prescriptive but the CLI accepts the bare flag

Both pages tell a new user reading the docs in isolation that they MUST pass an explicit value. As a tester following the docs literally, I would never discover that aspire resource mydb-password set-parameter --value "x" --save-to-user-secrets (no true after the flag) also saves to user secrets. This is the same concern that Phase A surfaced from the source side — flagging it here too because a doc-tester user has no way to know the implementation is more permissive than the documentation says. (See contradicted claim above for the suggested wording change.)

W2. parameter-set / parameter-delete aliases are mentioned in passing but never shown in an example

A user who only skims the option tables and code blocks would miss that aspire resource mydb-password parameter-set --value "x" still works. The Aside at the end captures this, but adding one comment line like # Legacy alias: equivalent to set-parameter above next to the first code block (or a single example using the legacy name) would make the back-compat story discoverable to readers who skip the Aside.

Knowledge gaps

K1. Default behavior of --save-to-user-secrets when omitted

The cell reads "Defaults to preserving any existing saved state." Without reading source, I had to interpret what "preserving" means: does it leave whatever is on disk alone (no write at all), or does it re-save the new value to whatever sink already held the old one? The Phase A verification showed it's the latter — when the parameter was previously persisted, the new value is also persisted; when it wasn't, it isn't. One short example block would clarify:

# First call — no existing saved state, --save-to-user-secrets omitted, value is NOT persisted to user secrets
aspire resource mydb-password set-parameter --value "MyStr0ngP@ssword"

# Later call — because the previous value was saved, omitting --save-to-user-secrets keeps saving the new value
aspire resource mydb-password set-parameter --value "MyOtherP@ssword"

Passed checks

• /reference/cli/commands/aspire-resource/ renders with no MDX/JSX errors
• #built-in-parameter-commands anchor on the resource page exists and is reachable from the What's New LearnMore link
• /fundamentals/external-parameters/ link target returns 200
• Tables, code blocks, and the <Aside type="note"> render correctly
• The four new code examples on the What's New page (cache seed-data, set-parameter, delete-parameter, set-parameter --help) are syntactically consistent with the resource page's examples

---

Automated review. Worktree restored; no files modified.

[IEvangelist]

Contradicted by source code. This sentence reads as prescriptive, but Option<bool> in src/Aspire.Cli/Commands/ResourceCommand.cs (lines 396–418) is created with ArgumentArity.ZeroOrOne and no custom parser, so the bare flag is accepted and treated as true. The test ResourceCommand_ForwardsKebabCaseEqualsAndBareBooleanArgumentsByName confirms --proxy alone forwards as "true".

Suggested rewording (descriptive, matches actual behavior):

We recommend passing an explicit true or false value (for example, --save-to-user-secrets true) so scripts are self-documenting. A bare flag like --save-to-user-secrets is equivalent to --save-to-user-secrets true.

Or simply drop the sentence and let the --save-to-user-secrets [true|false] syntax in the parameters table do the talking.

[IEvangelist]

I rechecked this against microsoft/aspire@e13850995727767ba26088932630342417745f40 on release/13.4, and this requested wording change is contradicted for these specific parameter-command options.

src/Aspire.Hosting/Orchestrator/ParameterProcessor.cs:228-253 gives SaveToUserSecrets a DynamicLoading callback. src/Aspire.Cli/Commands/ResourceCommand.cs:390-411 then treats any dynamic input as parseAsString and creates an Option<string?> with Arity = ArgumentArity.ExactlyOne. The bare-flag ArgumentArity.ZeroOrOne branch at ResourceCommand.cs:414-418 only applies when the option is actually an Option<bool>.

The cited ResourceCommand_ForwardsKebabCaseEqualsAndBareBooleanArgumentsByName test covers a non-dynamic proxy Boolean argument, so it doesn't apply to --save-to-user-secrets. The docs' explicit true/false requirement is correct as written.

[IEvangelist]

Contradicted by source code. Same issue as the parallel sentence in aspire-resource.mdx. The boolean flags in this section are bound with ArgumentArity.ZeroOrOne and no validator, so a bare --delete-from-user-secrets is accepted and parsed as true. See ResourceCommand_ForwardsKebabCaseEqualsAndBareBooleanArgumentsByName.

Suggested rewording:

Pass an explicit true or false value to boolean resource command options (for example, --delete-from-user-secrets true) to keep scripts self-documenting.

[IEvangelist]

I rechecked this against microsoft/aspire@e13850995727767ba26088932630342417745f40 on release/13.4, and the explicit-value wording is correct for this parameter-command option.

src/Aspire.Hosting/Orchestrator/ParameterProcessor.cs:268-289 gives DeleteFromUserSecrets a DynamicLoading callback. src/Aspire.Cli/Commands/ResourceCommand.cs:390-411 treats dynamic inputs as strings and creates an Option<string?> with Arity = ArgumentArity.ExactlyOne; the bare-flag ArgumentArity.ZeroOrOne branch at ResourceCommand.cs:414-418 only applies to non-dynamic Option<bool> arguments.

The cited bare-boolean test uses a non-dynamic proxy Boolean argument, so it doesn't verify --delete-from-user-secrets. The docs' explicit true/false requirement is correct as written.

[IEvangelist]

I rechecked this against microsoft/aspire@e13850995727767ba26088932630342417745f40 on release/13.4, and the explicit-value wording is correct for this parameter-command option.

src/Aspire.Hosting/Orchestrator/ParameterProcessor.cs:268-289 gives DeleteFromUserSecrets a DynamicLoading callback. src/Aspire.Cli/Commands/ResourceCommand.cs:390-411 treats dynamic inputs as strings and creates an Option<string?> with Arity = ArgumentArity.ExactlyOne; the bare-flag ArgumentArity.ZeroOrOne branch at ResourceCommand.cs:414-418 only applies to non-dynamic Option<bool> arguments.

The cited bare-boolean test uses a non-dynamic proxy Boolean argument, so it doesn't verify --delete-from-user-secrets. The docs' explicit true/false requirement is correct as written.

[IEvangelist]

Regarding the latest review-level change request (PRR_kwDOQK_VN88AAAABBia1lQ): I rechecked the current release/13.4 source and am not applying the suggested bare-flag wording.

microsoft/aspire@e13850995727767ba26088932630342417745f40 shows these parameter-command options are dynamically loaded (ParameterProcessor.cs:228-253 and 268-289). ResourceCommand.cs:390-411 therefore parses them as Option<string?> with ArgumentArity.ExactlyOne; the Option<bool> bare-flag path at ResourceCommand.cs:414-418 does not apply. The generic bare-boolean test cited in the review uses a non-dynamic proxy argument, so it doesn't contradict the current docs text.

I left the inline threads unresolved so the reviewer can confirm or push back.

[IEvangelist]

Regarding the latest review-level change request (PRR_kwDOQK_VN88AAAABBia1lQ): I rechecked the current release/13.4 source and am not applying the suggested bare-flag wording.

microsoft/aspire@e13850995727767ba26088932630342417745f40 shows these parameter-command options are dynamically loaded (ParameterProcessor.cs:228-253 and 268-289). ResourceCommand.cs:390-411 therefore parses them as Option<string?> with ArgumentArity.ExactlyOne; the Option<bool> bare-flag path at ResourceCommand.cs:414-418 does not apply. The generic bare-boolean test cited in the review uses a non-dynamic proxy argument, so it doesn't contradict the current docs text.

I left the inline threads unresolved so the reviewer can confirm or push back.