Back to Details

clrun

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

clrun — The Interactive CLI for AI Agents

clrun — 面向AI Agent的交互式CLI工具

No more 
--yes
flags or command retries. 
clrun
gives you full control over interactive terminal sessions with structured YAML responses.
无需再使用
--yes
参数或重复执行命令。
clrun
让你通过结构化的YAML响应，完全掌控交互式终端会话。

Install

安装

bash
npm install -g clrun
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
操作命令
运行命令
clrun <command>
发送文本并回车
clrun <id> "text"
发送按键
clrun key <id> down enter
切换复选框
clrun key <id> space
接受默认值
clrun key <id> enter
查看输出
clrun tail <id>
查看会话状态
clrun status
终止会话
clrun kill <id>
中断进程
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
文本输入 — 发送文本后自动回车：
bash
clrun <id> "my-project-name"    # 输入内容并按回车
clrun <id> ""                    # 仅按回车
按键输入 — 发送原始按键用于TUI导航：
bash
clrun key <id> down down enter           # 选择列表中的第3项
clrun key <id> space down space enter    # 切换第1和第2个复选框
clrun key <id> enter                      # 接受默认值
支持的按键：
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> ""
当你使用
tail
查看会话时，需要识别提示类型以选择正确的输入方式：
显示内容类型操作
◆ Name: │ default
文本输入
clrun <id> "value"
或 
clrun key <id> enter
● Opt1 ○ Opt2 ○ Opt3
单选列表
clrun key <id> down... enter
◻ Opt1 ◻ Opt2 ◻ Opt3
多选列表
clrun key <id> space down... enter
● Yes / ○ No
确认选择
clrun key <id> enter
或 
right enter
(y/n)
简单确认
clrun <id> "y"
或 
clrun <id> "n"
name: (default)
Readline输入
clrun <id> "value"
或 
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
从顶部开始计数选项。默认高亮第一个选项。要选择第N项，发送N-1次
down
按键，然后按
enter
。
◆  选择框架:
│  ● Vanilla       ← 0次down
│  ○ Vue           ← 1次down
│  ○ React         ← 2次down
│  ○ Svelte        ← 3次down
bash
clrun key <id> down down enter   # 选择React

Multi-Select Pattern

多选模式

Plan a sequence of 
space
(toggle) and 
down
(skip) from top to bottom, ending with 
enter
:
bash
undefined
规划从顶部到底部的
space
（切换）和
down
（跳过）序列，最后按
enter
确认：
bash
undefined

Select items 1, 3, and 4 from a list of 5:

从5个选项中选择第1、3、4项:

clrun key <id> space down down space down space enter
clrun key <id> space down down space down space enter

item1 skip skip item3 item4 confirm

选第1项 跳过 跳过 选第3项 选第4项 确认

undefined
undefined

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
所有响应均为结构化YAML格式。关键字段：
  • terminal_id
     — 保存该ID用于后续所有调用
  • output
     — 清理后的终端输出（已去除ANSI代码）
  • status
     — 
    running
    （运行中）、
    suspended
    （已挂起）、
    exited
    （已退出）、
    killed
    （已终止）、
    detached
    （已分离）
  • hints
     — 可直接复制粘贴的下一步执行命令
  • warnings
     — 检测到的输入或输出问题

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
1. 启动    →  clrun <command>               → 获取terminal_id
2. 观察    →  clrun tail <id>               → 读取输出，识别提示类型
3. 交互    →  clrun <id> "text" / clrun key → 响应提示
4. 重复    →  重复步骤2-3直至完成
5. 清理    →  clrun kill <id>               → 如有需要

Shell Variable Quoting

Shell变量引用

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
使用单引号防止shell扩展
$
变量：
bash
clrun <id> 'echo $MY_VAR'          # 正确
clrun <id> "echo $MY_VAR"          # 错误 — shell会在clrun处理前扩展变量

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.
  • 环境变量在会话内保持持久
  • 会话闲置5分钟后自动挂起（环境变量和当前工作目录已保存）
  • 向挂起的会话发送输入会自动恢复会话
  • 无需预先检查，直接发送输入即可
完整的真实场景示例请查看references/tui-patterns.md。