Docs
All commands
The main proa subcommands, and where each one is explained.
The Proa CLI is developer tooling for Proa templates and opinionated Proa sites. It scaffolds projects, generates typed Rust modules, formats template macro bodies, runs Proa-specific lints, inspects site structure, and reports how HTML and XML macro bodies consolidate into static byte runs.
Install
Install the latest stable CLI from crates.io. Install Proa walks through the complete setup:
cargo install proa-cli --locked
No GitHub credential or Cargo publishing token is required.
Then confirm the binary is on your path:
proa --help
Cargo installs both proa and cargo-proa. Select an exact published version
for reproducible installation:
cargo install proa-cli --version '=0.2.0' --locked --force
Generated project builds resolve Proa crates from crates.io and use Cargo.lock for reproducibility. Follow Installation if Cargo cannot download dependencies. When working from this repository, use:
cargo run -p proa-cli --bin proa -- <command>
Update
Update the CLI using the tool that installed it:
proa update
Preview the latest stable version without changing files, or select an exact stable release:
proa update --check
proa update --version 0.1.3
proa update --build-from-source
cargo proa update works too. Proa identifies the installation before updating:
- Standalone installer: downloads and runs the official installer. It verifies SHA256, checks both binaries, and switches one pointer to a complete versioned bundle. Existing processes keep using the previous bundle.
- Cargo: lets Cargo update its own installation and records. On Unix, Proa hands the process over to Cargo. On Windows, it prints the exact PowerShell command to run after Proa exits, then exits without installing. This avoids locked executables.
- Unknown or debug installation: refuses to overwrite it and provides
manual upgrade guidance.
--checkremains available in debug builds.
An explicit --version can reinstall the same release or downgrade; the
default command never downgrades to an older stable release. Prerelease and
main snapshot versions are rejected; use the installer to select a snapshot.
The updater uses Proa's CLI release metadata and verifies SHA256 checksums before installing prebuilt binaries. If no archive exists for a standalone installation, it builds the exact selected release from crates.io in private staging. This requires Cargo and can take several minutes. Both binaries must report the requested version before the bundle becomes current.
Checksum verification trusts Proa's HTTPS release channel; it does not yet verify an independent publisher signature.
Standalone executable staging stays on the installation filesystem to support
hosts where the system temporary directory does not allow execution. Update
logs stay in the installation root after staging is cleaned up. Set PROA_LOG
to choose a log path, or PROA_LOG=off to disable logging.
Use --build-from-source when a prebuilt binary cannot run on your system,
such as a Linux distribution with an older glibc. This bypasses archive
downloads and builds the selected release with your local toolchain.
Older CLIs without update need one upgrade through the installer or
cargo install proa-cli --locked before this command is available.
New standalone installations keep releases in a sibling directory named
<bin-directory>.proa. On Unix, the two public commands are symlinks through
its current pointer. On Windows, a dedicated bin directory is a junction
through current; shared directories containing other programs are refused.
Previous bundles remain available for processes that are still running.
Older releases without the bundle publisher can still be installed in their
legacy layout; rerun the installer to migrate once a capable release exists.
Invocation
The installed binary is proa:
proa run dev
proa dev enters the built-in watcher directly.
The package also ships cargo-proa, so Cargo can invoke the same command as a subcommand:
cargo proa fmt --check --verify src
Commands
| Command | Purpose |
|---|---|
proa update | Update both CLI binaries; use --check to preview or --version to select a release. |
proa init | Add proa.config.rs and proa.lock.json to an existing project. |
proa config validate | Compile proa.config.rs and validate the settings. |
proa config show | Print the effective configuration with defaults filled in. |
proa new site | Create an opinionated Proa site, including optional deployment presets such as --deploy coolify. |
proa run dev | Run the configured development script. Defaults to proa dev. |
proa run build | Run the configured build script. Defaults to proa build. |
proa dev | Build configured assets, run the app, restart on project changes, and reload open browser tabs. See Live reload. |
proa build | Run Proa checks, build configured assets, and compile the app for deployment. |
proa start | Start the release executable exported by proa build with its published public catalog. Pass --bin <path> and --public-assets <dir> to start another export. |
proa run | Compile and run one exact Proa binary through the linked RSJS pipeline. |
proa test | Compile and execute one exact test target through the linked RSJS pipeline. |
proa generate component | Generate reusable render components under src/components. |
proa generate layout | Generate shared page layouts under src/layouts. |
proa generate data | Generate typed data modules under src/static_data. |
proa registry list | Print configured component registry aliases. |
proa ui add | Install a source component or block from the Proa UI registries. |
proa rsjs explain | Explain why an rsjs impl emitted browser JS or stayed server-only. |
proa rsjs crossings | Print redacted public data crossing records from rsjs strategy sidecars. |
proa site check | Validate the expected site structure. |
proa site routes | Print page routes discovered from src/pages. |
proa site doctor | Alias of site check with the same diagnostics. |
proa fmt | Format HTML, XML, and raw md! / md_sync! template bodies. |
proa lint | Run accessibility, format, composition, content coverage, and render-path lints. |
proa check | Run verified format and lint checks and, for a whole project, the linked RSJS Cargo check. |
proa chunks | Inspect static runs, dynamic slots, and consolidation size estimates. |
proa font sync | Vendor and lock every font declared in code, or verify with --offline. |
proa font list | List fonts recorded in proa-fonts.lock. |
proa completions | Generate shell completions for the proa binary. |
Project Config
Generated sites include proa.config.rs and proa.lock.json. Return a
Config struct literal wrapped in Ok to set lifecycle options and component
registry aliases. Use ..Config::default() for other settings. These are the
default scripts used by proa run dev and proa run build.
use proa::config::{Config, Result, ScriptsConfig};
pub async fn config() -> Result<Config> {
Ok(Config {
scripts: ScriptsConfig {
dev: "proa dev",
build: "proa build",
..Default::default()
},
..Config::default()
})
}
proa.lock.json records components installed by proa ui add: version, registry, installed files, source hashes, and dependencies.
Use the command override when a project needs a custom server binary:
proa dev -- cargo run --bin my_app
proa build -- cargo build --release --bin my_app
Output Modes
Several commands support machine-readable output:
| Command | Machine Output |
|---|---|
init, registry list | --json |
config validate, ui add | --json |
rsjs explain, rsjs crossings, font list | --json |
new site | --dry-run --json |
generate * | --dry-run json |
site check, site routes | --json |
lint | --json or --github |
chunks | --json |
File Selection
fmt, lint, check, and chunks can operate on explicit paths or Git-selected paths:
proa lint src/pages/home.rs
proa lint --changed --base origin/main
proa check --staged
proa chunks --changed --json
Do not combine explicit paths with --changed, --staged, or --base.