CLI 参考手册
基本用法
直接运行命令即可，无需参数：
命令行
npx termbridge
这会启动所有组件：本地服务器、tmux 会话和默认的 Cloudflare 隧道。
不带子命令运行 termbridge 等同于 termbridge start。
也可以显式运行 termbridge start 并指定所有标志：
命令行
termbridge start --port 8080 --proxy 5173 --session dev --kill-on-exit --no-qr --tunnel cloudflare
标志
| 标志 | 作用 | 默认值 |
|---|---|---|
--port <port> |
使用指定端口，而不是随机端口 | 随机 |
--proxy <port> |
代理本地开发服务器（启用 Terminal/Preview 视图） | - |
--session <name> |
为你的 tmux 会话命名 | 自动生成 |
--kill-on-exit |
在 Termbridge 退出时清理 tmux 会话 | 关闭 |
--no-qr |
不打印 QR 代码（适用于脚本） | 关闭 |
--no-tunnel |
禁用隧道（需要 --public-url） |
关闭 |
--public-url <url> |
禁用隧道时使用的公共 URL | - |
--tunnel <provider> |
隧道提供商（cloudflare 或 none） |
cloudflare |
--tunnel-token <token> |
使用命名的 Cloudflare Tunnel 令牌（需要 --port） |
- |
--tunnel-url <url> |
命名隧道的公共 URL（与 --tunnel-token 一起使用时必需） |
- |
--backend <backend> |
终端后端（tmux 或 sandbox-daytona） |
tmux |
--sandbox-repo <url> |
要克隆到 Daytona 沙盒中的仓库 URL | - |
--sandbox-branch <branch> |
要在沙盒中检出的分支 | - |
--sandbox-path <path> |
沙盒中的仓库路径 | 根据仓库名称推导 |
--sandbox-name <name> |
沙盒名称 | 随机 termbridge-<hex> |
--sandbox-preview-port <port> |
沙盒中的预览端口 | - |
--sandbox-public |
创建公共沙盒 | 关闭（直接模式下开启） |
--sandbox-direct |
在 Daytona 沙盒内运行服务器（无隧道） | 关闭 |
--dev-proxy-url <url> |
将预览流量代理到此 URL，而不是 localhost:<proxy port>（供开发脚本使用） |
- |
-h、--help |
打印帮助文本 | - |
任何其他选项都会因 unknown option: <flag> 而失败。没有 --version 标志。
命令行标志优先于对应的环境变量，只有一个例外：TERMBRIDGE_TUNNEL 当前会覆盖 --tunnel 和 --no-tunnel（#5）。
注意 内置的
termbridge --help输出仍会列出--daytona-*标志和--backend tmux | daytona。这些名称已被弃用；请改用上表中的--sandbox-*标志和--backend sandbox-daytona（#1）。
示例
接入现有的 tmux 会话
如果你已经有一个正在运行的 tmux 会话：
命令行
termbridge --session my-session
固定端口和自定义会话
命令行
termbridge --port 8080 --session codex
正常退出（不遗留会话）
命令行
termbridge --kill-on-exit
脚本用法（无 QR 输出）
命令行
termbridge --no-qr
代理 Vite 开发服务器
命令行
# Start your Vite app first
cd my-app && npm run dev # runs on port 5173
# Then start Termbridge with proxy
termbridge --proxy 5173
使用 Views 按钮在终端和预览之间切换。预览会通过代理加载你的应用，并支持 HMR。
命名的 Cloudflare 隧道（基于令牌）
如果你有 Cloudflare 账户，并希望避免 trycloudflare 的速率限制：
命令行
termbridge --port 8080 --tunnel-token <TOKEN> --tunnel-url https://term.example.com
禁用隧道（使用自己的公共 URL）
命令行
termbridge --no-tunnel --public-url https://example.com
环境变量
Termbridge 会从 shell 和运行它所在目录中的 .env 文件读取环境变量。shell 中已设置的变量优先于 .env 文件中的变量。
核心设置
| 变量 | 作用 |
|---|---|
TERMBRIDGE_SESSIONS=2 |
启动时创建多个 tmux 会话 |
TERMBRIDGE_TMUX_CWD=/path |
新建 tmux 会话的工作目录 |
TERMBRIDGE_PUBLIC_URL=https://example.com |
隧道禁用时使用的公共 URL |
TERMBRIDGE_TUNNEL=none |
禁用隧道 |
TERMBRIDGE_TUNNEL_TOKEN=<token> |
命名隧道令牌（需要 TERMBRIDGE_TUNNEL_URL） |
TERMBRIDGE_TUNNEL_URL=https://term.example.com |
命名隧道的公共 URL |
高级设置
Daytona 直连模式会为其在沙盒中运行的服务器设置这些变量。你也可以自行设置。
| 变量 | 作用 |
|---|---|
TERMBRIDGE_HOST=0.0.0.0 |
服务器绑定的地址（默认值为 127.0.0.1）。打印出的本地 URL 始终显示 127.0.0.1。 |
TERMBRIDGE_COOKIE_SAMESITE=lax |
会话 Cookie 的 SameSite 值：lax、strict 或 none（默认值为 Lax，直连模式下为 None） |
TERMBRIDGE_SHARE_FILE=/path/share-url.txt |
同时将共享 URL 写入此文件 |
TERMBRIDGE_HIDE_TERMINAL_SWITCHER=1 |
在 UI 中隐藏终端切换器 |
TERMBRIDGE_TMUX_PATH_PREFIX=/path/bin |
在每个 tmux 会话中，将此内容添加到 PATH 开头，Termbridge 启动或接入会话时生效（作为 export 命令输入会话） |
开发
| 变量 | 作用 |
|---|---|
TERMBRIDGE_INSECURE_COOKIE=1 |
允许 HTTP Cookie（仅限本地开发） |
TERMBRIDGE_PROXY_PORT=5173 |
dev:beam:proxy 脚本的代理端口 |
TERMBRIDGE_DEV_UI=http://127.0.0.1:5000 |
覆盖 Vite 开发 UI URL |
TERMBRIDGE_DEV_PORT=3000 |
覆盖开发环境中的 Termbridge 服务器端口（默认值为 8787） |
TERMBRIDGE_DEV_SESSION=codex |
dev:beam 的 tmux 会话名称（默认值为 codex） |
TERMBRIDGE_SKIP_BUILD=1 |
在 dev:beam 中跳过 CLI 构建 |
沙盒（Daytona）
| 变量 | 作用 |
|---|---|
TERMBRIDGE_BACKEND=sandbox-daytona |
使用 Daytona 沙盒后端 |
TERMBRIDGE_SANDBOX_DIRECT=true |
在沙盒中运行 Termbridge |
TERMBRIDGE_SANDBOX_SERVER_PORT=8080 |
沙盒服务器的端口 |
TERMBRIDGE_SANDBOX_AGENTS=claude-code,codex |
为代理自动安装并同步身份验证 |
TERMBRIDGE_SANDBOX_AGENT_ENV=... |
要转发的额外环境变量 |
TERMBRIDGE_SANDBOX_AGENT_AUTH_PATHS=... |
要同步的本地身份验证文件 |
完整的 Daytona 配置请参阅 Daytona 指南。
停止 Termbridge
在运行 Termbridge 的终端中按 Ctrl+C。这会：
- 关闭隧道（如果已启用）
- 停止本地服务器
- 保持 tmux 会话运行（除非你使用了
--kill-on-exit）
默认情况下，tmux 会话会持续保留，因此你可以稍后重新连接。