clrun — The Interactive CLI for AI Agents

Use clrun whenever you need to run commands that require interactive input, TUI navigation, long-running processes, or deterministic execution control. No more --yes flags or command retries.

When to Use clrun

• Interactive scaffolders — create-vue, create-vite, create-astro, npm init
• TUI tools with select lists, checkboxes, and confirm dialogs
• Long-running processes — dev servers, test suites, docker builds
• Stateful sessions — setting env vars, then querying them later
• Any command that prompts for user input

Quick Reference

Two Input Modes

Text Input (clrun <id> "text")

Sends text followed by Enter. Use for:

• Typing text into prompts (project names, descriptions, etc.)
• Sending shell commands to the running session
• Responding to simple yes/no or readline-style prompts

clrun <id> "my-project-name"    # Type text and press Enter
clrun <id> ""                    # Just press Enter (accept default for readline)

Keystroke Input (clrun key <id> <keys...>)

Sends raw keystrokes. Use for:

• Navigating select lists (up, down, enter)
• Toggling checkboxes (space)
• Accepting TUI defaults (enter)
• Switching Yes/No (left, right)
• Interrupting processes (ctrl-c)

clrun key <id> down down enter           # Select 3rd item in a list
clrun key <id> space down space enter    # Toggle checkboxes 1 and 2, confirm
clrun key <id> enter                      # Accept default / confirm

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 and see a prompt, identify its type:

Select List Navigation

The first item is always highlighted by default. Each down moves one position. To select the Nth item: send N-1 down presses, then enter.

◆  Select a framework:
│  ● Vanilla       ← position 1 (0 downs)
│  ○ Vue           ← position 2 (1 down)
│  ○ React         ← position 3 (2 downs)
│  ○ Svelte        ← position 4 (3 downs)

clrun key <id> down down enter   # Selects React (2 downs from top)

Multi-Select Pattern

Plan your moves as a sequence of space (toggle) and down (skip) from top to bottom, ending with enter:

# Select TypeScript (1st), skip JSX (2nd), select Router (3rd), confirm:
clrun key <id> space down down space enter

Lifecycle Pattern

1. START    →  clrun <command>                    → get terminal_id
2. OBSERVE  →  clrun tail <id>                    → read output, identify prompt
3. INTERACT →  clrun <id> "text" / clrun key <id> → send input
4. REPEAT   →  go to 2 until done
5. VERIFY   →  clrun status                       → check exit codes
6. CLEANUP  →  clrun kill <id>                    → if needed

Reading Responses

All responses are YAML. Key fields:

• terminal_id — store this, you need it for everything
• output — cleaned terminal output (ANSI stripped, prompts filtered)
• status — running, suspended, exited, killed, detached
• hints — the exact commands you can run next (copy-pasteable)
• warnings — issues with your input or detected output artifacts
• restored — true if the session was auto-restored from suspension

Shell Variable Quoting

Use single quotes to prevent shell expansion:

clrun <id> 'echo $MY_VAR'          # Correct — variable reaches the session
clrun <id> "echo $MY_VAR"          # Wrong — your shell expands it first

Suspended Sessions

Sessions suspend after 5 minutes of inactivity. Just send input normally — they auto-restore transparently. No need to check status first.

Important Rules

1. Parse YAML — all responses are structured YAML
2. Read the hints — they tell you exactly what to do next
3. Use key for TUI prompts — never type escape sequences as text
4. Use text input for readline prompts — clrun <id> "text"
5. Single-quote $ variables — prevents premature shell expansion
6. Accept defaults with key enter — not with empty text for TUI prompts
7. Count items from top for select lists — N-1 down presses for item N

See references/tui-patterns.md for real-world walkthroughs.