CLI 与本地开发

日常命令#

在包含 curio.json 的目录或它的子目录执行工程命令。check、dev 和 pack 向上查找最近的 Manifest，到 Git 根目录停止；显式传入工程目录后，不再向上查找。

每层命令支持 --help。本地版本与文档不一致时，先查看已安装可执行文件的帮助信息。

初始化选项#

trove curio init my-tool --name "My Tool" --id dev.example.my-tool --template web --package-manager pnpm --yes --install
trove curio init static-tool --template static --yes

--template 接受 web、static。--package-manager 接受 npm、pnpm、yarn、bun，Web 默认 npm。--yes 接受推荐配置，--install 明确执行依赖安装，--no-install 跳过安装。

非交互初始化使用 --yes，或用 --no-input 并提供 --name 与 --template。问答取消时不创建文件。若创建后安装依赖失败，工程会保留，可重新执行安装。

端口与多开发会话#

生成的 Web 模板把 development.ui.url 设为 http://127.0.0.1:0，由 Host 分配端口，Vite 读取 TROVE_DEV_PORT：

server: {
  host: "127.0.0.1",
  port: Number(process.env.TROVE_DEV_PORT || 0),
  strictPort: true,
}

这是 Vite 配置片段。在不同终端开发不同 Curio，确保各工程 ID 不同；重复启动同一个 ID 会报告冲突。已有固定端口项目要自行分配不同端口。

trove curio dev --no-start-ui --ui-url http://127.0.0.1:5173
trove curio dev --backend managed
trove curio dev --backend external

--no-start-ui 连接已启动的 UI 服务。managed 使用配置的 Backend 启动命令；external 由你使用开发会话信息自行启动进程。参数覆盖只对这次运行生效，不写回 curio.json。

Ctrl-C 只停止本次 CLI 会话管理的资源，Host 与其他 Curio 继续运行，外部启动的 UI 服务不会被停止。external Backend 会收到 shutdown 并关闭会话；Host 不强制杀死其进程，但遵守协议的 Backend 会自行退出。终端连接丢失后，Host 也会回收对应会话。

查看失败原因#

trove curio check --json
trove --verbose curio dev

check 汇总 Manifest、engine、Contract、入口、工具链与依赖问题。配置了开发服务或构建命令时，不要求生产 UI 已存在。--verbose 展示完整安装、构建和启动日志。

需要同时查看 WebView 错误和进程输出时，打开 Trove 内的 Curio 调试控制台，详见测试与调试。

脚本与 CI#

trove curio check --json
trove curio pack --dry-run --json
trove curio pack --no-input --overwrite --json

--dry-run 只输出计划，不构建、不写包，也不能验证未来才生成的产物。只有确实打算替换输出文件时，才在自动化中使用 --overwrite。

check、pack、install 支持 --json：机器结果写 stdout，诊断写 stderr。可能发起问答的 init、dev、pack、install 和 contract generate 支持 --no-input。CI 与非 TTY 不发起交互问答，NO_COLOR 关闭终端颜色。

打包不需要 GUI；开发与安装会连接 Host。输出路径和安装选择见打包参数。