pty-bridge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

pty-bridge

You have access to

pty-bridge

, a CLI tool that manages interactive terminal sessions with full PTY support. Use it when the standard Bash tool cannot handle interactive programs — SSH, REPLs, database CLIs, TUI apps, or any command that expects terminal input.

你可以使用

pty-bridge

这一具备完整PTY支持的CLI工具来管理交互式终端会话。当标准Bash工具无法处理交互式程序时（如SSH、REPL、数据库CLI、TUI应用或任何需要终端输入的命令），请使用该工具。

Before Use — Check Installation

使用前——检查安装

Always verify pty-bridge is available before attempting to use it. Start every session by running:

bash

pty-bridge status

If this fails with

command not found

, install pty-bridge:

bash

curl -fsSL https://raw.githubusercontent.com/briqt/pty-bridge/main/skill/install.sh | bash

If curl install fails (e.g. no GitHub access), use npm instead:

bash

npm i -g github:briqt/pty-bridge

Requirements: Node.js 18+. No C++ compiler needed — prebuilt native binaries are included.

在尝试使用pty-bridge之前，请务必确认其已可用。 每次会话开始时先运行：

bash

pty-bridge status

如果执行失败并提示

command not found

，请安装pty-bridge：

bash

curl -fsSL https://raw.githubusercontent.com/briqt/pty-bridge/main/skill/install.sh | bash

如果curl安装失败（例如无法访问GitHub），请改用npm安装：

bash

npm i -g github:briqt/pty-bridge

要求：Node.js 18+。无需C++编译器——已包含预构建的原生二进制文件。

When to Use

使用场景

SSH into remote servers
Interactive REPLs (python, node, irb, psql, mysql, etc.)
Programs that prompt for passwords or confirmations
TUI applications (htop, vim, less, etc.)
Any command that hangs or misbehaves with the regular Bash tool

远程服务器SSH登录
交互式REPL（python、node、irb、psql、mysql等）
需要输入密码或确认信息的程序
TUI应用（htop、vim、less等）
常规Bash工具运行时出现挂起或异常的命令

Commands

命令

bash

pty-bridge start <command> [args...]                # Start a PTY session
pty-bridge read <id> [--full] [--buffer <type>]     # Read new output (incremental by default, --full for all)
pty-bridge write <id> <input>                       # Send input (or pipe via stdin)
pty-bridge exec <id> <command> [--wait <ms>]        # Execute command and return new output (default wait: 200ms)
                               [--wait-for-idle <ms>]
pty-bridge sendkey <id> <key>                       # Send special key
pty-bridge wait-for <id> <pattern> [--timeout <s>]  # Block until pattern appears (default: 30s)
pty-bridge snapshot <id>                            # Capture current visible screen content
pty-bridge list                                     # List active sessions with uptime, buffer type, and details
pty-bridge kill <id>                                # Terminate a session
pty-bridge resize <id> <cols> <rows>                # Resize terminal
pty-bridge status                                   # Show daemon status (PID, memory, sessions)

bash

pty-bridge start <command> [args...]                # 启动PTY会话
pty-bridge read <id> [--full] [--buffer <type>]     # 读取新输出（默认增量读取，--full参数读取全部内容）
pty-bridge write <id> <input>                       # 发送输入（或通过标准输入管道传输）
pty-bridge exec <id> <command> [--wait <ms>]        # 执行命令并返回新输出（默认等待时间：200ms）
                               [--wait-for-idle <ms>]
pty-bridge sendkey <id> <key>                       # 发送特殊按键
pty-bridge wait-for <id> <pattern> [--timeout <s>]  # 阻塞直到匹配到指定模式（默认超时：30s）
pty-bridge snapshot <id>                            # 捕获当前可见屏幕内容
pty-bridge list                                     # 列出活跃会话，包含运行时长、缓冲区类型及详细信息
pty-bridge kill <id>                                # 终止会话
pty-bridge resize <id> <cols> <rows>                # 调整终端尺寸
pty-bridge status                                   # 显示守护进程状态（PID、内存、会话数）

Start Options

启动选项

bash

pty-bridge start ssh user@host --keepalive 30    # Send keepalive every 30s (prevents SSH timeout)
pty-bridge start cmd --wait 1000                 # Wait 1000ms before returning initial output (default: 500ms)

bash

pty-bridge start ssh user@host --keepalive 30    # 每30秒发送一次保活信号（防止SSH超时）
pty-bridge start cmd --wait 1000                 # 返回初始输出前等待1000ms（默认：500ms）

