CLI & local development

Everyday commands#

Run project commands from the directory containing curio.json or a child directory. check, dev, and pack look upward to the nearest manifest, stopping at the Git root. An explicit project directory does not trigger an upward search.

Each level supports --help. Use the installed binary’s help when its version differs from these guides.

Initialization options#

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 accepts web or static. --package-manager accepts npm, pnpm, yarn, or bun; Web defaults to npm. --yes accepts recommended configuration; --install explicitly runs dependency installation. --no-install skips it.

In noninteractive mode, use --yes or supply --name and --template with --no-input. Canceling the interactive questions creates no files. If dependency installation fails after creation, the project remains available for another install attempt.

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 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 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 curio check --json
trove --verbose curio 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 curio check --json
trove curio pack --dry-run --json
trove curio 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 init, dev, pack, install, and contract 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.