CLI 树

ChatUp 使用一等顶层命令，但不把不同浏览器制品和工具链强行统一成一个 browser 抽象。Chrome for Testing、ChromeDriver 和 Playwright 各自拥有独立命令集、Python API、metadata 和存储目录。

顶层命令

chatup
├── --help              # 显示当前命令帮助
├── --version           # 输出当前包版本
├── --tree              # 输出带参数签名的真实已注册 CLI 树
├── --tree-brief        # 输出不带参数签名的同一棵 CLI 树
├── doctor              # 验证 ChatUp CLI 可调用
├── zsh                 # 配置 zsh、插件和 alias
├── cc-connect          # 安装 ChatArch CC Connect
├── gitea               # 安装 ChatTea-compatible Gitea
├── glance              # 安装已校验的 ChatArch Glance 本地运行时（不启动）
├── discourse           # 准备 Discourse 配置和 ChatEnv 管理的管理员凭据
├── zulip               # 准备 Zulip Compose 和 ChatEnv 管理的管理员凭据
├── mysql               # 安装 ChatData-compatible MySQL
├── twikoo              # 安装多实例 Twikoo 评论服务
├── nginx               # 准备 user-level NGINX
├── crs                 # 安装本地 Claude Relay Service + Redis
├── claude              # 安装/配置 Claude Code
├── docker              # 检查 Docker 环境与权限
├── frp                 # 安装 FRP Client/Server
├── nodejs              # 安装默认 LTS Node.js（POSIX 使用 nvm，Windows 使用 ChatArch 便携 ZIP）
├── uv                  # 安装 uv 和 ~/.chatarch/venv
├── chatgpt              # 安装新版 ChatGPT 桌面应用（含 Codex）
├── codex               # 配置 Codex CLI 和配置文件（设置时使用 CODEX_HOME）
├── cursor-agent        # 安装/配置 Cursor Agent CLI
├── opencode            # 安装/配置 OpenCode
├── lark-cli            # 配置官方 lark-cli 与 ChatEnv
├── hermes              # 安装 Hermes Agent 与可选 WebUI
├── workspace           # 初始化 ChatArch workspace
├── chrome              # 按当前系统安装普通 Google Chrome
├── snipaste            # 在 macOS 或 Windows 安装 Snipaste
├── iterm               # 安装 iTerm2（仅限 macOS）
├── macos               # 勾选 macOS 应用，Apple Silicon 可选 Blender
├── remotion            # 初始化带锁定依赖的本地视频项目
├── chrome-for-testing  # 管理 Google Chrome for Testing 浏览器
├── chromedriver        # 管理 ChromeDriver WebDriver server
└── playwright          # 管理 Playwright package 与 Chromium browser

运行 chatup --tree 可回读带参数签名和命令目的的真实注册树；chatup --tree-brief 保留相同节点和说明，但省略参数签名。完整参数见 命令参考。

Glance 本地运行时

chatup glance [--version latest|chatarch-vMAJOR.MINOR.PATCH] [--runtime-home PATH] [--dry-run] [-i|-I]

裸命令执行真实安装：仅支持当前发布矩阵中的 Linux amd64，下载 ChatArch/glance 的精确归档、SHA256SUMS 和 BUILDINFO.txt，完整校验后复用 ChatGlance portable API。默认目录为有效 ChatArch home 下的 glance；保留已有配置和数据，不启动服务。升级或更换已安装版本必须显式使用 chatglance runtime update。

Python 运行环境

chatup uv
├── --venv, --venv-path PATH           # 目标 venv，默认 ~/.chatarch/venv
├── --python, --python-version TEXT   # Python 版本，默认 3.12
├── -f, --force                       # 显式重建环境
├── --activate / --no-activate        # 更新已有 Bash/Zsh rc，默认开启
└── --log-level TEXT                  # 日志级别

不创建缺失的 rc 文件；Windows 跳过此项。--no-activate 保持现有启动配置不变。详见快速开始。

macOS 常用应用

chatup macos [--app snipaste|iterm|chrome|blender]... [--dry-run] [--log-level LEVEL] [-i|-I]

仅限 macOS，Apple Silicon 默认勾选 Snipaste、iTerm2、Chrome、Blender；Intel 保持前三项。空格切换、回车安装；可重复 --app 选择子集，-I 不询问，--dry-run 只预览。详见macOS 安装约定。

Remotion 视频项目

chatup remotion [PROJECT_DIR] [--browser-executable PATH] [--dry-run] [--log-level LEVEL] [-i|-I]

创建锁定依赖的本地视频项目。缺少目录时在终端中询问；不覆盖已有无关目录。项目安装、运行环境要求和浏览器策略见 Remotion 约定。

