pikasTech-unidesk/docs/reference/cli.md

UniDesk CLI Reference

UniDesk 的统一 CLI 入口是根目录 scripts/cli.ts，运行方式固定为 bun scripts/cli.ts <command>。CLI 默认输出 JSON，所有成功和失败路径都必须向 stdout 写出结构化对象，避免无输出造成状态不可观测。

Command Model

• help 输出命令索引，适合作为交互式入口。
• config show 读取并校验根目录 config.json，不从环境变量、默认值或隐藏文件静默补配置。
• check 执行配置校验、文件存在性检查、scripts/ TypeScript 检查、src/components/ TypeScript 检查和 Docker Compose 配置检查。
• server start 创建异步 job，在后台执行 Docker 构建和启动；命令本身只负责返回 job id、日志路径和启动命令。
• server stop 创建异步 job，在后台停止固定 Compose project 中的全部 UniDesk 服务。
• server status 查询公开端口、内部端口、Compose 容器、core/frontend/provider/database 健康检查和访问 URL。
• server logs 返回 logs/ 文件日志和 Docker 容器日志的尾部，默认限制输出大小，避免日志爆炸。
• job list 与 job status 查询 .state/jobs/ 文件系统状态，是异步命令的可观测入口。
• debug health 与 debug dispatch 走真实内部 core、WebSocket、数据库、provider、系统指标和 Docker 状态流程，只用于开发调试，不写入 TEST.md 的正式验收步骤。
• e2e run 使用 publicHost 派生的公开 frontend/provider ingress URL，并通过 Docker 内网验证 core API、PostgreSQL、provider self-connection、系统指标曲线、Docker 状态快照、provider.upgrade 预检和 Playwright 前端页面，是交付前的自动化 E2E 门禁。

Async Job State

长时操作采用 Fire-and-Forget 模式：CLI 创建 .state/jobs/{jobId}.json，后台进程执行真实命令，并将 stdout、stderr 分别写入 .state/jobs/{jobId}.stdout.log 与 .state/jobs/{jobId}.stderr.log。调用者通过 bun scripts/cli.ts job status <jobId> 查询进度和尾部输出。

Output Contract

每条命令的最外层 JSON 包含 ok、command 和 data 或 error。失败时 CLI 设置非零退出码，但仍然输出 JSON 错误对象；错误对象应包含 name、message 和可用的 stack。

Debug Contract

debug 子命令必须复用真实模块与真实端点，禁止维护平行实现。debug health 会摘要展示 /api/nodes/system-status 和 /api/nodes/docker-status，避免输出完整快照造成信息爆炸。debug dispatch 会在 backend-core 容器内调用内部 /api/dispatch，core 再通过 WebSocket 将 docker.ps、provider.upgrade 或 echo 任务下发给 provider gateway，因此它可以验证核心调度闭环，同时不需要公开 core REST API。