Automate terminal UI (TUI) apps with agent-tui for testing, inspection, demos, and scripted interactions. Use when automating CLI/TUI flows, regression testing terminal apps, verifying interactive behavior, or extracting structured text from terminal UIs. Also use when asked what agent-tui is, how it works, or to demo it. Do not use for web browsers, GUI apps, or non-terminal interfaces.
Automate terminal UI (TUI) apps with agent-tui for testing, inspection, demos, and scripted interactions. Use when automating CLI/TUI flows, regression testing terminal apps, verifying interactive behavior, or extracting structured text from terminal UIs. Also use when asked what agent-tui is, how it works, or to demo it. Do not use for web browsers, GUI apps, or non-terminal interfaces.
agent-tui
Quick start
Verify install: agent-tui --version
Install with npm i -g agent-tui (or pnpm add -g agent-tui, bun add -g agent-tui).
Alternate install: curl -fsSL https://raw.githubusercontent.com/pproenca/agent-tui/master/install.sh -o /tmp/agent-tui-install.sh && sh /tmp/agent-tui-install.sh or cargo install --git https://github.com/pproenca/agent-tui.git --path cli/crates/agent-tui.
If you used the install script, ensure ~/.local/bin is on your PATH.
Start a session: agent-tui run --format json <command> -- <args...>
Observe: agent-tui screenshot --format json
Act: agent-tui press Enter or agent-tui type "text"
Wait or verify: agent-tui wait "Expected text" --assert or agent-tui wait --stable
Cleanup: agent-tui kill
Core workflow
Run the app with agent-tui run and capture session_id from JSON output.
Take a fresh snapshot with agent-tui screenshot or agent-tui screenshot --format json.
Decide the next action based on the latest snapshot.
Act with press or type.
Synchronize with wait --assert or wait --stable.
Repeat from step 2 until the task finishes.
Clean up with agent-tui kill.
Reliability rules
Re-snapshot after every action that could change the UI.
Never act on a changing screen; wait for stability first.
Verify outcomes with wait --assert instead of assuming success.
Always end runs with kill or sessions cleanup.
Session handling
Use --session <id> for every command if more than one session exists.
If you lose the session id, run agent-tui sessions and agent-tui sessions show <id>.
Live preview (optional)
Ask whether a live preview is desired.
Start preview: agent-tui live start --open
Stop preview when done: agent-tui live stop
Deep-dive references
Full CLI coverage and options: references/command-atlas.md
