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. --check remains 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 dev

The package also ships cargo-proa, so Cargo can invoke the same command as a subcommand:

cargo proa fmt --check --verify src

Commands

Project Config

Generated sites include proa.config.json and proa.lock.json. The config drives lifecycle commands and records component registry aliases:

{
  "$schema": "https://proa.so/schema/proa.config.json",
  "paths": {
    "components": "src/components",
    "assets": "public/proa"
  },
  "registries": {
    "@proa": "https://ui.proa.so/r/{name}.json",
    "@proa-pro": "https://console.proa.so/r/{name}.json"
  },
  "dev": {
    "command": ["cargo", "run"],
    "host": "127.0.0.1",
    "port": 3000,
    "watch": ["src", "styles", "Cargo.toml", "build.rs", "proa.config.json"]
  },
  "build": {
    "command": ["cargo", "build", "--release"],
    "assets": [
      {
        "kind": "tailwind",
        "input": "styles/input.css",
        "output": "public/styles.css"
      }
    ]
  }
}

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:

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.

Reference Pages

• Create a site
• Generators
• Format, lint, and check
• Site inspection
• Static chunk reports
• CI usage