Read Options

读取选项

bash

pty-bridge read <id> --buffer normal      # Read from normal buffer (even if alternate is active)
pty-bridge read <id> --buffer alternate   # Read from alternate buffer
pty-bridge read <id> --buffer active      # Read from whichever buffer is active (default)

bash

pty-bridge read <id> --buffer normal      # 从常规缓冲区读取内容（即使交替缓冲区处于活跃状态）
pty-bridge read <id> --buffer alternate   # 从交替缓冲区读取内容
pty-bridge read <id> --buffer active      # 从当前活跃的缓冲区读取内容（默认行为）

Exec Options

执行选项

bash

pty-bridge exec <id> "make build" --wait-for-idle 500          # Poll every 500ms, return when output stabilizes (max 5s)
pty-bridge exec <id> "make build" --wait-for-idle 500 --wait 10000  # Same but max wait 10s

bash

pty-bridge exec <id> "make build" --wait-for-idle 500          # 每500ms轮询一次，输出稳定后返回（最长等待5s）
pty-bridge exec <id> "make build" --wait-for-idle 500 --wait 10000  # 同上，但最长等待10s

Snapshot

屏幕快照

bash

pty-bridge snapshot <id>    # Returns current visible screen: lines, cursor position, buffer type, dimensions

bash

pty-bridge snapshot <id>    # 返回当前可见屏幕内容：行数、光标位置、缓冲区类型、尺寸

Special Keys

特殊按键

enter, tab, escape, space, backspace, delete, up, down, left, right, home, end, pageup, pagedown, ctrl-a through ctrl-z, ctrl-\, ctrl-]

Workflow Patterns

工作流模式

SSH Session (recommended)

SSH会话（推荐）

bash

pty-bridge start ssh user@host --keepalive 30
pty-bridge read <id>

bash

pty-bridge start ssh user@host --keepalive 30
pty-bridge read <id>

If password prompt:

如果出现密码提示：

echo -n "password" | pty-bridge write <id> --stdin pty-bridge sendkey <id> enter pty-bridge read <id>

Run commands (exec = write + enter + wait + read, one step):

运行命令（exec = 写入+回车+等待+读取，一步完成）：

pty-bridge exec <id> "ls -la" pty-bridge exec <id> "df -h"

For slow commands, increase wait time:

对于慢速命令，增加等待时间：

pty-bridge exec <id> "apt update" --wait 5000

Disconnect:

断开连接：

pty-bridge exec <id> "exit"

undefined

pty-bridge exec <id> "exit"

undefined

Wait for Service Startup

等待服务启动

bash

pty-bridge start ssh user@host --keepalive 30
pty-bridge exec <id> "docker compose up -d"
pty-bridge exec <id> "docker logs -f myservice" --wait 1000

bash

pty-bridge start ssh user@host --keepalive 30
pty-bridge exec <id> "docker compose up -d"
pty-bridge exec <id> "docker logs -f myservice" --wait 1000

Block until service is ready:

阻塞直到服务就绪：

pty-bridge wait-for <id> "Uvicorn running" --timeout 120

Or wait for model loading:

或等待模型加载完成：

pty-bridge wait-for <id> "Started" --timeout 300

undefined

pty-bridge wait-for <id> "Started" --timeout 300

undefined

Interactive REPL

交互式REPL

bash

pty-bridge start python3
pty-bridge exec <id> "print('hello')"
pty-bridge exec <id> "2 + 2"
pty-bridge sendkey <id> ctrl-d

bash

pty-bridge start python3
pty-bridge exec <id> "print('hello')"
pty-bridge exec <id> "2 + 2"
pty-bridge sendkey <id> ctrl-d

Handling Prompts

处理提示信息

bash

pty-bridge start some-installer
pty-bridge read <id>
pty-bridge write <id> "yes"
pty-bridge sendkey <id> enter
pty-bridge read <id>

bash

pty-bridge start some-installer
pty-bridge read <id>
pty-bridge write <id> "yes"
pty-bridge sendkey <id> enter
pty-bridge read <id>

Output Format Convention

输出格式约定

stdout: command output (the actual PTY content)

stderr: metadata line in

[key=value ...]

format, e.g.

[lines=42 alive=true buffer=normal exitCode=0]

```
read
```
returns output on stdout, session metadata on stderr — parse stderr for session state
```
exec
```
returns command output on stdout — check
```
isAlive
```
and
```
exitCode
```
in the stderr line or JSON response
```
snapshot
```
prints a header line
```
[buffer=... cursor=... size=...]
```
then the screen content
```
status
```
output is human-readable text (parse with regex if needed)

