clrun — The Interactive CLI for AI Agents

Description

--- name: clrun description: Run and control interactive CLI sessions for AI agents. Handles TUI prompts (select lists, checkboxes, confirms), persistent shell state, and long-running processes. Use when you need to execute terminal commands, respond to interactive prompts, navigate scaffolding wizards like create-vue or create-vite, or manage dev servers. license: MIT metadata: author: cybertheory version: "1.0.1" compatibility: Requires Node.js >= 18. Works on macOS, Linux, and Windows. --- # 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 ```bash 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: ```bash clrun <id> "my-project-name" # Type and press Enter clrun <id> "" # Just press Enter ``` **Keystroke input** — sends raw keys for TUI navigation: ```bash 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 ``` ```bash 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`: ```bash # 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: ```bash 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](references/tui-patterns.md) for complete real-world examples.

Security Status