# capy-cli
The command-line interface for the Capy web framework.
The Capy CLI provides project scaffolding, generators, and development commands.
```sh
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.