microsoft / microsoft/aspire

Aspire CLI: add automation-focused `aspire terminal *` commands aligned with Hex1b

Open
#18,088 0 comments 0 reactions 1 assignee Claimed by @mitchdenny View on GitHub
area-cli area-terminals enhancement
Dominant language
C#
Stars
6.3k
Forks
991
Avg merge
2d 15h
Merged PRs (30d)
196

Description

## Problem
For agent-driven automation, `aspire terminal attach` is not enough by itself. We need non-interactive command primitives for injecting input and snapshotting terminal state, aligned with the Hex1b command model.

Current Aspire terminal surface is primarily:
- `aspire terminal attach`
- `aspire terminal ps`

Hex1b already provides a broader automation shape (`keys`, `capture screenshot`, `assert`, `mouse`, `recording`, `resize`, etc.).

## Goal
Design a command suite under `aspire terminal *` that maps closely to Hex1b semantics so automation scripts/agents can be portable and predictable.

## Priority mapping

### P0 (core automation baseline)

| Hex1b command shape | Capability | Proposed Aspire command | Priority rationale |
| --- | --- | --- | --- |
| `dotnet hex1b keys --text "..."` / `--key Enter --ctrl` | Send text/keystrokes with modifiers | `aspire terminal send [--replica N] (--text ... | --key ... [--ctrl] [--alt] [--shift])` | Required to automate any interactive flow. |
| `dotnet hex1b capture screenshot [--format text|ansi|svg|png|html] [--wait ... --timeout ...]` | Snapshot visible terminal state | `aspire terminal snapshot [--replica N] [--format ...] [--wait ... --timeout ...] [--output ...]` | Required for evidence capture and deterministic assertions. |
| `dotnet hex1b assert --text-present/--text-absent ...` | Wait/assert on terminal content | `aspire terminal assert [--replica N] (--text-present ... | --text-absent ...) [--timeout ...]` | Needed for reliable, timing-safe automation. |
| `dotnet hex1b terminal resize --width W --height H` | Force PTY dimensions | `aspire terminal resize [--replica N] --width W --height H` | Critical for deterministic layout and cursor math in tests. |
| `--json` across commands | Machine-readable output | `--format json`/`--json` parity across new subcommands | Necessary for script/agent composability. |

### P1 (high-value interaction + diagnostics)

| Hex1b command shape | Capability | Proposed Aspire command | Priority rationale |
| --- | --- | --- | --- |
| `dotnet hex1b mouse click|drag ...` | Mouse interaction at terminal coordinates | `aspire terminal mouse click|drag [--replica N] ...` | Important for TUIs that rely on mouse hit-testing. |
| `dotnet hex1b capture recording start|stop|status ...` | Start/stop/status of asciinema recording | `aspire terminal recording start|stop|status [--replica N] ...` | High value for bug repro artifacts and supportability. |
| `dotnet hex1b terminal info ` | Runtime terminal metadata | `aspire terminal info [--replica N]` | Better diagnostics than `ps` alone for automation scripts. |

### P2 (advanced / future-proofing)

| Hex1b command shape | Capability | Proposed Aspire command | Priority rationale |
| --- | --- | --- | --- |
| `dotnet hex1b capture recording playback --file ... [--player]` | Playback of recorded sessions | `aspire terminal recording playback --file ...` | Nice-to-have; mostly offline analysis rather than control. |
| `dotnet hex1b app tree ...` | Hex1b widget-tree diagnostics | N/A or deferred Aspire-specific equivalent | Potentially useful, but only for Hex1b-native apps. |

## API/UX design notes
- Resource-first identity is preferable (` [--replica]`) instead of raw terminal IDs.
- Command names should stay close to Hex1b to minimize mental/context switching.
- For automation reliability, all non-interactive commands should support explicit timeout and structured error codes.
- Recording commands should align with dashboard recording UX so artifacts and metadata are consistent across CLI and UI.

## Backlog
Track this in Backlog milestone unless a near-term automation milestone is identified.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.