# CLI 参考手册

## 基本用法

直接运行命令即可，无需参数：

```bash
npx termbridge
```

这会启动所有组件：本地服务器、tmux 会话和默认的 Cloudflare 隧道。

不带子命令运行 `termbridge` 等同于 `termbridge start`。

也可以显式运行 `termbridge start` 并指定所有标志：

```bash
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](https://github.com/inline0/termbridge/issues/5)）。

> **注意**
> 内置的 `termbridge --help` 输出仍会列出 `--daytona-*` 标志和 `--backend tmux | daytona`。这些名称已被弃用；请改用上表中的 `--sandbox-*` 标志和 `--backend sandbox-daytona`（[#1](https://github.com/inline0/termbridge/issues/1)）。

## 示例

### 接入现有的 tmux 会话

如果你已经有一个正在运行的 tmux 会话：

```bash
termbridge --session my-session
```

### 固定端口和自定义会话

```bash
termbridge --port 8080 --session codex
```

### 正常退出（不遗留会话）

```bash
termbridge --kill-on-exit
```

### 脚本用法（无 QR 输出）

```bash
termbridge --no-qr
```

### 代理 Vite 开发服务器

```bash
# 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 的速率限制：

```bash
termbridge --port 8080 --tunnel-token <TOKEN> --tunnel-url https://term.example.com
```

### 禁用隧道（使用自己的公共 URL）

```bash
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 指南](https://termbridge.inline0.dev/zh/docs/sandboxes/daytona)。

## 停止 Termbridge

在运行 Termbridge 的终端中按 `Ctrl+C`。这会：

- 关闭隧道（如果已启用）
- 停止本地服务器
- 保持 tmux 会话运行（除非你使用了 `--kill-on-exit`）

默认情况下，tmux 会话会持续保留，因此你可以稍后重新连接。