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 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.

clrun