{"skill":{"slug":"clrun","displayName":"clrun - Interactive CLI for agent with a LLM readable YAML response surface","summary":"Run and control interactive CLI sessions. Handles TUI prompts (select lists, checkboxes, confirms), persistent shell state, and long-running processes. Use w...","description":"---\nname: clrun\ndescription: Run and control interactive CLI sessions. 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.\nlicense: MIT\nmetadata:\n  author: cybertheory\n  version: \"1.0.1\"\ncompatibility: Requires Node.js >= 18 and clrun installed (npm install -g clrun or npx clrun).\n---\n\n# clrun — The Interactive CLI for AI Agents\n\nUse `clrun` whenever you need to run commands that require interactive input,\nTUI navigation, long-running processes, or deterministic execution control.\nNo more `--yes` flags or command retries.\n\n## When to Use clrun\n\n- **Interactive scaffolders** — create-vue, create-vite, create-astro, npm init\n- **TUI tools** with select lists, checkboxes, and confirm dialogs\n- **Long-running processes** — dev servers, test suites, docker builds\n- **Stateful sessions** — setting env vars, then querying them later\n- **Any command that prompts** for user input\n\n## Quick Reference\n\n| Action | Command |\n|--------|---------|\n| Run a command | `clrun <command>` |\n| Send text + Enter | `clrun <id> \"text\"` |\n| Send keystrokes | `clrun key <id> down enter` |\n| Toggle checkbox | `clrun key <id> space` |\n| Accept default | `clrun key <id> enter` |\n| View latest output | `clrun tail <id>` or `clrun <id>` |\n| Check all sessions | `clrun status` |\n| Kill a session | `clrun kill <id>` |\n| Interrupt (Ctrl+C) | `clrun key <id> ctrl-c` |\n\n## Two Input Modes\n\n### Text Input (`clrun <id> \"text\"`)\n\nSends text followed by Enter. Use for:\n- Typing text into prompts (project names, descriptions, etc.)\n- Sending shell commands to the running session\n- Responding to simple yes/no or readline-style prompts\n\n```bash\nclrun <id> \"my-project-name\"    # Type text and press Enter\nclrun <id> \"\"                    # Just press Enter (accept default for readline)\n```\n\n### Keystroke Input (`clrun key <id> <keys...>`)\n\nSends raw keystrokes. Use for:\n- Navigating select lists (`up`, `down`, `enter`)\n- Toggling checkboxes (`space`)\n- Accepting TUI defaults (`enter`)\n- Switching Yes/No (`left`, `right`)\n- Interrupting processes (`ctrl-c`)\n\n```bash\nclrun key <id> down down enter           # Select 3rd item in a list\nclrun key <id> space down space enter    # Toggle checkboxes 1 and 2, confirm\nclrun key <id> enter                      # Accept default / confirm\n```\n\n**Available keys:**\n`up`, `down`, `left`, `right`, `enter`, `tab`, `escape`, `space`,\n`backspace`, `delete`, `home`, `end`, `pageup`, `pagedown`,\n`ctrl-c`, `ctrl-d`, `ctrl-z`, `ctrl-l`, `ctrl-a`, `ctrl-e`, `y`, `n`\n\n## Identifying Prompt Types\n\nWhen you `tail` a session and see a prompt, identify its type:\n\n| You see | Type | Action |\n|---------|------|--------|\n| `◆  Project name: │  default` | Text input | `clrun <id> \"name\"` or `clrun key <id> enter` |\n| `● Option1  ○ Option2  ○ Option3` | Single-select | `clrun key <id> down... enter` |\n| `◻ Option1  ◻ Option2  ◻ Option3` | Multi-select | `clrun key <id> space down... enter` |\n| `● Yes / ○ No` | Confirm | `clrun key <id> enter` or `clrun key <id> right enter` |\n| `(y/n)`, `[Y/n]` | Simple confirm | `clrun <id> \"y\"` or `clrun <id> \"n\"` |\n| `package name: (default)` | Readline | `clrun <id> \"value\"` or `clrun <id> \"\"` |\n\n## Select List Navigation\n\nThe **first item** is always highlighted by default. Each `down` moves one position.\nTo select the Nth item: send N-1 `down` presses, then `enter`.\n\n```\n◆  Select a framework:\n│  ● Vanilla       ← position 1 (0 downs)\n│  ○ Vue           ← position 2 (1 down)\n│  ○ React         ← position 3 (2 downs)\n│  ○ Svelte        ← position 4 (3 downs)\n```\n\n```bash\nclrun key <id> down down enter   # Selects React (2 downs from top)\n```\n\n## Multi-Select Pattern\n\nPlan your moves as a sequence of `space` (toggle) and `down` (skip) from top to bottom, ending with `enter`:\n\n```bash\n# Select TypeScript (1st), skip JSX (2nd), select Router (3rd), confirm:\nclrun key <id> space down down space enter\n```\n\n## Lifecycle Pattern\n\n```\n1. START    →  clrun <command>                    → get terminal_id\n2. OBSERVE  →  clrun tail <id>                    → read output, identify prompt\n3. INTERACT →  clrun <id> \"text\" / clrun key <id> → send input\n4. REPEAT   →  go to 2 until done\n5. VERIFY   →  clrun status                       → check exit codes\n6. CLEANUP  →  clrun kill <id>                    → if needed\n```\n\n## Reading Responses\n\nAll responses are YAML. Key fields:\n\n- **`terminal_id`** — store this, you need it for everything\n- **`output`** — cleaned terminal output (ANSI stripped, prompts filtered)\n- **`status`** — `running`, `suspended`, `exited`, `killed`, `detached`\n- **`hints`** — the exact commands you can run next (copy-pasteable)\n- **`warnings`** — issues with your input or detected output artifacts\n- **`restored`** — `true` if the session was auto-restored from suspension\n\n## Shell Variable Quoting\n\nUse **single quotes** to prevent shell expansion:\n\n```bash\nclrun <id> 'echo $MY_VAR'          # Correct — variable reaches the session\nclrun <id> \"echo $MY_VAR\"          # Wrong — your shell expands it first\n```\n\n## Suspended Sessions\n\nSessions suspend after 5 minutes of inactivity. Just send input normally — they\nauto-restore transparently. No need to check status first.\n\n## Important Rules\n\n1. **Parse YAML** — all responses are structured YAML\n2. **Read the hints** — they tell you exactly what to do next\n3. **Use `key` for TUI prompts** — never type escape sequences as text\n4. **Use text input for readline prompts** — `clrun <id> \"text\"`\n5. **Single-quote `$` variables** — prevents premature shell expansion\n6. **Accept defaults with `key enter`** — not with empty text for TUI prompts\n7. **Count items from top** for select lists — N-1 `down` presses for item N\n\nSee [references/tui-patterns.md](references/tui-patterns.md) for real-world walkthroughs.\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":345,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1771290555712,"updatedAt":1778991091033},"latestVersion":{"version":"1.0.0","createdAt":1771290555712,"changelog":"first push","license":null},"metadata":null,"owner":{"handle":"cybertheory","userId":"s17bcrt91sk27tgjm3wb7jeqhh884n1q","displayName":"Rishabh Singh","image":"https://avatars.githubusercontent.com/u/27149047?v=4"},"moderation":null}