clrun

Original：🇺🇸 English
Translated

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.

2installs
Sourcecybertheory/clrun
Added on

NPX Install

npx skill4agent add cybertheory/clrun clrun

Tags

Translated version includes tags in frontmatter
ai-agent-clitui-handlingsession-persistenceterminal-interactiondev-wizard-navigation

SKILL.md Content

View Translation Comparison →

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

ActionCommand
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 seeTypeAction
◆ 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 for complete real-world examples.