Server Workspace CLI
server workspace CLI 位于server/cli。在仓库内开发时，通常通过 workspace 脚本调用：
workflow-workspace 命令。仓库内脚本会先构建项目，再运行 server/cli。它用于连接 Workflow Server，管理远程 workflow 包和版本。
参数规则
workspace CLI 会从命令后的所有参数中识别全局选项，未识别的参数保留为命令位置参数或 workflow args。当前不会剥离-- 分隔符，因此运行远程 workflow 时直接写业务参数即可。
| 规则 | 说明 |
|---|---|
| 全局选项 | --server、--token、--target、--release-log、--path、--file、--output、--create 会被 CLI 解析。 |
| workflow args | run 的 <workflow> 之后，未被识别为全局选项的参数会发送到 server run API。 |
| debug args | debug-node 的 <workflow> 和 <node> 之后，未被识别为全局选项的参数会发送到 debug node API。 |
--version | 已废弃。版本号由 server 发布流程生成。 |
全局选项
| 选项 | 说明 |
|---|---|
--server <url> | Workflow Server 地址。默认读取 WORKFLOW_SERVER_URL，再读保存的 CLI 登录态，最后回退到开发常用的 http://localhost:7125。发布/部署态建议显式传 http://localhost:7130 或正式域名。 |
--token <token> | 可选的显式 Bearer 覆盖值。默认读取 WORKFLOW_SERVER_ADMIN_KEY，再读保存的 CLI 登录态 API Key。 |
--target <target> | 远程运行、调试或下载目标。常用值为 draft、latest 或具体版本号。 |
--release-log <text> | 发布日志。用于 upload 后自动 publish，或用于 publish。 |
--path <path> | 本地 workflow 目录或下载目标目录。 |
--file <archive> | 已存在的 .tgz workflow 包。 |
--output <file.tgz> | pack 生成的压缩包路径。 |
--create | upload 时如果本地 package.json.id 还没有绑定 server UUID，则先调用 POST /api/workflows 创建远程项目并把返回 UUID 写回本地 package。 |
配置和登录态
| 来源 | 说明 |
|---|---|
server/cli/.env | CLI 工作目录下的配置文件。 |
仓库根目录 .env | 共享配置文件。 |
| CLI 登录态文件 | login 会写入 workflow-auth.json，后续命令可复用。 |
| 环境变量 | 显式环境变量优先级高于 .env。 |
.env 示例：
配置优先级
| 配置项 | 优先级 |
|---|---|
| server URL | --server > WORKFLOW_SERVER_URL > CLI 登录态 > http://localhost:7125 |
| token | --token > WORKFLOW_SERVER_ADMIN_KEY > CLI 登录态 |
| repo root | WORKFLOW_REPO_ROOT > 从当前目录或 CLI 文件位置向上查找包含 pnpm-workspace.yaml 的仓库根目录 |
| pack 暂存目录 | WORKFLOW_WORKSPACE_PACKS_DIR > <repo root>/workspace/.packs |
| CLI 登录态目录 | WORKFLOW_CLI_AUTH_DIR > 系统默认应用配置目录 |
workflow-auth.json。macOS 默认目录是 ~/Library/Application Support/workflow-code，Windows 默认使用 %APPDATA%/workflow-code，Linux 默认使用 $XDG_CONFIG_HOME/workflow-code 或 ~/.config/workflow-code。
从桌面 App 发行包触发 Publish 时，App 会为 workspace CLI 设置 WORKFLOW_WORKSPACE_PACKS_DIR 到 App 用户数据目录下的可写位置；同时 upload --path <workflow-dir> 会按 <workflow-dir> 的父目录查找 ../sibling-workflow 这类本地 workflow 依赖，避免发行包误把 app.asar 当成仓库根目录。
命令列表
输出和退出码
| 情况 | 行为 |
|---|---|
server 返回 errCode: 0 | 输出 JSON，退出码保持成功。 |
server 返回非零 errCode | 输出 JSON，并设置退出码为 1。 |
| 参数缺失或本地命令失败 | 输出错误信息，退出码为 1。 |
完整发布示例
workflow-workspace。仓库内开发默认仍以 7125 为主；只有发布/部署态示例才切到 7130+。例如：
package.json.id UUID 为远程项目标识。<workflow> 位置参数仍可继续写本地目录名或 workflow 名称，但 CLI 会优先读取该目录内 package.json.id；只有当你直接把 <workflow> 传成 UUID 时，CLI 才会跳过本地 package 读取。若本地 package 缺失 UUID、不是 UUID，或还没有在 server 端创建项目，upload / run / publish / debug-node 都会直接失败，并给出 workspace upload <workflow> --create 的绑定提示，不再从目录名推导远程项目 ID。
当 workflow 源码通过 ../<sibling-workflow>/... 引用其它 workspace workflow 时，pack 和 upload 也会把这些兄弟 workflow 源码一起打进归档里的 workspace/workflow/* 结构，确保 server 端构建 draft/runtime 包时能解析本地依赖，不需要手工拼包。
Codex 手动上传示例
workspace/workflow/codex 可先打包为 .tgz，再通过 upload --file 上传已有包，适合需要人工确认归档内容或复用包文件的场景：