Restructure CLI resource commands under 'aspire resource' by JamesNK · Pull Request #14918 · microsoft/aspire

JamesNK · 2026-03-03T22:08:56Z

Description

Restructure Aspire CLI resource commands from a flat structure (aspire start/stop/restart <resource>, aspire command <resource> <command>) to a nested structure under a unified aspire resource command (aspire resource <resource> start/stop/restart/<command>).

aspire start and aspire stop are now apphost-only commands
aspire resource <resource> <command> handles all resource operations (start, stop, restart, and custom commands)
Deleted RestartCommand and ResourceCommandBase — their logic is folded into ResourceCommand via a well-known command mapping
Updated VS Code extension tree provider to use the new command syntax
Updated resource strings and 26 XLF localization files
Moved resource-related tests from StartCommandTests to ResourceCommandTests

Fixes #14797

Checklist

Is this feature complete?
- Yes. Ready to ship.
- No. Follow-up changes expected.
Are you including unit tests for the changes and scenario tests if relevant?
- Yes
- No
Did you add public API?
- Yes
  - If yes, did you have an API Review for it?
    - Yes
    - No
  - Did you add <remarks /> and <code /> elements on your triple slash comments?
    - Yes
    - No
- No
Does the change make any security assumptions or guarantees?
- Yes
  - If yes, have you done a threat model and had a security review?
    - Yes
    - No
- No
Does the change require an update in our Aspire docs?
- Yes
  - Link to aspire.dev issue:
    - New issue
- No

github-actions · 2026-03-03T22:09:05Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 14918

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 14918"

Copilot

Pull request overview

This PR restructures Aspire CLI resource operations from top-level commands (start/stop/restart, command) into a unified nested aspire resource <resource> <command> model, and updates the VS Code extension and tests accordingly.

Changes:

Consolidates resource lifecycle operations (start/stop/restart/custom) under aspire resource, removing RestartCommand and ResourceCommandBase.
Makes aspire start / aspire stop AppHost-only commands and updates CLI wiring plus unit tests.
Updates VS Code extension command invocations and refreshes related RESX/XLF localization resources.

Reviewed changes

Copilot reviewed 40 out of 42 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
tests/Aspire.Cli.Tests/Utils/CliTestHelper.cs	Removes `RestartCommand` DI registration in CLI tests.
tests/Aspire.Cli.Tests/Commands/StartCommandTests.cs	Removes resource-argument tests now that `start` is AppHost-only.
tests/Aspire.Cli.Tests/Commands/RestartCommandTests.cs	Deletes tests for removed `RestartCommand`.
tests/Aspire.Cli.Tests/Commands/ResourceCommandTests.cs	Updates parsing from `command` → `resource` and adds coverage for well-known/backchannel resource command names.
src/Aspire.Cli/Resources/xlf/StopCommandStrings.zh-Hant.xlf	Updates stop description and removes resource-argument-related string.
src/Aspire.Cli/Resources/xlf/StopCommandStrings.zh-Hans.xlf	Updates stop description and removes resource-argument-related string.
src/Aspire.Cli/Resources/xlf/StopCommandStrings.tr.xlf	Updates stop description and removes resource-argument-related string.
src/Aspire.Cli/Resources/xlf/StopCommandStrings.ru.xlf	Updates stop description and removes resource-argument-related string.
src/Aspire.Cli/Resources/xlf/StopCommandStrings.pt-BR.xlf	Updates stop description and removes resource-argument-related string.
src/Aspire.Cli/Resources/xlf/StopCommandStrings.pl.xlf	Updates stop description and removes resource-argument-related string.
src/Aspire.Cli/Resources/xlf/StopCommandStrings.ko.xlf	Updates stop description and removes resource-argument-related string.
src/Aspire.Cli/Resources/xlf/StopCommandStrings.ja.xlf	Updates stop description and removes resource-argument-related string.
src/Aspire.Cli/Resources/xlf/StopCommandStrings.it.xlf	Updates stop description and removes resource-argument-related string.
src/Aspire.Cli/Resources/xlf/StopCommandStrings.fr.xlf	Updates stop description and removes resource-argument-related string.
src/Aspire.Cli/Resources/xlf/StopCommandStrings.es.xlf	Updates stop description and removes resource-argument-related string.
src/Aspire.Cli/Resources/xlf/StopCommandStrings.de.xlf	Updates stop description and removes resource-argument-related string.
src/Aspire.Cli/Resources/xlf/StopCommandStrings.cs.xlf	Updates stop description and removes resource-argument-related string.
src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.zh-Hant.xlf	Updates resource command descriptions and removes restart/start resource-arg strings.
src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.zh-Hans.xlf	Updates resource command descriptions and removes restart/start resource-arg strings.
src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.tr.xlf	Updates resource command descriptions and removes restart/start resource-arg strings.
src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.ru.xlf	Updates resource command descriptions and removes restart/start resource-arg strings.
src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.pt-BR.xlf	Updates resource command descriptions and removes restart/start resource-arg strings.
src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.pl.xlf	Updates resource command descriptions and removes restart/start resource-arg strings.
src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.ko.xlf	Updates resource command descriptions and removes restart/start resource-arg strings.
src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.ja.xlf	Updates resource command descriptions and removes restart/start resource-arg strings.
src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.it.xlf	Updates resource command descriptions and removes restart/start resource-arg strings.
src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.fr.xlf	Updates resource command descriptions and removes restart/start resource-arg strings.
src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.es.xlf	Updates resource command descriptions and removes restart/start resource-arg strings.
src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.de.xlf	Updates resource command descriptions and removes restart/start resource-arg strings.
src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.cs.xlf	Updates resource command descriptions and removes restart/start resource-arg strings.
src/Aspire.Cli/Resources/StopCommandStrings.resx	Aligns stop description with AppHost-only behavior; removes `AllAndResourceMutuallyExclusive`.
src/Aspire.Cli/Resources/StopCommandStrings.Designer.cs	Removes generated accessor for `AllAndResourceMutuallyExclusive`.
src/Aspire.Cli/Resources/ResourceCommandStrings.resx	Updates resource command descriptions; removes restart/start resource-arg and option-validity strings.
src/Aspire.Cli/Resources/ResourceCommandStrings.Designer.cs	Removes generated accessors for deleted ResourceCommandStrings entries.
src/Aspire.Cli/Program.cs	Removes `RestartCommand` service registration.
src/Aspire.Cli/Commands/StopCommand.cs	Removes resource-argument support; stop now targets AppHost (or `--all`).
src/Aspire.Cli/Commands/StartCommand.cs	Removes resource-start behavior; `start` now launches AppHost detached.
src/Aspire.Cli/Commands/RootCommand.cs	Removes `RestartCommand` from root command wiring.
src/Aspire.Cli/Commands/RestartCommand.cs	Deletes `RestartCommand` implementation.
src/Aspire.Cli/Commands/ResourceCommandBase.cs	Deletes now-obsolete shared base for resource lifecycle commands.
src/Aspire.Cli/Commands/ResourceCommand.cs	Renames command to `resource` and adds mapping for friendly names (start/stop/restart) to backchannel commands.
extension/src/views/AspireAppHostTreeProvider.ts	Updates extension to invoke `aspire resource "<resource>" <command>` instead of `aspire command ...` / `aspire start/stop ...`.

