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

[aspire-repo-bot]

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

Targeting release/13.4 — the latest release branch on microsoft/aspire.dev — because release/13.5 (from the source PR milestone 13.5) does not exist there.

Why this PR is needed

PR microsoft/aspire#17535 tightened the aspire do command validator so that --list-steps always requires a positional step argument. Previously, aspire do --list-steps (without a step) was accepted but caused the AppHost to launch and race ahead executing the full pipeline, which surfaced as InvalidOperationException: Sequence contains more than one matching element. The CLI now emits a friendly, localized error when the step is omitted:

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 (without a step) as a valid example in two places — the "Discovering available steps" section and the "Examples" section. Those examples are now incorrect and would mislead users.

Changes made

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

• Changed the "Quick listing with --list-steps" section to show aspire do deploy --list-steps instead of aspire do --list-steps and added an explanation that the step argument is required.
• Updated the corresponding example in the "Examples" section to use aspire do deploy --list-steps and added a note that omitting the step produces a friendly error.

Files modified

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

Generated by PR Documentation Check for issue #17535 · ● 7.5M · ◷

[Copilot]

Pull request overview

Updates the Aspire CLI aspire do reference docs to reflect the newer validator behavior where --list-steps requires a positional step argument, preventing misleading examples and avoiding the prior “launch AppHost / race” failure mode.

Changes:

• Updated --list-steps examples to use aspire do deploy --list-steps instead of aspire do --list-steps.
• Added explanatory text noting that the step argument is required and that omitting it yields a friendly error.

---

💡 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: b2d8e7be7587369fd7f2e2ea008aeb349085aa8b

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

Verdict: APPROVE. Every claim matches the implementation at release/13.4.

Doc-tester (UX) notes

The doc now matches the validator's expectation: aspire do <step> --list-steps. A user copying the example command aspire do deploy --list-steps will succeed, and a user who omits the step and hits the validator will see exactly the kind of friendly error the prose advertises (The 'step' argument is required when using --list-steps. Example: 'aspire do deploy --list-steps'. Common starting steps are 'build', 'publish' and 'deploy'...).

Verified claims (with evidence)

#	Claim	Evidence
1	"The step argument is required when using --list-steps with aspire do."	src/Aspire.Cli/Commands/DoCommand.cs:34-54 — Validators.Add(...) checks result.GetValue(s_listStepsOption); when true and the step argument is empty, result.AddError(DoCommandStrings.ListStepsRequiresStep). The error fires before the AppHost is launched.
2	"Omitting the step produces a friendly error that suggests concrete examples."	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'. See https://aspire.dev/reference/cli/commands/aspire-do/ for the full list of pipeline steps."
3	Example aspire do deploy --list-steps.	DoCommand.cs:27-32 declares the step argument with Arity = ArgumentArity.ZeroOrOne; the --list-steps option is inherited from PipelineCommandBase. With step = deploy, the validator (:38-41) returns early, so the command proceeds.