capy-cli 0.6.0

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

capy-cli

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.

cargo install capy-cli --version 0.6.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

 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.

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.