Chrome、Snipaste 与 iTerm2

chatup chrome [--dry-run] [--sudo] [-y|--yes] [--log-level LEVEL]
chatup snipaste [--dry-run] [-y|--yes] [--log-level LEVEL]
chatup iterm [--dry-run] [--log-level LEVEL]

Chrome 安装普通系统浏览器；Snipaste 支持 macOS 和 Windows；iTerm2 仅限 macOS。详见安装约定。

ChatGPT 桌面应用

chatup chatgpt
├── --dry-run   # 只显示安装计划，不执行
└── -y, --yes   # 接受 Windows Store 来源和包协议

安装含 Codex 的新版 ChatGPT 桌面应用，不是 Codex CLI 或 ChatGPT Classic。macOS 走 Homebrew，Windows 使用官方 Microsoft Store 精确 ID。前提、Linux preview 指引、原生目录和 Python 接口见桌面安装约定。

Twikoo

chatup twikoo
├── --version VERSION
├── --repo OWNER/REPO
├── --home PATH
├── --name INSTANCE
├── --port PORT
├── --bind-address ADDRESS
├── --install / --no-install
├── --init / --no-init
├── --service / --no-service
├── --start / --no-start
├── --smoke / --no-smoke
└── --force

chatup twikoo 使用 Twikoo GitHub Release 二进制，并按多实例布局准备 ~/.chatarch/twikoo/instances/<name>/。每个实例都有自己的 bin/twikoo 和相邻 bin/.env -> ../env/twikoo.env，避免多个实例共享 runtime 旁边的 .env 导致端口或数据目录串扰。默认只绑定 127.0.0.1，外部 local/public 域名入口交给 NGINX/public-entry 层。

Cursor Agent

chatup cursor-agent
├── --auth-json PATH
├── --auth-env PATH
├── -e, --env FILE_OR_PROFILE
├── --env-profile NAME
├── --save-profile NAME
├── --cli-config PATH
├── --agent-state PATH
├── --api-key-env NAME
├── --credential-store native|file-wrapper
├── --install-only
├── --verify / --no-verify
└── -i / -I

cursor-agent 管理 Cursor Agent CLI 的安装和登录态文件复制，并注册 ChatEnv CursorAgent 配置类型。它不在 argv 或输出中打印 token；auth.json、cli-config.json、agent-cli-state.json 这些 Cursor 自身文件会安全写入，ChatEnv profile .env 则交给 ChatEnv 自己维护。-e/--env 可快速读取 env 文件或 ChatEnv profile。在 macOS 上迁移 Linux 文件登录态时，可用 --credential-store file-wrapper 写入不含 token 的 wrapper。

常用迁移形式：

chatup cursor-agent --auth-json ./auth.json --cli-config ./cli-config.json --agent-state ./agent-cli-state.json --credential-store file-wrapper -I
chatup cursor-agent -e ./cursor.env --credential-store file-wrapper -I
chatup cursor-agent -e work --credential-store file-wrapper -I

制品身份

Backend	实际制品	角色
chrome-for-testing	Google Chrome for Testing	可启动的浏览器；支持扩展和 CDP
chromedriver	ChromeDriver	WebDriver 协议 server；不是浏览器
playwright	Playwright package + Playwright Chromium	固定 package、revision、browser version 与 executable path

Chrome for Testing 是 Google 官方发行名称。命令中的 for-testing 描述制品身份，不表示 ChatUp 暴露了一个 test 操作；三个 backend 都没有 test 子命令，健康检查统一叫 doctor。

当前不注册 chatup chromium。只有选定并验证真实 Chromium 下载源、revision contract、平台布局和验收方式后，才会新增独立 Chromium backend。

Chrome for Testing

chatup chrome-for-testing
├── install
│   ├── --version VERSION
│   ├── --channel stable|beta|dev|canary
│   ├── --platform PLATFORM
│   ├── --home PATH
│   ├── --sha256 HEX
│   ├── --force
│   ├── --doctor / --no-doctor
│   ├── --output text|json
│   └── -i / -I
├── list [--home PATH] [--output text|json]
├── show [VERSION] [--platform PLATFORM] [--output text|json] [-i|-I]
├── path [VERSION] [--platform PLATFORM] [--output text|json] [-i|-I]
├── doctor [VERSION] [--execute|--no-execute] [--output text|json] [-i|-I]
├── remove [VERSION] --yes [--output text|json] [-i|-I]
└── gc [--dry-run|--apply] [--yes] [--minimum-age-hours HOURS]

install 的 --version 与 --channel 互斥；都不提供时默认使用 stable。resolve 类操作只接受完整四段版本，不能使用 channel 或旧的 chrome@... / cft@... 引用。

