capy-cli
Capy 0.9.0 adds 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.
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.
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 devopens 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 serveruns only the Rust application.capy buildinstalls missing frontend dependencies, builds the release backend, regenerates contracts, then runspnpm 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
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.
| Keys | Action |
|---|---|
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.
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.