npx skills add ...
npx skills add microsoft/aspire --skill hex1b
npx skills add microsoft/aspire --skill hex1b
CLI tool for automating any terminal application — TUI apps, shells, CLI tools, REPLs, and more. Use when you need to launch a process in a virtual terminal, capture its screen output, inject keystrokes or mouse input, take screenshots, record sessions, or assert on what's visible.
The dotnet hex1b CLI tool lets you automate any terminal application — TUI apps,
interactive CLIs, shells, REPLs, curses programs, or anything else that runs in a terminal.
It wraps arbitrary processes in a headless virtual terminal, giving you programmatic control
over screen capture, input injection, and content assertions.
A terminal is a headless virtual terminal managed by Hex1b. Any process that runs in a terminal emulator can be launched inside one. Terminals are identified by a short numeric ID (the process ID). Use a prefix if unambiguous.
All commands support --json for machine-readable output.
Start any command in a headless terminal. This is the entry point for all automation.
To get the terminal ID for subsequent commands:
Capture the terminal's visible content at any point.
The --wait option polls until the specified text is visible, then captures. Useful when
the application takes time to render its initial state.
Use assertions to block until content is visible (or confirm it's absent). This is essential for reliable automation — never assume timing.
Exit code 0 means the assertion passed; non-zero means it failed (timed out).
Type text or send individual keys to the terminal.
Available key names (from the Hex1bKey enum, case-insensitive):
A–ZD0–D9F1–F12UpArrow, DownArrow, LeftArrow, RightArrow, Home, End, PageUp, PageDownBackspace, Delete, InsertTab, Enter, SpacebarEscapeOemComma, OemPeriod, OemMinus, OemPlus, OemQuestion, Oem1, Oem4, Oem5, Oem6, Oem7, OemTildeNumPad0–NumPad9, Multiply, Add, Subtract, Decimal, DivideClick or drag at specific terminal coordinates (0-based column, row).
If the terminal is already running, start recording its session to an asciinema .cast file.
Use --record on terminal start to begin recording immediately when the process launches.
The .cast file is written incrementally, so the file will contain all events up to the
point you stop.
If the terminal is running a Hex1b application with .WithDiagnostics() enabled, you can
inspect its internal widget/node tree.
Attach to a terminal for interactive use — you see what the process sees and can type directly.
Generate this skill file for a repository so AI agents know how to use the CLI.
--json with jq for scriptable output: dotnet hex1b terminal list --json | jq '.[] | .id'terminal list automatically cleans up stale sockets from exited processescapture screenshot --wait is useful for waiting for async rendering before capturingassert before interacting — never assume the app has rendered--output is required since PNG is a binary format.cast format and can be played with any compatible player# Start the default interactive shell
# (PowerShell on Windows, bash on Linux/macOS)
dotnet hex1b terminal start
# Start a specific program with custom terminal size
dotnet hex1b terminal start --width 120 --height 40 -- htop
# Start with a working directory
dotnet hex1b terminal start --cwd /path/to/project -- vim myfile.txt
# Start a .NET project
dotnet hex1b terminal start -- dotnet run --project src/MyApp
# Start and immediately attach (interactive mirror)
dotnet hex1b terminal start --attach# List all running terminals
dotnet hex1b terminal list
# Get the ID as JSON (useful for scripting)
ID=$(dotnet hex1b terminal start --json -- dotnet run --project src/MyApp | jq -r .id)# Plain text (default) — good for reading content and assertions
dotnet hex1b capture screenshot <id>
# ANSI — preserves colors and formatting
dotnet hex1b capture screenshot <id> --format ansi
# SVG — rendered terminal screenshot as vector image
dotnet hex1b capture screenshot <id> --format svg --output screenshot.svg
# PNG — rendered terminal screenshot as raster image (requires --output)
dotnet hex1b capture screenshot <id> --format png --output screenshot.png
# HTML — rendered terminal screenshot as HTML
dotnet hex1b capture screenshot <id> --format html --output screenshot.html
# Include scrollback history
dotnet hex1b capture screenshot <id> --scrollback 100
# Wait for specific content to appear before capturing
dotnet hex1b capture screenshot <id> --format png --output ready.png --wait "Ready" --timeout 30# Wait up to 30 seconds for text to appear
dotnet hex1b assert <id> --text-present "Welcome" --timeout 30
# Confirm error text is NOT showing (waits up to 10s to be sure)
dotnet hex1b assert <id> --text-absent "Error" --timeout 10# Type text (each character sent as a keystroke)
dotnet hex1b keys <id> --text "hello world"
# Send a named key
dotnet hex1b keys <id> --key Enter
dotnet hex1b keys <id> --key Tab
dotnet hex1b keys <id> --key Escape
dotnet hex1b keys <id> --key UpArrow
# Send key with modifiers
dotnet hex1b keys <id> --key C --ctrl # Ctrl+C
dotnet hex1b keys <id> --key S --ctrl # Ctrl+S
dotnet hex1b keys <id> --key Tab --shift # Shift+Tab
dotnet hex1b keys <id> --key F --ctrl --shift # Ctrl+Shift+F# Left click at column 10, row 5
dotnet hex1b mouse click <id> 10 5
# Right click
dotnet hex1b mouse click <id> 10 5 --button right
# Drag from (5,3) to (20,3)
dotnet hex1b mouse drag <id> 5 3 20 3# Start the terminal first
dotnet hex1b terminal start -- dotnet run --project src/MyApp
# ... get the <id> from terminal list ...
# Begin recording to a file
dotnet hex1b capture recording start <id> --output session.cast
# Optionally set a title and idle time limit
dotnet hex1b capture recording start <id> --output session.cast --title "Demo session" --idle-limit 2.0
# Do your interactions...
dotnet hex1b keys <id> --text "hello"
dotnet hex1b keys <id> --key Enter
# Stop recording when done
dotnet hex1b capture recording stop <id># Start terminal with recording enabled from the start
dotnet hex1b terminal start --record session.cast -- dotnet run --project src/MyApp
# The recording is already in progress — interact normally
dotnet hex1b assert <id> --text-present "Ready" --timeout 15
dotnet hex1b keys <id> --key Enter
dotnet hex1b capture screenshot <id> --format text
# Stop recording when done
dotnet hex1b capture recording stop <id># Stop the active recording
dotnet hex1b capture recording stop <id>
# Check if a terminal is currently recording
dotnet hex1b capture recording status <id># Simple playback in the terminal
dotnet hex1b capture recording playback --file session.cast
# Play at 2x speed
dotnet hex1b capture recording playback --file session.cast --speed 2.0
# Interactive TUI player with pause/seek controls
dotnet hex1b capture recording playback --file session.cast --player# Show the full widget tree with geometry
dotnet hex1b app tree <id>
# Include focus state
dotnet hex1b app tree <id> --focus
# Include popup stack
dotnet hex1b app tree <id> --popups
# Limit tree depth
dotnet hex1b app tree <id> --depth 3
# Get as JSON for programmatic inspection
dotnet hex1b app tree <id> --json# Stop a specific terminal
dotnet hex1b terminal stop <id>
# Get terminal details (PID, dimensions, uptime)
dotnet hex1b terminal info <id>
# Resize a running terminal
dotnet hex1b terminal resize <id> --width 160 --height 50
# Clean up stale sockets from exited processes
dotnet hex1b terminal clean# Attach to a terminal (Ctrl+] to detach)
dotnet hex1b terminal attach <id># Write skill file to .agents/skills/hex1b/SKILL.md
dotnet hex1b agent init
# Specify a different repo root
dotnet hex1b agent init --path /path/to/repo
# Overwrite an existing skill file
dotnet hex1b agent init --force
# Print to stdout instead of writing to disk
dotnet hex1b agent init --stdout# Launch the app
ID=$(dotnet hex1b terminal start --json -- dotnet run --project src/MyApp | jq -r .id)
# Wait for it to be ready
dotnet hex1b assert $ID --text-present "Main Menu" --timeout 15
# Navigate and interact
dotnet hex1b keys $ID --key Enter
dotnet hex1b assert $ID --text-present "Settings"
dotnet hex1b keys $ID --text "new value"
dotnet hex1b keys $ID --key Enter
# Capture final state
dotnet hex1b capture screenshot $ID --format png --output result.png
dotnet hex1b capture screenshot $ID --format text
# Clean up
dotnet hex1b terminal stop $ID# Start with recording
ID=$(dotnet hex1b terminal start --json --record demo.cast -- dotnet run --project samples/MyApp | jq -r .id)
# Wait and interact
dotnet hex1b assert $ID --text-present "Ready" --timeout 15
dotnet hex1b keys $ID --key Tab
dotnet hex1b keys $ID --key Enter
# Take a screenshot at a key moment
dotnet hex1b capture screenshot $ID --format png --output highlight.png
# Stop recording and terminal
dotnet hex1b capture recording stop $ID
dotnet hex1b terminal stop $ID
# Play it back
dotnet hex1b capture recording playback --file demo.cast --player