chatup chrome-for-testing install --channel stable -I
chatup chrome-for-testing install --version 145.0.7632.6 --output json -I
chatup chrome-for-testing path 145.0.7632.6 -I
chatup chrome-for-testing doctor 145.0.7632.6 --output json -I

ChromeDriver

chatup chromedriver
├── install
│   ├── --version VERSION
│   ├── --channel stable|beta|dev|canary
│   ├── --match-browser PATH
│   ├── --match-cft-version VERSION
│   ├── --platform PLATFORM
│   ├── --home PATH
│   ├── --sha256 HEX
│   ├── --force
│   ├── --doctor / --no-doctor
│   ├── --output text|json
│   └── -i / -I
├── list [--home PATH] [--output text|json]
├── show [VERSION] [--platform PLATFORM] [--output text|json] [-i|-I]
├── path [VERSION] [--platform PLATFORM] [--output text|json] [-i|-I]
├── doctor [VERSION] [--execute|--no-execute] [--output text|json] [-i|-I]
├── remove [VERSION] --yes [--output text|json] [-i|-I]
└── gc [--dry-run|--apply] [--yes] [--minimum-age-hours HOURS]

四个安装选择器互斥。--match-browser 读取给定浏览器 binary 的 --version，先按 Google 官方 build manifest 匹配，找不到时退回 milestone manifest；浏览器 patch 与最终 Driver patch 不必相同。--match-cft-version 直接使用精确 CFT 版本。ChromeDriver 不参与 ChatPost 当前的扩展/CDP 知乎链路。

chatup chromedriver install --channel stable -I
chatup chromedriver install --match-cft-version 145.0.7632.6 -I
chatup chromedriver install --match-browser /path/to/browser --output json -I

Playwright

chatup playwright
├── install [VERSION]
│   ├── --browser chromium
│   ├── --home PATH
│   ├── --force
│   ├── --doctor / --no-doctor
│   ├── --output text|json
│   └── -i / -I
├── path [VERSION] [--browser chromium] [--output text|json] [-i|-I]
└── doctor [VERSION] [--execute|--no-execute] [--output text|json] [-i|-I]

Playwright backend 接受精确三段 package 版本。install 使用可用的 Node.js/npm 安装该 package，并把它声明的 Chromium revision 下载到同一个 ChatArch-owned installation；path 返回 Playwright 自身解析出的 executable。它不创建 Profile、不启动浏览器，也不安装 ChromeDriver。

chatup nodejs -I
chatup playwright install 1.61.1 --output json -I
chatup playwright path 1.61.1 -I
chatup playwright doctor 1.61.1 --output json -I

独立存储

~/.chatarch/
├── chrome-for-testing/
│   └── <version>/<platform>/
│       ├── installation.json
│       └── <Google archive tree>/
├── chromedriver/
│   └── <version>/<platform>/
│       ├── installation.json
│       └── <Google archive tree>/
└── playwright/
    └── <playwright-version>/<browser>/
        ├── installation.json
        ├── package/
        └── browsers/

Chrome for Testing 与 ChromeDriver 使用官方 Google HTTPS 制品、可选 SHA-256、受限 ZIP 解压和原子目录替换。Playwright 使用 npm package 完整性与 Playwright 自身 browser manifest/download 流程，并同样采用原子安装目录。三个 backend 都不修改系统 Chrome，不创建 Profile，不保存 Cookie，也不管理账号或扩展。

remove 必须显式传 --yes。gc 默认 dry-run，只处理超过最小年龄的 backend 临时/backup 目录；实际清理同时需要 --apply --yes。

ChatStyle 交互

可恢复缺参通过 ChatStyle CommandSchema 处理：

• -i 强制当前子命令的缺参补问；
• -I 禁止补问，缺少 required 值时快速失败；
• CHATARCH_AUTO_PROMPT=0/false/no/off 关闭默认自动补问；
• CLI 参数和 prompt 返回值使用相同校验；
• 删除/清理不会通过默认确认 prompt 放宽，仍需要 --yes。

Python API

消费方选择精确 backend module，不经过通用 Browser base：

from chatup.chrome_for_testing import resolve as resolve_cft
from chatup.chromedriver import resolve as resolve_driver
from chatup.playwright import resolve as resolve_playwright

browser = resolve_cft("145.0.7632.6")
driver = resolve_driver("145.0.7632.6")
playwright_browser = resolve_playwright("1.61.1", browser="chromium")
print(browser.binary_path)
print(driver.binary_path)
print(playwright_browser.binary_path)

ChatPost 可以按任务选择 chatup.chrome_for_testing 或 chatup.playwright descriptor。它继续自己管理 isolated user-data-dir、Runner process、CDP/bridge、扩展、人工登录、账号映射和 publication ledger。