aspire terminal attach command

Name

aspire terminal attach - Attach the local terminal to an interactive PTY session for a resource.

Synopsis

aspire terminal attach <resource> [options]

Description

The aspire terminal attach command connects your local terminal to the interactive pseudo-terminal (PTY) session of a resource that was registered with WithTerminal(). Once attached, you interact with the resource’s terminal, as if it were running directly in your console. For example, you can drive its TUI or type into its shell.

The command discovers the running AppHost, verifies it supports the terminals.v1 capability, looks up the resource, and connects to one of its terminal replicas. When the resource has a single replica, that replica is selected automatically. When it has more than one, you’re prompted to choose one—or you can pass --replica.

Multiple peers can attach to the same session at once. By default, attach takes the primary role and drives the terminal’s dimensions. Pass --viewer to join as a passive viewer instead. This technique is useful when another peer, such as the dashboard, is currently driving the session.

While attached, the following hotkeys are available:

Hotkey	Action
`Ctrl+B D`	Detach from the session and exit cleanly.
`Ctrl+B T`	Take control (request the primary role).

If the selected replica has already exited, the command attaches to the historical output buffer; no live input is sent.

Because WithTerminal is experimental, this command is hidden behind a feature flag. Enable it with aspire config set features.terminalCommandsEnabled true.

Arguments

The following arguments are available:

<resource>

The name of the resource to attach a terminal to. The resource must have been registered with .WithTerminal().

Options

The following options are available:

--apphost <apphost>

The path to the Aspire AppHost file or project file, such as apphost.mts, apphost.cs, or an AppHost .csproj.
-r, --replica <index>

The 0-based replica index to attach to. Required when the resource has more than one replica and the CLI is not running interactively.
--viewer

Connect as a viewer (secondary) instead of taking primary control. Viewers see the terminal output but do not drive its dimensions. This option is useful when another peer (for example, the dashboard) is currently driving the session. Take control later with Ctrl+B T.
-?, -h, --help

Prints help and usage documentation for the available commands and options.
-l, --log-level <Critical|Debug|Error|Information|None|Trace|Warning>

Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs.
--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 running a command.

Examples

Attach to a resource’s terminal:
Aspire CLI
```
aspire terminal attach agent
```
Attach to a specific replica of a multi-replica resource:
Aspire CLI
```
aspire terminal attach agent --replica 1
```
Join an existing session as a passive viewer:
Aspire CLI
```
aspire terminal attach agent --viewer
```