# capy-cli
Capy 0.10.0 adds resource references, nested routes, access profiles, additive
evolution commands, named tasks, and scheduler commands. Capy 0.9 added
field-aware `make:resource ... --frontend`, six auth pages through
`make:auth --frontend`, explicit `db:seed`, `db:migrate` aliases, strict contracts,
and a shared application factory. Start with
[Build a Complete Feature](https://github.com/capy-rs/capy/blob/main/docs/complete-feature.md).
Capy 0.6.0 adds `capy make:auth` for optional cookie sessions, Argon2id passwords,
CSRF, explicit policies and password reset, plus `capy auth:prune`.
The auth API is experimental. Production requires HTTPS and an application-owned
reset-delivery adapter; the generated local inbox is development-only.
Capy 0.5.0 adds `capy openapi`, deterministic `capy types`, CI drift checks via
`capy types --check`, and automatic contract regeneration after successful Rust
builds in `capy dev`. Public DTOs and explicit route metadata are the source of
truth; generated TypeScript describes JSON at compile time, without runtime
response validation.
Production Foundation includes `capy doctor` (read-only environment and
bounded database diagnosis) and `capy check` (offline configuration, production
asset and migration-registration validation). The latter compiles the application
offline, requiring cached dependencies, then executes its `check` command without
starting HTTP or opening the database. Generated frontend projects include a pnpm
lockfile and a typed ApiError helper with empty-response support.
The command-line interface for the Capy web framework.
The Capy CLI provides project scaffolding, generators, and development commands.
```sh
cargo install capy-cli --version 0.10.0 --locked
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` opens a native terminal dashboard for Rust, application logs, and Vite.
React HMR is enabled; Rust source changes automatically rebuild and restart the backend.
API-only projects show only server and logs.
- `capy serve` runs only the Rust application.
- `capy build` installs missing frontend dependencies, builds the release backend,
regenerates contracts, then runs `pnpm run build` (TypeScript + Vite). 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.
## Development dashboard
```text
capy dev • example-app ~/projects/example-app
┌─ contexts ──────────┬─ server · cargo build → serve ───────────────┐
│ 1 ● server │ Compiling example-app │
│ running · 28 │ Server running on http://127.0.0.1:8000 │
│ 2 ● logs │ GET /api/health 200 0.42ms │
│ running · 14 │ request_id="example" │
│ 3 ● frontend │ │
│ running · 8 │ │
└─────────────────────┴─────────────────────────────────────────────┘
http://127.0.0.1:8000 following · 1–28 / 28
↑↓ scroll · 1–9 tabs · r restart · c clear · / search · s stream · q quit
```
`server` contains Cargo compilation, server lifecycle, ordinary stdout/stderr,
and Capy's HTTP request diagnostics. `logs` contains application and dependency
`tracing` events, with the existing `RUST_LOG` filter. It is a source attached to
the backend, so restart is disabled there. `frontend` contains pnpm installation,
Vite readiness, diagnostics, and HMR updates. Frontend HMR and the `/api` proxy
keep their existing configuration.
Projects created with `--api` or `--frontend none`, and legacy projects without
`capy.toml`, show **server + logs only** and require no frontend tools. Backend
restart recompiles the same Cargo binary selected by `package.default-run`
(or the only binary). Rust files and `Cargo.toml` under the application root are
watched automatically in both dashboard and inline modes. Adding, editing,
renaming, or deleting sources triggers a debounced rebuild, including files made
by `capy make:*`. Compile errors leave the session open and retry on the next
source change; Vite keeps running during backend rebuilds. Press `1`, then `r`
for a manual rebuild. Restarting the frontend stops its whole process tree before
launching Vite again.
The watcher polls source contents every 250 ms and groups saves until they have
settled for 300 ms. It skips hidden directories, `target/`, `frontend/`, and
`generated/`, `node_modules/`, and ignores non-source files such as database files, logs, and
`Cargo.lock`. It does not follow directory symlinks or watch dependencies outside
the application root. `capy serve` compiles and runs once; use `capy dev` for
automatic rebuilds. Changes to `config/api.toml` also trigger a rebuild.
| `1`–`9` | Select a context; also leave stream mode |
| `↑` / `↓`, `k` / `j` | Scroll one line |
| `PageUp` / `PageDown` | Scroll one page |
| `←` / `→` | Scroll long lines horizontally |
| `g` / `G`, `Home` / `End` | Oldest output / latest output |
| `r` | Recompile/restart server, or restart frontend |
| `c` | Clear the current context or stream buffer |
| `/`, type, `Enter` | Case-insensitive search in the current buffer |
| `n` / `N` | Next / previous match, wrapping at the ends |
| `Esc` | Cancel search input |
| `s` / `t` | Aggregated stream / individual contexts |
| `q`, `Ctrl+C` | Stop all managed processes and exit |
Shortcuts are disabled while typing a search; Ctrl+C always quits. Search terms,
scroll positions, and output are independent per context and for the stream.
Clear a search by submitting an empty query. The stream orders lines as they
are received, prefixes each with local time and source, and includes lifecycle
messages. Concurrent stdout/stderr pipes have no stronger ordering guarantee.
Every buffer retains the latest 5,000 lines. Lines exceeding 16 KiB are truncated
and marked; pending channels and ANSI control payloads are bounded as well.
Scrolling up pauses following even while new output arrives. Scroll to the bottom
or press `G` to resume. Long lines are clipped to the viewport; use `←`/`→` to read the rest. Supported
ANSI colors and styles are retained; cursor movement, clipboard commands, and
other subprocess terminal controls are discarded. Small terminals show a compact
view or a resize message.
```sh
capy dev --inline # prefixed plain output, suitable for log files
capy dev --tui # dashboard when a usable terminal is attached, including CI
capy dev --stream # start the dashboard in aggregated stream mode
capy dev > output.log 2>&1
```
Automatic TUI mode requires both stdin and stdout to be terminals. CI,
`TERM=dumb`, redirected output, and non-interactive IDE/Docker runners use plain
`[server]`, `[logs]`, and `[frontend]` output without escape sequences. `--tui`
and `--stream` can override CI detection but cannot make a redirected or dumb
terminal interactive. `--inline` conflicts with both flags; `--tui --stream` is
valid. Subprocess stdin belongs to Capy; interact with the dashboard, not pnpm
prompts or Vite's own shortcuts.
Log separation uses a development-only, versioned JSON prefix on the backend's
stderr; no files or logging service are needed. Production logging is unchanged.
Applications that install their own tracing subscriber, or use an older Capy
runtime without this hook, keep their output under server. Framework request
logs stay under server. Restart the entire command to reload CLI-resolved ports
or frontend configuration.
On quit or a termination signal, input stops and children receive a shutdown
request. Unix process groups get SIGTERM and a five-second grace period, then
survivors are killed and direct children reaped. Windows uses the existing job
object strategy, attempts non-forced `taskkill /T`, then terminates the job;
console applications may need forced termination. Ctrl+C and Windows console
close/shutdown events are handled. Terminal guards restore raw mode, the alternate
screen, and cursor after exits, errors, and unwinding panics. Uncatchable process
termination cannot run those guards. An unexpected server exit stops the session,
preserves a failing status, and prints the failed context's last diagnostics after
restoring the shell.
Those lifecycle scenarios have been executed on Linux/macOS. Windows CI now
contains compilation, real pnpm.cmd discovery and a job-object descendant cleanup
test, but no Windows runner result was obtained for this milestone locally.
Windows reload and interactive terminal restoration remain unverified; do not
treat the Unix suites as evidence for them.
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.
Build and `serve` keep their existing process ownership and exit-status behavior
(128 + signal for Unix signal deaths).
MIT licensed. See LICENSE. This is an initial developer preview, not a production-readiness claim.