命令参考¶

本页只列当前已经实现的 chatup 一级命令。运行时以 chatup <command> --help 为准。

CLI 树¶

ChatUp 当前采用一级命令结构，没有 chatup setup ... 子树。所有安装、初始化和配置能力都直接挂在 chatup 下：

chatup
|-- doctor      # 检查 ChatUp 是否可调用
|-- uv          # 安装 uv，并创建默认 ChatArch Python 运行环境
|-- workspace   # 初始化 ChatArch workspace scaffold
|-- nodejs      # 安装 nvm 和默认 LTS Node.js
|-- docker      # 检查 Docker 环境，并提示 sudo 配置
|-- zsh         # 配置 zsh / oh-my-zsh / 插件 / alias
|-- chrome-for-testing # 管理 Google Chrome for Testing 浏览器
|-- chromedriver       # 管理 ChromeDriver WebDriver server
|-- playwright         # 管理 Playwright package 与 Chromium browser
|-- frp         # 安装 FRP Client/Server
|-- gitea       # 安装 ChatTea-compatible Gitea runtime/config/service
|-- discourse   # 准备 Discourse docker 配置和 ChatEnv 管理的管理员凭据
|-- zulip       # 准备 Zulip Docker Compose 配置和 ChatEnv 管理的管理员凭据
|-- mysql       # 安装 ChatData-compatible MySQL runtime/instance/service
|-- twikoo      # 安装多实例 Twikoo 评论服务 runtime/instance/service
|-- nginx       # 准备 user-level NGINX runtime，并生成入口模板
|-- crs         # 安装本地 Claude Relay Service + Redis + smoke check
|-- cc-connect  # 安装 CC Connect CLI 和运行依赖
|-- claude      # 配置 Claude Code CLI 和配置文件
|-- codex       # 配置 Codex CLI 和配置文件
|-- cursor-agent # 配置 Cursor Agent CLI 登录态和配置文件
|-- opencode    # 配置 OpenCode CLI 和配置文件
|-- hermes      # 安装 Hermes Agent 和可选 WebUI
`-- lark-cli    # 配置官方 lark-cli，并复用 ChatEnv 飞书配置

命令分组速览¶

基础环境

doctor、uv、nodejs、docker、zsh、chrome-for-testing、chromedriver、playwright、frp 负责机器级运行环境准备和检查。
本地服务

gitea、discourse、zulip、mysql、twikoo、nginx、crs 负责 ChatArch 常用本地服务，默认落在 ~/.chatarch/...，其中 Discourse/Zulip 管理员凭据从 ChatEnv 读取。
Agent 工具链

claude、codex、cursor-agent、opencode、hermes、cc-connect、lark-cli 负责模型、Agent 和飞书工具链配置。
工作区

workspace 创建 ChatArch 人类-AI 协作目录结构和项目记录入口。

基础命令¶

命令	当前能力
`chatup doctor`	检查 ChatUp 是否可调用。
`chatup uv`	安装 `uv` 并创建 ChatArch Python 运行环境。
`chatup nodejs`	安装 nvm 和默认 LTS Node.js。
`chatup docker`	检查 Docker 环境，并在需要时给出 sudo 相关建议。
`chatup zsh`	配置 zsh、oh-my-zsh、插件、主题和 shell alias。
`chatup chrome-for-testing`	独立管理 Google Chrome for Testing 浏览器及其 JSON/Python descriptor。
`chatup chromedriver`	独立管理 ChromeDriver WebDriver server，可匹配 CFT 或指定浏览器版本。
`chatup playwright`	安装精确 Playwright package 与其管理的 Chromium，并输出可复用 descriptor。
`chatup frp`	安装 FRP Client/Server。

Agent 与工具链¶

命令	当前能力
`chatup claude`	配置 Claude Code CLI 和配置文件。
`chatup codex`	配置 Codex CLI 和配置文件。
`chatup cursor-agent`	安装/验证 Cursor Agent CLI，并安全复制 `auth.json`、`cli-config.json` 和 `agent-cli-state.json`。
`chatup opencode`	配置 OpenCode CLI 和配置文件。
`chatup hermes`	安装 Hermes Agent 和可选 Hermes WebUI。
`chatup cc-connect`	安装 CC Connect CLI 和运行依赖。
`chatup lark-cli`	配置官方 lark-cli，并复用 ChatEnv 飞书配置。

Codex 命令约定¶

chatup codex 配置 OpenAI Codex CLI（~/.codex/config.toml 与 ~/.codex/auth.json）：

-e, --env VALUE 是凭据来源：VALUE 是文件路径时按 env 文件读取，否则按 ChatEnv OpenAI profile 名读取。
当 -e PROFILE 选择 ChatEnv profile 时，ChatUp 只读取这个显式 profile，不会从 active profile、既有 Codex 配置或进程环境变量回填缺失的 secret；profile 文件按无插值方式读取，包含 ${...} 这类未解析变量会失败而不会回填进程环境。
ChatEnv profile 名不能包含路径分隔符、. 或 ..；如果要传文件路径，该路径必须真实存在。
如果显式 profile 缺少 OPENAI_API_KEY，非交互 setup 会失败，不会把另一个账号的 key 写进 Codex。
Codex CLI 0.144+ 要求 wire_api = "responses"；chatup codex 写出的 CRS/OpenAI-compatible provider 使用 responses wire API。
模型渠道要通过 Codex 本身验证，例如先 chatup codex -e apple -I，再 codex exec ...；只 curl API 成功不等于 Codex 路由可用。

常用形式：

chatup codex -e apple -I
chatup codex -e ~/.chatarch/envs/OpenAI/.env -I
chatup codex --api-key "$OPENAI_API_KEY" --base-url https://example.invalid/openai/v1 --model gpt-5.5 -I

Cursor Agent 命令约定¶

chatup cursor-agent 面向 Cursor Agent CLI，而不是 Cursor IDE GUI：

--auth-json PATH 复制包含 accessToken / refreshToken 的 Cursor auth.json；
--auth-env PATH 从 env 文件读取 CURSOR_ACCESS_TOKEN 和 CURSOR_REFRESH_TOKEN 后写成 Cursor JSON；
-e, --env VALUE 快速读取 Cursor 凭据：VALUE 是文件路径时按 env 文件读取，否则按 ChatEnv CursorAgent profile 名读取；
--env-profile NAME 从 ChatEnv CursorAgent profile 读取 token 并写成 Cursor JSON；
--save-profile NAME 把导入的 token 保存到 ChatEnv CursorAgent profile，不打印 secret 值；
--cli-config PATH 复制 ~/.cursor/cli-config.json；
--agent-state PATH 复制 ~/.cursor/agent-cli-state.json；
--api-key-env NAME 仅把指定环境变量作为验证时的 CURSOR_API_KEY，不会把 secret 放进 argv；
--credential-store file-wrapper 会写入不含 token 的 cursor-agent wrapper，在运行时从 auth.json 读取 token 并使用文件登录态，适合把 Linux auth.json 迁移到 macOS；
写入 Cursor 自身登录态/配置文件时会使用受限权限；ChatEnv CursorAgent profile 由 ChatEnv 自己的存储机制维护，ChatUp 不额外改 profile .env 权限。

常用形式：

chatup cursor-agent --install-only -I
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 --auth-env ./cursor.env --save-profile work --credential-store file-wrapper -I
chatup cursor-agent -e work --credential-store file-wrapper -I

本地服务¶

命令	当前能力
`chatup gitea`	从 `ChatArch/gitea` Release assets 安装 ChatArch Gitea；默认跟随 latest，可选生成 ChatTea-compatible `app.ini` 和 user-level systemd service。
`chatup discourse`	准备 `~/.chatarch/discourse` 下的 Discourse Docker/app.yml 布局，并从 ChatEnv 读取 `DISCOURSE_ADMIN_USERNAME`、`DISCOURSE_ADMIN_EMAIL`、`DISCOURSE_ADMIN_PASSWORD` 写入受限权限的 `secrets/admin.env`。
`chatup zulip`	准备 `~/.chatarch/zulip` 下的 Zulip Docker Compose、bind-mount 数据目录和 secret files，并从 ChatEnv 读取 `ZULIP_ADMIN_USERNAME`、`ZULIP_ADMIN_EMAIL`/`ZULIP_ADMIN_MAIL`、`ZULIP_ADMIN_PASSWORD`。
`chatup mysql`	安装并准备 ChatData-compatible user-level MySQL runtime、实例目录、`my.cnf` 和可选 user-level systemd service。
`chatup twikoo`	从 `twikoojs/twikoo` Release assets 安装 Twikoo 二进制，并准备多实例目录、实例 env、实例级 `bin/twikoo` 和可选 user-level systemd service。
`chatup nginx`	准备 `~/.chatarch/nginx` 下的 user-level NGINX runtime/config/log/run/temp 布局，也可生成 reverse-proxy、HTTPS proxy、WebSocket proxy、static root 和 redirect 模板。
`chatup crs`	安装本地 Claude Relay Service，准备 Redis、配置、secret、admin SPA 和 smoke check。

工作区¶

命令	当前能力
`chatup workspace`	初始化 ChatArch 人类-AI 协作 workspace。

浏览器制品 backend 约定¶

ChatUp 不提供通用 browser group，也不再提供含义模糊的 chrome 命令：

chatup chrome-for-testing 管理真正可启动的 Google Chrome for Testing 浏览器，默认 home 为 ~/.chatarch/chrome-for-testing；
chatup chromedriver 管理 ChromeDriver WebDriver server，默认 home 为 ~/.chatarch/chromedriver；
chatup playwright 管理精确 Playwright package 与 Playwright Chromium，默认 home 为 ~/.chatarch/playwright；
Chrome for Testing 与 ChromeDriver 各自提供完整制品生命周期；Playwright 仅提供本任务实际使用的 install/path/doctor；
Chrome for Testing 中的 Testing 是官方制品名，不是用户 CLI 的 test 操作；
chromium 尚无已验证 provider，因此不注册命令；
安装使用官方 HTTPS manifest、可选 SHA-256、受限 ZIP 解压、installation.json 和原子目录替换；
remove 需要 --yes，gc 默认 dry-run，apply 同时需要 --yes；
不修改系统 Chrome、不创建 Profile/Cookie，也不管理账号或扩展。

chatup chrome-for-testing install --channel stable -I
chatup chrome-for-testing path 145.0.7632.6 -I
chatup chromedriver install --match-cft-version 145.0.7632.6 -I
chatup chromedriver doctor 145.0.7632.6 --output json -I
chatup playwright install 1.61.1 --output json -I
chatup playwright path 1.61.1 -I

完整子命令、ChatStyle 行为和 Python contract 见 CLI 树。

Gitea 命令约定¶

chatup gitea 对齐 ChatTea 的本地 Gitea 布局：

默认 release：latest，从 ChatArch/gitea 最新 GitHub Release 解析。
默认 binary：~/.chatarch/chattea/bin/gitea。
默认 work path：~/.chatarch/chattea/gitea。
可选 --init 会生成 custom/conf/app.ini，权限为 0600。
可选 --service 会写入 user-level systemd service。
Gitea 默认监听 127.0.0.1:3000，公网或本地域名入口交给 NGINX/public-entry 层。

常用形式：

chatup gitea --force
chatup gitea --init --service --base-url http://127.0.0.1:3000
chatup gitea --init --database-backend mysql --database-host ~/.chatarch/chatdata/instances/mysql/default/run/mysql.sock

Discourse / Zulip 命令约定¶

chatup discourse 和 chatup zulip 面向 ChatArch 社区服务安装，不在命令输出中打印管理员密码。管理员凭据统一来自 ChatEnv：

DISCOURSE_ADMIN_USERNAME
DISCOURSE_ADMIN_EMAIL
DISCOURSE_ADMIN_PASSWORD
ZULIP_ADMIN_USERNAME
ZULIP_ADMIN_EMAIL      # 或兼容 ZULIP_ADMIN_MAIL
ZULIP_ADMIN_PASSWORD

常用形式：

chatup discourse -e discourse-prod --hostname discourse.public.wzhecnu.cn
chatup discourse -e ./discourse-admin.env --clone --force
chatup zulip -e zulip-prod --external-host zulip.public.wzhecnu.cn --port 3095
chatup zulip -e ./zulip-admin.env --pull --start

默认行为：

chatup discourse 准备 ~/.chatarch/discourse、docker/containers/app.yml、shared/standalone 和 secrets/admin.env；--clone 才 clone/update discourse_docker。
chatup zulip 准备 ~/.chatarch/zulip/compose/compose.yaml、data/ bind mounts、secrets/ secret files 和 secrets/admin.env；--start 才执行 Docker Compose。
Zulip Compose 默认只绑定 127.0.0.1:3095:80，不抢主机 25/80/443；public/local 入口仍交给外层 NGINX/public-entry。
ZULIP_ADMIN_MAIL 只作为 ZULIP_ADMIN_EMAIL 的兼容别名；优先使用 ZULIP_ADMIN_EMAIL。

MySQL 命令约定¶

chatup mysql 复用 ChatData 第一版 no-sudo runtime 模型：

默认 MySQL 版本：8.4.6。
默认 home：~/.chatarch/chatdata。
默认实例：default。
默认端口：3307。
默认绑定：127.0.0.1。
默认会下载 runtime、初始化实例目录、生成 my.cnf 并写入 user-level systemd service，但不会启动服务。
--smoke 和 --database 需要 --start，避免在未启动服务时延迟失败。

常用形式：

chatup mysql
chatup mysql --start --smoke
chatup mysql --start --database gitea
chatup mysql --home ~/.chatarch/chatdata --name default --port 3307

Twikoo 命令约定¶

chatup twikoo 面向 Twikoo 评论服务的 no-Docker、多实例安装：

默认 Twikoo 版本：1.7.15。
默认 repo：twikoojs/twikoo。
默认 home：~/.chatarch/twikoo。
默认实例：chatblog。
默认端口：8892。
默认绑定：127.0.0.1。
默认会下载 release 二进制、初始化实例目录、生成 env/twikoo.env 并写入 user-level systemd service，但不会启动服务。
每个实例都通过 instances/<name>/bin/twikoo 启动，并让 bin/.env 指向该实例自己的 env/twikoo.env；不要让多个实例直接共享 runtime 目录旁边的 .env。
local/public 域名入口仍由 NGINX/public-entry 管理。

常用形式：

chatup twikoo --name chatblog --port 8892
chatup twikoo --name chatblog --port 8892 --start --smoke
chatup twikoo --home ~/.chatarch/twikoo --name another-blog --port 8893 --no-start

NGINX 命令约定¶

chatup nginx 默认准备 user-level NGINX，而不是修改系统 NGINX：

默认 home：~/.chatarch/nginx。
默认 binary：复制已有 nginx 到 ~/.chatarch/nginx/bin/nginx；如系统 PATH 中没有 nginx，可用 --binary PATH 指定已有二进制。
默认 config：~/.chatarch/nginx/conf/nginx.conf。
默认 logs/run/temp：~/.chatarch/nginx/logs、~/.chatarch/nginx/run、~/.chatarch/nginx/temp。
默认站点目录：~/.chatarch/nginx/conf/sites-available 和 ~/.chatarch/nginx/conf/sites-enabled。
默认监听：127.0.0.1:8080。
默认写入 user-level systemd service；不会写 /etc/nginx，不会重载系统服务。

chatup nginx
chatup nginx --home ~/.chatarch/nginx --binary /usr/sbin/nginx --port 8080
chatup nginx --start --smoke

chatup nginx 也保留模板生成模式：

chatup nginx --list
chatup nginx proxy-pass ./gitea-local.conf --set SERVER_NAME=gitea.local.example.invalid --set PROXY_PASS=http://127.0.0.1:3000
chatup nginx websocket-proxy ./ws.conf --set SERVER_NAME=ws.local.example.invalid --set PROXY_PASS=http://127.0.0.1:3000
chatup nginx static-root ./site.conf --set SERVER_NAME=site.local.example.invalid --set ROOT_DIR=/srv/site

CRS 命令约定¶

chatup crs 的默认目标是本地开发环境：

默认安装目录：~/.chatarch/crs/local
默认 CRS 端口：12392
默认 Redis 端口：6379
secret 文件：写入安装目录下的 .local-secrets.env，并使用受限权限。
默认会启动服务并运行 smoke check。

常用形式：

chatup crs --install-dir ~/.chatarch/crs/local --port 12392 --redis-port 6379
chatup crs --no-start --no-smoke