Files not reviewed (2)

src/Aspire.Cli/Resources/ResourceCommandStrings.Designer.cs: Language not supported
src/Aspire.Cli/Resources/StopCommandStrings.Designer.cs: Language not supported

src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.de.xlf

src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.cs.xlf

src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.zh-Hans.xlf

src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.ru.xlf

src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.pt-BR.xlf

src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.zh-Hant.xlf

src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.tr.xlf

src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.pl.xlf

src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.ja.xlf

src/Aspire.Cli/Resources/xlf/ResourceCommandStrings.it.xlf

…source'

… tests

JamesNK · 2026-03-03T22:58:23Z

New help output:

The Aspire CLI can be used to create, run, and publish Aspire-based applications.

Usage:
  aspire <command> [options]

App commands:
  add [<integration>]              Add a hosting integration to the apphost.
  init                             Initialize Aspire in an existing codebase.
  new                              Create a new app from an Aspire starter template.
  ps                               List running apphosts.
  run                              Run an Aspire AppHost interactively for development.
  start                            Start an apphost in the background.
  stop                             Stop a running apphost.
  update                           Update integrations in the Aspire project. (Preview)

Resource management:
  resource <resource> <command>    Execute a command on a resource (e.g. start, stop, restart).
  wait <resource>                  Wait for a resource to reach a target status.

Monitoring:
  describe [<resource>]            Describe resources in a running apphost.
  logs [<resource>]                Display logs from resources in a running apphost.
  otel                             View OpenTelemetry data (logs, spans, traces) from a running apphost.

Deployment:
  deploy                           Deploy an apphost to its deployment targets. (Preview)
  do <step>                        Execute a specific pipeline step and its dependencies. (Preview)
  publish                          Generate deployment artifacts for an apphost. (Preview)

Tools & configuration:
  agent                            Manage AI agent specific setup.
  cache                            Manage disk cache for CLI operations.
  config                           Manage CLI configuration including feature flags.
  docs                             Browse and search Aspire documentation from aspire.dev.
  doctor                           Diagnose Aspire environment issues and verify setup.
  secret                           Manage AppHost user secrets.

Options:
  -h, /h                 Show help and usage information
  -v, --version          Show version information
  -l, --log-level        Set the minimum log level for console output (Trace, Debug, Information, Warning, Error,
                         Critical).
  --non-interactive      Run the command in non-interactive mode, disabling all interactive prompts and spinners.
  --nologo               Suppress the startup banner and telemetry notice.
  --banner               Display the animated Aspire CLI welcome banner.
  --wait-for-debugger    Wait for a debugger to attach before executing the command.

Use "aspire <command> --help" for more information about a command.

github-actions · 2026-03-03T23:26:14Z

🎬 CLI E2E Test Recordings

The following terminal recordings are available for commit 91003d2:

