Hex1b.Tool

Hex1b.Tool

A command-line tool for managing and interacting with Hex1b terminal applications. Provides terminal hosting, screen capture, input injection, widget tree inspection, session recording, and more.

Installation

Install as a .NET global tool:

dotnet tool install -g Hex1b.Tool

This makes the hex1b command available system-wide. Alternatively, install as a local tool in your project:

dotnet tool install Hex1b.Tool

Then invoke with dotnet hex1b.

Quick Start

Connect to a running app

Any Hex1b application that uses .WithDiagnostics() is automatically discoverable:

# List all discoverable terminals
hex1b terminal list

# Attach to a terminal (interactive TUI mirror)
hex1b terminal attach <id>

# Take a screenshot
hex1b capture screenshot <id>

Start a hosted terminal

Start new terminal sessions that host shell commands:

# Start the default interactive shell
# (PowerShell on Windows, bash on Linux/macOS)
hex1b terminal start

# Start with custom dimensions
hex1b terminal start --width 120 --height 40 -- htop

# Start and immediately attach
hex1b terminal start --attach -- vim

Commands

terminal — Manage terminal sessions

capture — Screenshots and recordings

keys — Send keyboard input

hex1b keys <id> --text "hello world"
hex1b keys <id> --key Enter
hex1b keys <id> --key Tab --ctrl

mouse — Send mouse input

app — Inspect widget trees

assert — Validate terminal content

Assert on terminal content for scripting and CI:

hex1b assert <id> --text-present "Ready" --timeout 10
hex1b assert <id> --text-absent "Error"

agent — AI agent integration

Global Options

Making Your App Discoverable

For the CLI to find your application, call .WithDiagnostics() on your terminal builder:

using Hex1b;

await using var terminal = Hex1bTerminal.CreateBuilder()
    .WithHex1bApp((app, options) => ctx =>
        ctx.Text("Hello from Hex1b!"))
    .WithDiagnostics()
    .Build();

await terminal.RunAsync();

Scripting and CI

The CLI is designed for scriptability. Use --json for machine-readable output and assert for CI checks:

hex1b terminal start -- ./my-app
hex1b assert abc --text-present "Welcome" --timeout 30
hex1b keys abc --text "admin"
hex1b keys abc --key Enter
hex1b assert abc --text-present "Dashboard"
hex1b capture screenshot abc --format svg --output result.svg
hex1b capture screenshot abc --format png --output result.png
hex1b terminal stop abc

Requirements

• .NET 10.0 or later
• Windows, Linux, or macOS

Documentation

• CLI Guide — Getting started and use cases
• CLI Reference — Complete command reference
• GitHub Repository

License

MIT — See LICENSE file in the repository.