[docs] Update aspire do --list-steps docs to require step argument

[aspire-repo-bot]

Documents changes from microsoft/aspire#17543.
@mitchdenny

Why this PR is needed

The aspire do command validator was tightened in microsoft/aspire#17543 so that --list-steps always requires a step argument. Previously, running aspire do --list-steps (without a step) would launch the AppHost, race ahead executing the full pipeline, and then crash with InvalidOperationException: Sequence contains more than one matching element. The fix makes the CLI emit a friendly, localized error instead:

The 'step' argument is required when using --list-steps. Specify the step you want to inspect, for example: 'aspire do deploy --list-steps' or 'aspire do publish --list-steps'.

The existing docs showed aspire do --list-steps (no step) as a valid command. This PR corrects that.

Target branch

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

Changes

Updated src/frontend/src/content/docs/reference/cli/commands/aspire-do.mdx:

• Changed the --list-steps bullet in the "Discovering available steps" section to reflect the new requirement: aspire do <step> --list-steps.
• Updated the "Quick listing with --list-steps" subsection to explain that a step argument is required and to show aspire do deploy --list-steps as the example.
• Updated the "Quickly list the steps" example in the Examples section to use aspire do deploy --list-steps and to note that omitting the step argument returns a friendly error.

Files modified

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

Generated by PR Documentation Check for issue #17543 · ● 9.2M · ◷

[Copilot]

Pull request overview

Updates the aspire do CLI reference docs to reflect the validator change where --list-steps requires a <step> argument, preventing the previously confusing failure mode when omitting the step.

Changes:

• Updated the “Discovering available steps” guidance to use aspire do <step> --list-steps.
• Revised the “Quick listing with --list-steps” section to state the step requirement and use deploy as the example.
• Updated the Examples section to use the new invocation and mention the friendly error when omitting the step.

---

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

[IEvangelist]

Docs accuracy review

Source of truth: microsoft/aspire@cc4b7eaf (release/13.4, fetched 2026-05-29)
PR head: b320952256e969554a83fa3cdb4ecf0554ee8970

Verdict	Count
verified	3
verified-with-nuance	2
unverifiable	0
contradicted	0

Verdict: COMMENT. The new required-step-argument guidance is accurate, but the surrounding prose now claims aspire do <step> --list-steps "lists every step in the pipeline" — actually it filters the listing to the target step's transitive dependency closure.

Doc-tester (UX) notes

A new user copying aspire do deploy --list-steps from this page will succeed and will see a listing that looks exhaustive in most realistic pipelines, because the deploy step usually transitively depends on everything. But:

• If they then try aspire do parameter-prompt --list-steps on the same pipeline (e.g., because they only care about parameter setup), they'll get a much smaller listing — only parameter-prompt itself — and there's nothing on the page that primes them for that scope difference.
• The pre-existing aspire deploy --list-steps, aspire publish --list-steps, and aspire destroy --list-steps flows (also mentioned in this section) behave the same way: their listings are scoped to the deploy / publish / destroy step's transitive deps, not literally "every step".

This affects two specific sentences added by this PR; flagged inline below.

Verified claims (with evidence)

#	Claim	Evidence
1	"The --list-steps option requires a step argument when used with aspire do."	src/Aspire.Cli/Commands/DoCommand.cs:34-54 Validators.Add(...) — when listSteps is true and the step argument is empty, calls result.AddError(DoCommandStrings.ListStepsRequiresStep).
2	"Omitting it returns a friendly error that suggests the correct form."	DoCommandStrings.resx:144-145 ListStepsRequiresStep = "The 'step' argument is required when using --list-steps. Example: 'aspire do deploy --list-steps'. Common starting steps are 'build', 'publish' and 'deploy'. ..."
3	Example aspire do deploy --list-steps.	DoCommand.cs:124 GetTargetStepName(parseResult) => parseResult.GetValue(_stepArgument) flows the step name into PipelineCommandBase.cs:274-275 → backchannel.GetPipelineStepsAsync(targetStep, ...).

Verified-with-nuance

#	Claim	Nuance
4	"Pass the name of the step you want to inspect ... to list every step in the pipeline along with its direct dependencies and tags."	src/Aspire.Hosting/Backchannel/AppHostRpcTarget.cs:260-273 — when a step is supplied, resolvedSteps = DistributedApplicationPipeline.ComputeTransitiveDependencies(targetStep, stepsByName). The listing is scoped to the target step's transitive dependency closure, not every step in the pipeline. In typical pipelines deploy reaches everything; in atypical ones (or with a leaf step like parameter-prompt) the listing is much smaller.
5	"Pass any well-known step name (such as deploy or publish) to display a compact view of every step with its dependencies and tags."	Same nuance as #4. The same backchannel method (GetPipelineStepsAsync) is the only path.