Aspire CLI: add automation-focused `aspire terminal *` commands aligned with Hex1b
- 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
Assessment
This issue has not been assessed yet.