CLI 与本地开发

日常命令#

日常操作只需短命令。需要名称、模板或候选包时，终端会引导选择；不必记忆参数组合。

项目命令从当前目录向上查找最近的 curio.json，到 Git 根目录停止。支持目录参数的命令也可显式指定位置，显式目录不向上查找。用 trove --help 或 trove dev --help 查看高级选项。

初始化选项#

运行下列命令，在向导中保留默认名称并选择模板：

trove new
cd my-curio
trove dev

Web 使用 TypeScript 和 Vite；静态 HTML 无需 Node；Rust 模板包含 Web UI、原生 Backend、契约导出与生成客户端。可选择 npm、pnpm、yarn 或 bun，默认 npm。

新建工程要求目标目录不存在。取消问答不创建文件；创建完成后依赖安装失败，会保留工程供重试。已有工程应运行 trove adopt，向导保留源码和现有脚本。已有 Manifest 时用 trove kit 升级套件。

dev 和 pack 自动执行 bindings；check 保持只读，生成文件缺失或过期时报告 bindings.stale。新建 Rust 工程若先检查，请先运行 trove generate。详见 Backend 模板。

套件更新记录保存在 vendor/.trove-kit.json。已在本地修改的套件文件默认不会被覆盖；明确需要替换时使用 trove kit --overwrite，原内容会保存为备份。SDK 压缩包文件名包含内容摘要，因此同为 0.0.1-alpha.1 的新构建也能被包管理器正确识别。更新后安装依赖，并重新生成合约和客户端；不要手改生成的 JSON 或类型文件。

端口与多开发会话#

生成的 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 dev --no-start-ui --ui-url http://127.0.0.1:5173
trove dev --backend managed
trove 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 check --json
trove --verbose dev

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

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

脚本与 CI#

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

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

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

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