stdout: 命令输出（实际PTY内容）

stderr: 元数据行，格式为

[key=value ...]

，例如

[lines=42 alive=true buffer=normal exitCode=0]

```
read
```
在stdout返回输出，在stderr返回会话元数据——解析stderr可获取会话状态
```
exec
```
在stdout返回命令输出——检查stderr行或JSON响应中的
```
isAlive
```
和
```
exitCode
```
```
snapshot
```
先打印头行
```
[buffer=... cursor=... size=...]
```
，然后输出屏幕内容
```
status
```
输出为人类可读文本（如需解析可使用正则表达式）

Error Recovery

错误恢复

Symptom	Cause	Action
`command not found: pty-bridge`	Not installed	Run install command above
`connect ENOENT` or socket timeout	Daemon died or not started	`pty-bridge status` ; daemon auto-starts on next `start`
SSH password prompt	Interactive auth required	Use `pty-bridge write <id> "password" --stdin` then `sendkey enter`
`waitFor` timeout	Pattern never appeared	Check the partial output returned; pattern may have typo or command failed silently
npm install fails	Missing build tools	Install build-essential + python3 (see Installation section)
PTY output is empty/garbled	TUI app in alternate screen	Use `snapshot <id>` instead of `read` ; or `read <id> --buffer alternate`

症状	原因	操作
`command not found: pty-bridge`	未安装	运行上述安装命令
`connect ENOENT` 或套接字超时	守护进程已终止或未启动	执行 `pty-bridge status` ；下次执行 `start` 时守护进程会自动启动
SSH密码提示	需要交互式认证	使用 `pty-bridge write <id> "password" --stdin` ，然后执行 `sendkey enter`
`waitFor` 超时	未匹配到指定模式	检查返回的部分输出；模式可能存在拼写错误或命令已静默失败
npm安装失败	缺少构建工具	安装build-essential + python3（参见安装部分）
PTY输出为空/乱码	TUI应用处于交替屏幕	使用 `snapshot <id>` 替代 `read` ；或使用 `read <id> --buffer alternate`

Important Notes

重要注意事项

Prefer
exec
over
write
+
sendkey enter
—
```
exec
```
combines write, enter, wait, and read into one call, returning only the new output.
read
is incremental by default — it returns only output since the last read. Use
```
read <id> --full
```
to get the entire buffer.
Use
wait-for
for long operations — instead of
```
sleep N && read
```
, use
```
wait-for <id> "pattern" --timeout N
```
to block until specific output appears.
```
write
```
sends text as-is — use
```
sendkey enter
```
afterward to submit (or just use
```
exec
```
).

For secrets, pipe via stdin:

echo -n "password" | pty-bridge write <id> --stdin

Always
```
kill
```
sessions when done to free resources.
The daemon auto-exits after 5 minutes when no alive sessions remain.
Use
```
ctrl-c
```
via sendkey to interrupt stuck commands.
Terminal defaults to 120x40. Use
```
resize
```
for TUI apps that need specific dimensions.
Client socket timeout is configurable via
```
PTY_BRIDGE_TIMEOUT
```
environment variable (ms, default: 30000).

优先使用
exec
而非
write
+
sendkey enter
—
```
exec
```
将写入、回车、等待和读取合并为一次调用，仅返回新输出。
read
默认增量读取 — 仅返回自上次读取后的输出。使用
```
read <id> --full
```
获取全部缓冲区内容。
长操作使用
wait-for
— 不要使用
```
sleep N && read
```
，而是使用
```
wait-for <id> "pattern" --timeout N
```
阻塞直到出现指定输出。
```
write
```
会原样发送文本 — 之后需使用
```
sendkey enter
```
提交（或直接使用
```
exec
```
）。
对于敏感信息，通过标准输入管道传输：
```
echo -n "password" | pty-bridge write <id> --stdin
```
会话使用完毕后务必执行
```
kill
```
以释放资源。
当没有活跃会话时，守护进程会在5分钟后自动退出。
使用
```
sendkey
```
发送ctrl-c以中断卡住的命令。
终端默认尺寸为120x40。对于需要特定尺寸的TUI应用，使用
```
resize
```
调整。
客户端套接字超时可通过
```
PTY_BRIDGE_TIMEOUT
```
环境变量配置（单位：ms，默认值：30000）。