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

Node.js:

npm install -g clrun

Python (uv):

uv tool install clrun-cli

(pip: pip install clrun-cli)

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 calls
• output — cleaned terminal output (ANSI stripped)
• status — running, suspended, exited, killed, detached
• hints — 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.