hex1b

# Install as a global tool
dotnet tool install -g Hex1b.Tool
 
# Or as a local tool (requires a tool manifest)
dotnet new tool-manifest   # if no manifest exists yet
dotnet tool install --local Hex1b.Tool
dotnet tool restore        # to restore from an existing manifest

# 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