[docs] Update aspire ps and resource command docs for CLI log path

[aspire-repo-bot]

Documents changes from microsoft/aspire#17168 (@JamesNK).

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

Why this PR is needed

PR microsoft/aspire#17168 introduced two user-facing changes to the Aspire CLI:

1. aspire ps — new LOGS column: The table output now includes a conditionally-displayed LOGS column showing a clickable link to the CLI log file for each AppHost. This column only appears when at least one running AppHost has a log path. The JSON output (--format Json) now includes a logFilePath field.

2. Failed resource commands — log file paths: When a resource command executed via aspire resource fails, the CLI now prints the paths to both the CLI log file and the AppHost log file so users can find detailed diagnostics.

Neither of these changes was documented on the existing aspire ps or aspire resource reference pages.

Summary of changes

• src/frontend/src/content/docs/reference/cli/commands/aspire-ps.mdx — updated:

  • Added LOGS and SDK columns to the table description
  • Updated the --format option description to mention the new logFilePath JSON field
  • Replaced the plain-text table example with a bordered table example showing the LOGS column
  • Added logFilePath to the JSON output example, noting it is null when unavailable

• src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx — updated:

  • Added a new "Log file paths on failure" subsection explaining the two log path lines printed when a resource command fails

Files modified

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

Generated by PR Documentation Check for issue #17168 · ● 20.7M · ◷

[Copilot]

Pull request overview

Updates the Aspire CLI reference docs to reflect new log-path related output from aspire ps and failed aspire resource commands, aligning the docs with changes introduced in microsoft/aspire#17168 for the 13.4 release.

Changes:

• Documented new SDK/LOGS columns for aspire ps table output and added logFilePath to the JSON output example.
• Added a new subsection to aspire resource documenting the log file paths printed when a resource command fails.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
src/frontend/src/content/docs/reference/cli/commands/aspire-ps.mdx	Documents aspire ps log-path output in both table and JSON formats, with updated examples.
src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx	Adds documentation for CLI/AppHost log file paths printed on resource-command failure.

---

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

[IEvangelist]

doc-tester review

Generated by running the doc-tester skill against the changed pages on a locally served docs site (Astro frontend launched via aspire start --isolated).

Test environment

• Aspire CLI: 13.4.0-preview.1.26269.1 (closest GA-track build I had available — see knowledge gap below)
• Local docs site: rendered both changed pages and verified all See also links return 200
• Validated against the live behavior of aspire ps, aspire ps --format Json, and several failing aspire resource … invocations

Verdict: 🔴 REQUEST_CHANGES

There is one verifiable correctness gap introduced by this PR (an undocumented JSON property that is the JSON counterpart to a column the PR adds), plus a few minor inconsistencies. Combined with the existing merge conflict against release/13.4, this should not merge as-is.

---

⚠️ Merge conflict against base

gh pr view 991 --json mergeable,mergeStateStatus reports "mergeable":"CONFLICTING","mergeStateStatus":"DIRTY". This PR needs a rebase/merge of release/13.4 before it can be merged. (I did not attempt to resolve conflicts as part of this review.)

---

Findings

🔴 Blocker

B1. New sdkVersion JSON property is not documented (aspire-ps.mdx)

The PR adds a SDK column to the table output, but the JSON property list and JSON example are out of sync with the actual CLI output. Running aspire ps --format Json on 13.4.0-preview.1.26269.1 returns:

{
  "appHostPath": "…\\Aspire.Dev.AppHost.csproj",
  "appHostPid": 86920,
  "sdkVersion": "13.3.0.0",
  "cliPid": 96880,
  "dashboardUrl": "https://localhost:64122/login?t=…"
}

But the doc states:

The JSON output includes an array of AppHost objects with appHostPath, appHostPid, cliPid, logFilePath, and dashboardUrl properties.

sdkVersion is missing from the property list, missing from the JSON example block, and missing from the surrounding prose. Since this PR introduces the SDK column in the table, the JSON property that backs it should be documented in the same PR for parity.

Suggested wording (Options › --format)

The JSON output includes an array of AppHost objects with appHostPath, appHostPid, sdkVersion, cliPid, logFilePath, and dashboardUrl properties. The logFilePath field is null when no log path is available. Defaults to Table.

Suggested JSON example update

[
  {
    "appHostPath": "./src/MyApp.AppHost/MyApp.AppHost.csproj",
    "appHostPid": 12345,
    "sdkVersion": "10.0.100",
    "cliPid": 12340,
    "logFilePath": "~/.aspire/logs/cli_20260516T123456_abc12345.log",
    "dashboardUrl": "https://localhost:17244/login?t=abc123"
  }
]

(Note: I observed "sdkVersion": "13.3.0.0" — a 4-part .NET SDK version string — in real output. The table example uses 10.0.0 (3-part). Please double-check what format ships in 13.4 and use a single representative format consistently across both examples.)

---

🟡 Minor

M1. Description prose still says "process IDs, and dashboard URLs" (aspire-ps.mdx, line 24)

The frontmatter description: was updated to mention "log file paths," but the body prose was not:

