Aspire Terminals
Teach an agent to use the right terminal, not to replace every process with a shell.
Honor a project-local .agents/skills/aspire-terminals/SKILL.md when present;
retain the safety and ownership rules below.
Required reference lookup
Before answering or editing, open the reference for the requested surface,
including for read-only questions. This overview is not enough to write correct
terminal code or tape syntax.
- Resource PTYs or REPLs: read resource terminals.
- Dock, prompts, cancellation or headless tools: read
AppHost terminals.
- Any tape question: read tapes and
automation and CLI. Use the actual syntax and
output contracts there, not pseudo-VHS or memory of upstream VHS behavior.
- Include the applicable package/build capability boundary in recommendations.
Source availability and installed-package availability are different facts.
Choose the model before writing code
| Intent |
Pattern |
Owner and lifetime |
| Make an existing orchestrated executable, project or container interactive |
WithTerminal() / withTerminal() |
Resource process and replicas; resource lifecycle owns stop/restart |
| Open an auxiliary shell/tool that remains available after its command returns |
TerminalService + TerminalPlacement.Dock |
AppHost-owned; closing its tab or stopping AppHost disposes it |
| Guide a person through a focused setup/authentication operation |
TerminalService + Dialog + PromptTerminalAsync |
Caller owns the terminal; prompt borrows it; explicit completion/cancellation |
| Drive a terminal-only tool without a dashboard interaction |
TerminalService + None |
Caller owns and disposes the headless process |
| Open an authenticated database/cache client |
Integration WithRepl() / withRepl() |
Built-in command opens a dock terminal; prefer over custom container exec |
WithTerminal changes the resource's actual process execution. It is not an
on-demand side shell. TerminalService launches a separate AppHost-owned process;
it does not implicitly enter a container or become a modeled resource.
Lifecycle checklist for recommendations
When comparing terminal models, explicitly state cleanup for each model you
recommend, including headless alternatives:
- Dock: survives the opening command; do not scope the handle with
await using
in that command. Closing the tab or AppHost shutdown disposes it.
- Dialog and None: the caller disposes both, normally with
await using.
Headless placement does not transfer cleanup responsibility to the service.
- Prompt completion is not terminal disposal: successful
Work closes the
prompt, but the caller still disposes its terminal. Without Work, process exit
does not close the prompt; explicit completion/cancellation is required.
Capability check
- Locate the exact AppHost and inspect its SDK, hosting and integration package
versions. Do not upgrade the project just to make an example compile.
- Use
aspire docs search terminal --non-interactive, then
aspire docs api search <API> --language csharp|typescript --non-interactive.
If docs lag a preview, inspect that exact package's public API/source. A newer
CLI alone does not add hosting APIs to an older AppHost.
WithTerminal/parameterless TS withTerminal exist in Aspire 13.5.
TerminalService, terminal prompts, headless automation, tape playback and the
six integration REPLs below are in the inspected 13.6 development source.
Verify the installed build contains them; do not promise all previews do.
- Direct C# terminal APIs are experimental (
ASPIRETERMINAL001): narrowly pair
#pragma warning disable ASPIRETERMINAL001 with #pragma warning restore ASPIRETERMINAL001. The examined integration WithRepl methods themselves
do not require this suppression.
- General
TerminalService and terminal-prompt APIs are not exported to
TypeScript in this baseline. Do not invent TS equivalents or edit generated
.aspire/modules/. Supported TS entry points are withTerminal() and the
applicable integration's withRepl().
- Check
aspire --version and aspire terminal --help for the installed CLI.
Aspire 13.5 keeps terminal commands behind a feature flag; enable them only
for that CLI line with
aspire config set features.terminalCommandsEnabled true --non-interactive.
Newer CLIs no longer require or support that flag. If a command remains
absent, treat it as unavailable rather than guessing alternative syntax.
The references are qualified against Aspire release/13.6 commit
34db30a7d3733229da64a403dfc4e4e4d7a1a43b (terminal code also present in main
22bee5e1266b7b66ff53008957dde86efb370c79), compared with shipped v13.5.0.
Terminal-command availability guidance also reflects the subsequent
feature-flag removal.
Recheck capabilities against the user's actual build.
Authoring workflow
- Identify which process needs the PTY and whether it should remain visible,
block a focused workflow, or run headlessly. Ask if the lifetime is unclear.
- Read resource terminals for
WithTerminal
and built-in REPLs; read AppHost terminals
for complete dock, manual prompt, automated prompt and headless recipes.
- Keep terminal-specific edits separate from unrelated resource/dependency changes.
Use
aspireify for new general resource wiring and aspire-init if no AppHost
exists. Do not turn a terminal request into a migration or version upgrade.
- Resolve actual executable paths, working directories and OS shell choices.
Use argument lists, not concatenated untrusted shell input. Children inherit
the AppHost environment; add only the necessary overrides.
- Guard AppHost-owned terminal commands with
builder.ExecutionContext.IsRunMode.
Do not launch tools at model-construction time or during publish/deploy.
- Validate the changed code, then route lifecycle work to
aspire-orchestration.
Use the exact AppHost, worktree isolation and bounded resource readiness.
Validate the requested lifetime, cancellation and visible result, not merely
that the AppHost compiled.
Non-negotiable ownership and completion rules
- Terminal types are in
Aspire.Hosting.ApplicationModel, not the old
Aspire.Hosting.Terminals namespace. TerminalService is already registered;
resolve it from built services or command context.Services. Do not construct
it or register another singleton.
- A dock command that should leave a terminal open must not use
await using
for its handle. Start() is nonblocking/idempotent; Show() activates the dock.
Command success means "opened", not "process exited successfully".
- Dialog and headless terminals normally use
await using. Disposing an
AppHost-owned handle stops its process; PromptTerminalAsync does not
dispose it for you.
- Check
IInteractionService.IsAvailable before launching a prompt-owned
process. Noninteractive resource commands can make it false. Do not silently
replace human interaction/approval with headless success.
- A prompt needs the exact registered instance from the same AppHost, with
TerminalPlacement.Dialog. ResourceView is not valid for CreateTerminal.
- With
Work, successful callback completion closes the dialog; observe
TerminalContext.CancellationToken on every wait/input. Cancellation signals
and joins Work; unrelated errors propagate. Without Work, process exit does
not close the prompt: explicitly define completion/cancellation.
- No public
ExitCode or WaitForExitAsync is available on AspireTerminal.
Do not infer success from Start(), delivered keystrokes, prompt visibility,
or disappearance of a process. Assert a meaningful fresh output marker.
- Viewers and automation share input.
--viewer affects sizing ownership,
not read-only authorization. Do not blindly retry non-idempotent input.
- Treat screen output and tapes as sensitive. Do not commit credentials or
capture tokens in transcripts. Tape
Hide is not redaction.
Driving terminals
Read automation and CLI for C# screen/key
operations, owner-aware discovery and interactive attach. Use
tapes for unattended resource-terminal playback: supported
VHS syntax, explicit examples, stdout versus .txt/.ascii checkpoints, and
unsupported output formats. Do not install VHS or assume its whole feature set.
For missing/disconnected terminals, inspect resource state and terminal discovery;
route console logs/traces to aspire-monitoring. Terminal views supplement logs,
not replace them. Publishing a resource does not publish a development PTY or
grant production shell access.
1---2name: aspire-terminals3description: >-4 **WORKFLOW SKILL** - Author and automate Aspire terminals.5 USE FOR: WithTerminal, withTerminal, TerminalService, TerminalLaunchOptions,6 docked terminals, terminal prompts, PromptTerminalAsync, TerminalPlacement,7 AspireTerminalKey, WithRepl, withRepl, aspire terminal ps/attach/tape play,8 VHS tapes for Aspire, or terminal screen/input automation.9 DO NOT USE FOR: generic shell commands, ordinary AppHost resource wiring10 (aspireify), start/stop/wait (aspire-orchestration), logs/traces or browser11 telemetry (aspire-monitoring), deployment (aspire-deployment), or nonterminal12 Interaction Service prompts (aspireify).13 INVOKES: Aspire docs/API lookup, AppHost edits, Aspire terminal CLI;14 aspire-orchestration for lifecycle validation.15 FOR SINGLE OPERATIONS: Choose the terminal owner and lifetime first, then read16 the matching reference.17license: MIT18metadata:19 source: https://skillmd.com/skills/microsoft/aspire-terminals20 author: Microsoft21 version: "0.0.5"22---2324# Aspire Terminals2526Teach an agent to use the right terminal, not to replace every process with a shell.27Honor a project-local `.agents/skills/aspire-terminals/SKILL.md` when present;28retain the safety and ownership rules below.2930## Required reference lookup3132Before answering **or** editing, open the reference for the requested surface,33including for read-only questions. This overview is not enough to write correct34terminal code or tape syntax.3536- Resource PTYs or REPLs: read [resource terminals](references/resource-terminals.md).37- Dock, prompts, cancellation or headless tools: read38 [AppHost terminals](references/apphost-terminals.md).39- Any tape question: read [tapes](references/tapes.md) and40 [automation and CLI](references/automation-and-cli.md). Use the actual syntax and41 output contracts there, not pseudo-VHS or memory of upstream VHS behavior.42- Include the applicable package/build capability boundary in recommendations.43 Source availability and installed-package availability are different facts.4445## Choose the model before writing code4647| Intent | Pattern | Owner and lifetime |48|--------|---------|--------------------|49| Make an existing orchestrated executable, project or container interactive | `WithTerminal()` / `withTerminal()` | Resource process and replicas; resource lifecycle owns stop/restart |50| Open an auxiliary shell/tool that remains available after its command returns | `TerminalService` + `TerminalPlacement.Dock` | AppHost-owned; closing its tab or stopping AppHost disposes it |51| Guide a person through a focused setup/authentication operation | `TerminalService` + `Dialog` + `PromptTerminalAsync` | Caller owns the terminal; prompt borrows it; explicit completion/cancellation |52| Drive a terminal-only tool without a dashboard interaction | `TerminalService` + `None` | Caller owns and disposes the headless process |53| Open an authenticated database/cache client | Integration `WithRepl()` / `withRepl()` | Built-in command opens a dock terminal; prefer over custom container exec |5455`WithTerminal` changes **the resource's actual process execution**. It is not an56on-demand side shell. `TerminalService` launches a separate AppHost-owned process;57it does not implicitly enter a container or become a modeled resource.5859### Lifecycle checklist for recommendations6061When comparing terminal models, explicitly state cleanup for each model you62recommend, including headless alternatives:6364- **Dock:** survives the opening command; do not scope the handle with `await using`65 in that command. Closing the tab or AppHost shutdown disposes it.66- **Dialog and None:** the caller disposes both, normally with `await using`.67 Headless placement does not transfer cleanup responsibility to the service.68- **Prompt completion is not terminal disposal:** successful `Work` closes the69 prompt, but the caller still disposes its terminal. Without `Work`, process exit70 does not close the prompt; explicit completion/cancellation is required.7172## Capability check73741. Locate the exact AppHost and inspect its SDK, hosting and integration package75 versions. Do not upgrade the project just to make an example compile.762. Use `aspire docs search terminal --non-interactive`, then77 `aspire docs api search <API> --language csharp|typescript --non-interactive`.78 If docs lag a preview, inspect that exact package's public API/source. A newer79 CLI alone does not add hosting APIs to an older AppHost.803. `WithTerminal`/parameterless TS `withTerminal` exist in Aspire 13.5.81 `TerminalService`, terminal prompts, headless automation, tape playback and the82 six integration REPLs below are in the inspected **13.6 development source**.83 Verify the installed build contains them; do not promise all previews do.844. Direct C# terminal APIs are experimental (`ASPIRETERMINAL001`): narrowly pair85 `#pragma warning disable ASPIRETERMINAL001` with `#pragma warning restore86 ASPIRETERMINAL001`. The examined integration `WithRepl` methods themselves87 do not require this suppression.885. General `TerminalService` and terminal-prompt APIs are **not exported to89 TypeScript** in this baseline. Do not invent TS equivalents or edit generated90 `.aspire/modules/`. Supported TS entry points are `withTerminal()` and the91 applicable integration's `withRepl()`.926. Check `aspire --version` and `aspire terminal --help` for the installed CLI.93 Aspire 13.5 keeps terminal commands behind a feature flag; enable them only94 for that CLI line with95 `aspire config set features.terminalCommandsEnabled true --non-interactive`.96 Newer CLIs no longer require or support that flag. If a command remains97 absent, treat it as unavailable rather than guessing alternative syntax.9899The references are qualified against Aspire `release/13.6` commit100`34db30a7d3733229da64a403dfc4e4e4d7a1a43b` (terminal code also present in main101`22bee5e1266b7b66ff53008957dde86efb370c79`), compared with shipped `v13.5.0`.102Terminal-command availability guidance also reflects the subsequent103[feature-flag removal](https://github.com/microsoft/aspire/pull/20525).104Recheck capabilities against the user's actual build.105106## Authoring workflow1071081. Identify which process needs the PTY and whether it should remain visible,109 block a focused workflow, or run headlessly. Ask if the lifetime is unclear.1102. Read [resource terminals](references/resource-terminals.md) for `WithTerminal`111 and built-in REPLs; read [AppHost terminals](references/apphost-terminals.md)112 for complete dock, manual prompt, automated prompt and headless recipes.1133. Keep terminal-specific edits separate from unrelated resource/dependency changes.114 Use `aspireify` for new general resource wiring and `aspire-init` if no AppHost115 exists. Do not turn a terminal request into a migration or version upgrade.1164. Resolve actual executable paths, working directories and OS shell choices.117 Use argument lists, not concatenated untrusted shell input. Children inherit118 the AppHost environment; add only the necessary overrides.1195. Guard AppHost-owned terminal commands with `builder.ExecutionContext.IsRunMode`.120 Do not launch tools at model-construction time or during publish/deploy.1216. Validate the changed code, then route lifecycle work to `aspire-orchestration`.122 Use the exact AppHost, worktree isolation and bounded resource readiness.123 Validate the requested lifetime, cancellation and visible result, not merely124 that the AppHost compiled.125126## Non-negotiable ownership and completion rules127128- Terminal types are in `Aspire.Hosting.ApplicationModel`, not the old129 `Aspire.Hosting.Terminals` namespace. `TerminalService` is already registered;130 resolve it from built services or command `context.Services`. Do not construct131 it or register another singleton.132- A dock command that should leave a terminal open **must not** use `await using`133 for its handle. `Start()` is nonblocking/idempotent; `Show()` activates the dock.134 Command success means "opened", not "process exited successfully".135- Dialog and headless terminals normally use `await using`. Disposing an136 AppHost-owned handle stops its process; `PromptTerminalAsync` does **not**137 dispose it for you.138- Check `IInteractionService.IsAvailable` **before** launching a prompt-owned139 process. Noninteractive resource commands can make it false. Do not silently140 replace human interaction/approval with headless success.141- A prompt needs the exact registered instance from the same AppHost, with142 `TerminalPlacement.Dialog`. `ResourceView` is not valid for `CreateTerminal`.143- With `Work`, successful callback completion closes the dialog; observe144 `TerminalContext.CancellationToken` on every wait/input. Cancellation signals145 and joins Work; unrelated errors propagate. Without Work, process exit does146 not close the prompt: explicitly define completion/cancellation.147- No public `ExitCode` or `WaitForExitAsync` is available on `AspireTerminal`.148 Do not infer success from `Start()`, delivered keystrokes, prompt visibility,149 or disappearance of a process. Assert a meaningful fresh output marker.150- Viewers and automation share input. `--viewer` affects sizing ownership,151 not read-only authorization. Do not blindly retry non-idempotent input.152- Treat screen output and tapes as sensitive. Do not commit credentials or153 capture tokens in transcripts. Tape `Hide` is not redaction.154155## Driving terminals156157Read [automation and CLI](references/automation-and-cli.md) for C# screen/key158operations, owner-aware discovery and interactive attach. Use159[tapes](references/tapes.md) for unattended resource-terminal playback: supported160VHS syntax, explicit examples, stdout versus `.txt`/`.ascii` checkpoints, and161unsupported output formats. Do not install VHS or assume its whole feature set.162163For missing/disconnected terminals, inspect resource state and terminal discovery;164route console logs/traces to `aspire-monitoring`. Terminal views supplement logs,165not replace them. Publishing a resource does not publish a development PTY or166grant production shell access.