agent-tui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agent-tui

Quick start

快速开始

Verify install:
```
agent-tui --version
```

Install with

npm i -g agent-tui

(or

pnpm add -g agent-tui

bun add -g agent-tui

Alternate install:

curl -fsSL https://raw.githubusercontent.com/pproenca/agent-tui/master/install.sh -o /tmp/agent-tui-install.sh && sh /tmp/agent-tui-install.sh

cargo install --git https://github.com/pproenca/agent-tui.git --path cli/crates/agent-tui

If you used the install script, ensure
```
~/.local/bin
```
is on your PATH.

Start a session:

agent-tui run --format json <command> -- <args...>

Observe:
```
agent-tui screenshot --format json
```

Act:

agent-tui press Enter

agent-tui type "text"

Wait or verify:

agent-tui wait "Expected text" --assert

agent-tui wait --stable

Cleanup:
```
agent-tui kill
```

验证安装：
```
agent-tui --version
```

安装方式：使用

npm i -g agent-tui

（或

pnpm add -g agent-tui

、

bun add -g agent-tui

）。

替代安装方式：执行

curl -fsSL https://raw.githubusercontent.com/pproenca/agent-tui/master/install.sh -o /tmp/agent-tui-install.sh && sh /tmp/agent-tui-install.sh

，或使用

cargo install --git https://github.com/pproenca/agent-tui.git --path cli/crates/agent-tui

。

若使用安装脚本，请确保
```
~/.local/bin
```
已添加到你的PATH环境变量中。

启动会话：

agent-tui run --format json <command> -- <args...>

查看界面：
```
agent-tui screenshot --format json
```

执行操作：

agent-tui press Enter

或

agent-tui type "text"

等待或验证：

agent-tui wait "Expected text" --assert

或

agent-tui wait --stable

清理会话：
```
agent-tui kill
```

Core workflow

核心工作流

Run the app with
```
agent-tui run
```
and capture
```
session_id
```
from JSON output.

Take a fresh snapshot with

agent-tui screenshot

agent-tui screenshot --format json

Decide the next action based on the latest snapshot.
Act with
```
press
```
or
```
type
```
.
Synchronize with
```
wait --assert
```
or
```
wait --stable
```
.
Repeat from step 2 until the task finishes.
Clean up with
```
agent-tui kill
```
.

使用
```
agent-tui run
```
启动应用，并从JSON输出中获取
```
session_id
```
。

使用

agent-tui screenshot

或

agent-tui screenshot --format json

获取最新界面快照。

根据最新快照决定下一步操作。
使用
```
press
```
或
```
type
```
命令执行操作。
使用
```
wait --assert
```
或
```
wait --stable
```
命令同步状态。
重复步骤2直至任务完成。
使用
```
agent-tui kill
```
清理会话。

Reliability rules

可靠性规则

Re-snapshot after every action that could change the UI.
Never act on a changing screen; wait for stability first.
Verify outcomes with
```
wait --assert
```
instead of assuming success.
Always end runs with
```
kill
```
or
```
sessions cleanup
```
.

每次执行可能改变UI的操作后，重新获取快照。
切勿在界面变化时执行操作；先等待界面稳定。
使用
```
wait --assert
```
验证操作结果，而非默认操作成功。
务必使用
```
kill
```
或
```
sessions cleanup
```
结束运行。

Session handling

会话管理

Use
```
--session <id>
```
for every command if more than one session exists.

If you lose the session id, run

agent-tui sessions

and

agent-tui sessions show <id>

若存在多个会话，所有命令都需添加
```
--session <id>
```
参数指定会话。
若丢失会话ID，可执行
```
agent-tui sessions
```
和
```
agent-tui sessions show <id>
```
命令查询。

Live preview (optional)

实时预览（可选）

Ask whether a live preview is desired.
Start preview:
```
agent-tui live start --open
```
Stop preview when done:
```
agent-tui live stop
```

询问是否需要实时预览。
启动预览：
```
agent-tui live start --open
```
完成后停止预览：
```
agent-tui live stop
```

Deep-dive references

深度参考资料

Full CLI coverage and options:
```
references/command-atlas.md
```
JSON output contract:
```
references/output-contract.md
```
End-to-end command sequences:
```
references/flows.md
```
Quick command selection:
```
references/decision-tree.md
```
Session lifecycle and concurrency:
```
references/session-lifecycle.md
```
Assertions and test oracles:
```
references/assertions.md
```
Failure recovery playbook:
```
references/recovery.md
```
Safety and confirmation prompts:
```
references/safety.md
```
Clarification checklist:
```
references/clarifications.md
```
Test plan template:
```
references/test-plan.md
```
Demo script:
```
references/demo.md
```
User prompt templates:
```
references/prompt-templates.md
```
Minimal command sets by use case:
```
references/use-cases.md
```

完整CLI命令及选项：
```
references/command-atlas.md
```
JSON输出规范：
```
references/output-contract.md
```
端到端命令序列：
```
references/flows.md
```
快速命令选择指南：
```
references/decision-tree.md
```
会话生命周期与并发：
```
references/session-lifecycle.md
```
断言与测试验证：
```
references/assertions.md
```
故障恢复手册：
```
references/recovery.md
```
安全与确认提示：
```
references/safety.md
```
澄清检查清单：
```
references/clarifications.md
```
测试计划模板：
```
references/test-plan.md
```
演示脚本：
```
references/demo.md
```
用户提示模板：
```
references/prompt-templates.md
```
按用例划分的最小命令集：
```
references/use-cases.md
```