Test	Recording
AddPackageInteractiveWhileAppHostRunningDetached	▶️ View Recording
AddPackageWhileAppHostRunningDetached	▶️ View Recording
AgentCommands_AllHelpOutputs_AreCorrect	▶️ View Recording
AgentInitCommand_MigratesDeprecatedConfig	▶️ View Recording
AgentInitCommand_WithMalformedMcpJson_ShowsErrorAndExitsNonZero	▶️ View Recording
AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	▶️ View Recording
Banner_DisplayedOnFirstRun	▶️ View Recording
Banner_DisplayedWithExplicitFlag	▶️ View Recording
CreateAndDeployToDockerCompose	▶️ View Recording
CreateAndDeployToDockerComposeInteractive	▶️ View Recording
CreateAndPublishToKubernetes	▶️ View Recording
CreateAndRunAspireStarterProject	▶️ View Recording
CreateAndRunAspireStarterProjectWithBundle	▶️ View Recording
CreateAndRunJsReactProject	▶️ View Recording
CreateAndRunPythonReactProject	▶️ View Recording
CreateAndRunTypeScriptStarterProject	▶️ View Recording
CreateEmptyAppHostProject	▶️ View Recording
CreateStartAndStopAspireProject	▶️ View Recording
CreateStartWaitAndStopAspireProject	▶️ View Recording
CreateTypeScriptAppHostWithViteApp	▶️ View Recording
DescribeCommandResolvesReplicaNames	▶️ View Recording
DescribeCommandShowsRunningResources	▶️ View Recording
DetachFormatJsonProducesValidJson	▶️ View Recording
DoctorCommand_DetectsDeprecatedAgentConfig	▶️ View Recording
DoctorCommand_WithSslCertDir_ShowsTrusted	▶️ View Recording
DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	▶️ View Recording
LogsCommandShowsResourceLogs	▶️ View Recording
PsCommandListsRunningAppHost	▶️ View Recording
PsFormatJsonOutputsOnlyJsonToStdout	▶️ View Recording
SecretCrudOnDotNetAppHost	▶️ View Recording
SecretCrudOnTypeScriptAppHost	▶️ View Recording
StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	▶️ View Recording
StopAllAppHostsFromAppHostDirectory	▶️ View Recording
StopAllAppHostsFromUnrelatedDirectory	▶️ View Recording
StopNonInteractiveMultipleAppHostsShowsError	▶️ View Recording
StopNonInteractiveSingleAppHost	▶️ View Recording
StopWithNoRunningAppHostExitsSuccessfully	▶️ View Recording

_{📹 Recordings uploaded automatically from CI run #22646594252}

* Restructure CLI resource commands under 'aspire resource' * Detect bare-word args in 'aspire start' and guide users to 'aspire resource' * Remove TreatUnmatchedTokensAsErrors=false from StartCommand * Add tests that 'aspire start/stop myresource' fail * Restore unmatched token forwarding in StartCommand and add forwarding tests * Move StartDescription to StartCommandStrings

Restructure CLI resource commands under 'aspire resource'

63c4655

Copilot AI review requested due to automatic review settings March 3, 2026 22:08

Copilot started reviewing on behalf of JamesNK March 3, 2026 22:09 View session

Copilot AI reviewed Mar 3, 2026

View reviewed changes

JamesNK changed the base branch from main to release/13.2 March 3, 2026 22:14

JamesNK added 5 commits March 4, 2026 06:19

Detect bare-word args in 'aspire start' and guide users to 'aspire re…

5dd455c

…source'

Remove TreatUnmatchedTokensAsErrors=false from StartCommand

13e4d5d

Add tests that 'aspire start/stop myresource' fail

86290a8

Restore unmatched token forwarding in StartCommand and add forwarding…

f0d0759

… tests

Move StartDescription to StartCommandStrings

91003d2

JamesNK added the area-cli label Mar 3, 2026

JamesNK requested review from davidfowl, mitchdenny and sebastienros March 3, 2026 23:08

davidfowl approved these changes Mar 4, 2026

View reviewed changes

davidfowl merged commit e6519b0 into release/13.2 Mar 4, 2026
758 of 761 checks passed

davidfowl deleted the jamesnk/command-resource-refactor branch March 4, 2026 00:13

dotnet-policy-service bot added this to the 13.2 milestone Mar 4, 2026

github-actions bot mentioned this pull request Mar 4, 2026

[13.2-burndown] Daily Burndown Report - March 4, 2026 #14940

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Restructure CLI resource commands under 'aspire resource'#14918

Restructure CLI resource commands under 'aspire resource'#14918
davidfowl merged 6 commits intorelease/13.2from
jamesnk/command-resource-refactor

JamesNK commented Mar 3, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 3, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JamesNK commented Mar 3, 2026

Uh oh!

github-actions bot commented Mar 3, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

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

Uh oh!

Description

Checklist

Uh oh!

github-actions bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JamesNK commented Mar 3, 2026

Uh oh!

github-actions bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎬 CLI E2E Test Recordings

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

JamesNK commented Mar 3, 2026 •

edited

Loading

github-actions bot commented Mar 3, 2026 •

edited

Loading

github-actions bot commented Mar 3, 2026 •

edited

Loading