cybertheory clrun — The Interactive CLI for AI Agents
No more --yes flags or command retries. clrun gives you full control over interactive terminal sessions with structured YAML responses.
Install
npm install -g clrun
Core Commands
| Action | Command |
|---|---|
| Run a command | clrun <command> |
| Send text + Enter | clrun <id> "text" |
| Send keystrokes | clrun key <id> down enter |
| Toggle checkbox | clrun key <id> space |
| Accept default | clrun key <id> enter |
| View output | clrun tail <id> |
| Check sessions | clrun status |
| Kill session | clrun kill <id> |
| Interrupt | clrun key <id> ctrl-c |
Two Input Modes
Text input — sends text followed by Enter:
clrun <id> "my-project-name" # Type and press Enter
clrun <id> "" # Just press Enter
Keystroke input — sends raw keys for TUI navigation:
clrun key <id> down down enter # Select 3rd item in list
clrun key <id> space down space enter # Toggle checkboxes 1 and 2
clrun key <id> enter # Accept default
Available keys: up, down, left, right, enter, tab, escape, space, backspace, delete, home, end, pageup, pagedown, ctrl-c, ctrl-d, ctrl-z, ctrl-l, ctrl-a, ctrl-e, y, n
Identifying Prompt Types
When you tail a session, identify the prompt type to choose the right input:
| You see | Type | Action |
|---|---|---|
◆ Name: │ default |
Text input | clrun <id> "value" or clrun key <id> enter |
● Opt1 ○ Opt2 ○ Opt3 |
Single-select | clrun key <id> down... enter |
◻ Opt1 ◻ Opt2 ◻ Opt3 |
Multi-select | clrun key <id> space down... enter |
● Yes / ○ No |
Confirm | clrun key <id> enter or right enter |
(y/n) |
Simple confirm | clrun <id> "y" or clrun <id> "n" |
name: (default) |
Readline | clrun <id> "value" or clrun <id> "" |
Select List Navigation
Count items from the top. First item is highlighted by default. To select item N, send N-1 down presses then enter.
◆ Select a framework:
│ ● Vanilla ← 0 downs
│ ○ Vue ← 1 down
│ ○ React ← 2 downs
│ ○ Svelte ← 3 downs
clrun key <id> down down enter # Selects React
Multi-Select Pattern
Plan a sequence of space (toggle) and down (skip) from top to bottom, ending with enter:
# Select items 1, 3, and 4 from a list of 5:
clrun key <id> space down down space down space enter
# item1 skip skip item3 item4 confirm
Reading Responses
All responses are structured YAML. Key fields:
terminal_id— store this for all subsequent callsoutput— cleaned terminal output (ANSI stripped)status—running,suspended,exited,killed,detachedhints— exact commands you can run next (copy-pasteable)warnings— detected issues with input or output
Workflow Pattern
1. START → clrun <command> → get terminal_id
2. OBSERVE → clrun tail <id> → read output, identify prompt
3. INTERACT → clrun <id> "text" / clrun key → respond to prompt
4. REPEAT → steps 2-3 until done
5. CLEANUP → clrun kill <id> → if needed
Shell Variable Quoting
Use single quotes to prevent your shell from expanding $ variables:
clrun <id> 'echo $MY_VAR' # Correct
clrun <id> "echo $MY_VAR" # Wrong — expanded before clrun sees it
Session Persistence
- Environment variables persist within a session
- Sessions auto-suspend after 5 min idle (env and cwd saved)
- Sending input to a suspended session auto-restores it
- No pre-check needed — just send input
See references/tui-patterns.md for complete real-world examples.