CLI & local development

Everyday commands#

Everyday actions use short commands. The terminal prompts for names, templates, and package candidates when needed.

Project commands search upward for the nearest curio.json, stopping at the Git root. Commands accepting a directory can target one explicitly; an explicit directory is not searched upward. Use trove --help or trove dev --help for advanced options.

Initialization options#

Run the following, keep the default name in the wizard, and choose a template:

trove new
cd my-curio
trove dev

Web uses TypeScript and Vite. Static HTML needs no Node runtime. Rust includes a Web UI, native Backend, contract export, and generated clients. Choose npm, pnpm, yarn, or bun; npm is the default.

The new project directory must not exist. Canceling the questions creates no files. If dependency installation fails after creation, the project remains for retry. Use trove adopt for an existing project; its wizard preserves source and scripts. Use trove kit when a manifest already exists.

dev and pack run bindings automatically. check is read-only and reports bindings.stale for missing or outdated output. Run trove generate before the first check of a new Rust project. See the Backend template.

Kit receipts live in vendor/.trove-kit.json. Locally edited kit files are preserved by default; use trove kit --overwrite to replace them while saving backups. SDK archive names include a content digest, so package managers can distinguish new builds with the same 0.0.1-alpha.1 version. Install dependencies after updating, then regenerate contracts and clients; do not hand-edit generated JSON or types.

Ports and simultaneous sessions#

The generated Web template asks Host to allocate a port with development.ui.url set to http://127.0.0.1:0. Vite reads TROVE_DEV_PORT:

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

This is a Vite config fragment. Start different Curios in separate terminals. Each needs its own ID; starting the same ID twice reports a conflict. Existing fixed-port projects must choose distinct ports.

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

--no-start-ui attaches to an already running UI server. managed uses the configured Backend command; external is for a process you launch using the development session information. Overrides affect only this invocation, not curio.json.

Ctrl-C stops this CLI session’s resources. Host and other Curios remain running. An externally started UI server is not stopped. An external Backend receives shutdown and its session is closed; Host does not forcibly kill its process, but a conforming Backend will exit. Losing the terminal connection also allows Host to reclaim the session.

Inspect failures#

trove check --json
trove --verbose dev

check reports manifest, engine, contract, entry, toolchain, and dependency issues. When a development server or build is configured, the production UI does not need to exist yet. --verbose exposes full installation, build, and launch output.

For WebView errors and process output together, open the Curio’s debug console inside Trove. See testing and debugging.

Scripts and CI#

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

--dry-run reports a plan without building or writing a package. It does not validate future build output. Use --overwrite only when your automation intends to replace an existing output file.

--json is supported by check, pack, and install: machine results go to stdout, diagnostics to stderr. --no-input is available on commands that can ask questions, including new, adopt, dev, pack, install, and generate. CI/non-TTY execution does not launch interactive prompts. NO_COLOR disables terminal colors.

Packaging does not require the GUI. Development and installation connect to Host. See packaging options for output paths and installation selection.