capy-cli 0.2.0

The command-line interface for the Capy web framework.
Documentation

capy-cli

The command-line interface for the Capy web framework.

The Capy CLI provides project scaffolding, generators, and development commands.

cargo install capy-cli
capy new blog
cd blog
capy dev

Requires Rust and rustfmt. Full-stack projects also need Node.js 22.12+ (or 20.19+) and pnpm. capy new NAME defaults to Vite + React + TypeScript; use --api or --frontend none for a backend-only application, or --frontend react explicitly.

  • capy dev compiles and runs Rust alongside Vite. React HMR is enabled; restart the command after changing Rust code. API-only projects run Rust alone.
  • capy serve runs only the Rust application.
  • capy build installs missing frontend dependencies, runs pnpm run build (TypeScript + Vite), then cargo build --release. API-only builds skip pnpm.

capy.toml selects [frontend] driver = "react" or "none". Legacy projects without metadata remain backend-only. The frontend lives in frontend/. The backend address is resolved from the application settings and passed to Vite's /api proxy; APP_PORT=8001 capy dev updates both sides. Vite defaults to port 5173; use CAPY_FRONTEND_PORT=5174 capy dev when that port is occupied.

For deployment, ship frontend/dist/ with the release binary and configuration, and run APP_ENVIRONMENT=production ./target/release/NAME from the app root. The backend serves the SPA and static assets without a Node server. Missing builds fail clearly in production. Commit the generated pnpm lockfile; installs honor it.

Generators hold a cross-process project lock while checking names and updating registries. A successful capy make:* creates every required file and registration; a failed command makes a best effort to restore the previous valid state. Registries are replaced atomically, and a failed replacement removes the new source file. Keep .capy-generator.lock in place; the lock file is intentionally persistent and ignored by Git. Do not edit registries concurrently with a generator. Locks require a filesystem supporting advisory locks and atomic rename. Power loss or SIGKILL between source creation and registry replacement can leave an unregistered source; inspect and remove or register that source before retrying.

Names normalize to snake_case modules and PascalCase types. Model exports also reserve <Type>Model. Collisions are rejected before source changes. Registry imports must be explicit; glob imports and binding-generating macros in ordinary registries prevent reliable collision checks. Migration registry markers must each occur exactly once.

On Unix, Capy owns process groups, forwards SIGINT/SIGTERM/SIGHUP, allows five seconds to shut down, then kills remaining descendants and reaps direct children. An error in either development server stops its sibling. Build and serve exit statuses are preserved (128 + signal for signal deaths). Windows job objects own process trees and terminate them on Ctrl-C. Unix SIGKILL cannot run cleanup.

MIT licensed. See LICENSE. This is an initial developer preview, not a production-readiness claim.