Clarify worktree and same-path behavior for --isolated in the CLI reference

Open Beginner friendly
#2,184 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
github, markdown
Domain
cli, documentation

Research direction

Read src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx and aspire-start.mdx, then compare their --isolated descriptions with the related microsoft/aspire clarification. Explain the different-directory requirement, same-path behavior, and any differences between run, start, and run --detach; include a supported side-by-side example. Done when both reference pages clearly cover these points with aligned wording.

Written by the indexing model from the issue text.

Description

documentation

Clarify worktree and same-path behavior for --isolated in the CLI reference

Target: microsoft/aspire.dev

The --isolated descriptions on both reference pages say:

Run in isolated mode with randomized ports and isolated user secrets, allowing multiple instances of the same AppHost to run simultaneously.

Neither explains that those instances must come from different directories, such as separate worktrees/checkouts. That intended contract has now been confirmed.

In a local test, aspire start --apphost apphost.cs --isolated --no-build --non-interactive --format Json stopped the existing VS Code-debugged instance at that path before starting its replacement. This was on macOS with Aspire SDK 17.0.0. We haven't separately reproduced two concurrent foreground aspire run --isolated commands.

Update both reference pages:

  • Say that parallel isolated runs require copies of the same AppHost in different directories, typically separate worktrees/checkouts.
  • Explain what happens when the same command is repeated from the same path.
  • Distinguish run, start, and run --detach if their behavior differs.
  • Include a concrete supported side-by-side example.

Suggested wording:

Run with randomized ports and isolated user secrets, allowing copies of the same AppHost in different directories, such as separate Git worktrees, to run simultaneously. This does not enable multiple concurrent instances from the same AppHost path.

These pages contain their own checked-in descriptions in:

  • src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx
  • src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx

Updating CLI help alone won't update this prose. Keep the wording aligned with the corresponding microsoft/aspire clarification.

Related CLI-help follow-up: microsoft/aspire#22344 covers the command help wording.

Dominant language
MDX
Stars
202
Forks
99
Avg merge
3d 22h
Merged PRs (30d)
138

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/aspire.dev

All issues in microsoft/aspire.dev

Similar issues

More CLI issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.