The aspire ps command lists all running Aspire AppHost processes. The output includes the AppHost project path, process IDs, and dashboard URLs for each running instance.

Suggested wording

The aspire ps command lists all running Aspire AppHost processes. The output includes the AppHost project path, .NET SDK version, process IDs, log file paths, and dashboard URLs for each running instance.

M2. Column name capitalization inconsistency within the same page (aspire-ps.mdx)

The column-description table uses uppercase, underscored names (PATH, SDK, PID, CLI_PID, LOGS, DASHBOARD), but the actual CLI and the example output added in this PR use title case with spaces (Path, SDK, PID, CLI PID, Logs, Dashboard). This pre-dates the PR for PATH/PID/CLI_PID/DASHBOARD, but the PR adds two new rows (SDK, LOGS) that perpetuate the inconsistency. Consider aligning the column-description table to the rendered column names so the doc looks self-consistent (e.g. Path, SDK, PID, CLI PID, Logs, Dashboard).

M3. Log filename example uses identical cli_ prefix for CLI and AppHost logs (aspire-resource.mdx)

See logs at ~/.aspire/logs/cli_20260516T123456_abc12345.log
See AppHost logs at ~/.aspire/logs/cli_20260516T123456_def67890.log

Both filenames start with cli_, which makes it harder for a reader to distinguish which log is which on disk. If the actual filename pattern really is cli_<timestamp>_<id>.log for both processes, consider adding a brief note that the distinguishing factor is the <id> suffix (and which suffix corresponds to which process). Otherwise, if the AppHost log uses a different naming convention, the example should reflect that. (In my testing of 13.4.0-preview.1.26269.1, my CLI log was cli_20260520T023015_897e9a2b.log and a separate aspire start produced cli_20260520T022747907_detach-child_c2b46032c127445ca78c69f59cefbbe6.log — the prefix is always cli_, but suffixes vary.)

---

🔵 Nits

N1. ~/.aspire/logs/ on Windows. The doc consistently uses ~/.aspire/logs/. On Windows the CLI actually prints C:\Users\<you>\.aspire\logs\…. The tilde notation is fine as a portable convention, but a one-line note such as "(on Windows, this resolves to %USERPROFILE%\.aspire\logs\)" would help Windows readers who land on the page.

N2. Asciinema cast. <AsciinemaPlayer src="/casts/aspire-ps.cast" ... /> is unchanged. If the cast was recorded before the SDK/Logs columns existed, the embedded animation will visibly disagree with the static example in the same page. Worth verifying the cast still reflects what aspire ps shows in 13.4.

N3. No example of the null case. The doc says "The logFilePath property is null when no log path is available for the AppHost," but doesn't show that case. A second object in the JSON example with "logFilePath": null would make the contract concrete.

---

Knowledge gaps (couldn't fully verify)

Per the doc-tester skill, I'm calling out behavior that I could not confirm from the documentation alone using the CLI build I had.

KG1. LOGS column and logFilePath JSON property were not observed in 13.4.0-preview.1.26269.1.

With an active in-scope AppHost that clearly has a log path (aspire start printed Logs: C:\Users\…\.aspire\logs\cli_…log), my aspire ps output rendered only Path | SDK | PID | CLI PID | Dashboard — no Logs column. Likewise, aspire ps --format Json produced no logFilePath field (not even as null).

Most likely explanation: this PR documents behavior shipping in a CLI build newer than 13.4.0-preview.1.26269.1 (microsoft/aspire#17168 referenced in the PR description). Per the doc-tester skill, this is a knowledge gap I should flag rather than silently assume. Could the PR author confirm — ideally with a brief asciinema clip or aspire ps --format Json snippet from the CLI build that includes #17168 — that the rendered output really matches what the doc claims (column appears when one apphost has a log path, JSON includes "logFilePath": "…" or null)?

KG2. See AppHost logs at line was never produced in two failure scenarios I tried.

I triggered two failures with aspire resource …:

1. aspire resource nonexistent-resource stop → only See logs at <path> was printed.
2. aspire resource frontend-hgaehfpz nonexistent-command → only See logs at <path> was printed.

The doc says See AppHost logs at is "only printed when the AppHost log path is known", so it's plausible that both of these scenarios happen to fall outside that condition — but as a new reader, I have no way to construct a scenario that does print it. A concrete repro (e.g., "to see both lines, run … against a running AppHost where …") would make this section much more useful and self-verifying. Without it, a future reader can't tell whether the second line is dead documentation or just rarely-triggered.

---

Suggested verdict if a v2 of this PR fixes B1 and rebases

• Resolve B1 (document sdkVersion in the property list and example).
• Address M1 (update body prose to match the frontmatter description).
• Rebase onto release/13.4 to clear the merge conflict.
• Optionally fold in M2/M3/N1/N2/N3 and KG1/KG2 confirmation while you're in there.

With those done, this PR is otherwise a useful and well-scoped doc update — the new Log file paths on failure section is exactly the kind of "where do I look when this goes wrong" guidance that's worth having in the CLI reference.