---
title: All commands
description: 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](/docs#1-install-proa) walks through the complete setup:

```bash
cargo install proa-cli --locked
```

No GitHub credential or Cargo publishing token is required.

Then confirm the binary is on your path:

```bash
proa --help
```

Cargo installs both `proa` and `cargo-proa`. Select an exact published version
for reproducible installation:

```bash
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](/docs) if Cargo cannot download dependencies. When working from this repository, use:

```bash
cargo run -p proa-cli --bin proa -- <command>
```

## Update

Update the CLI using the tool that installed it:

```bash
proa update
```

Preview the latest stable version without changing files, or select an exact
stable release:

```bash
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`:

```bash
proa dev
```

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

```bash
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.json` and `proa.lock.json` to an existing project. |
| `proa config validate` | Check `proa.config.json` for unknown keys, empty commands, and invalid asset definitions. |
| `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 dev` | Build configured assets, run the app, restart on project changes, and reload open browser tabs. See [Live reload](/docs/cli/new-site#live-reload). |
| `proa build` | Run Proa checks, build configured assets, and compile the app for deployment. |
| `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.json` and `proa.lock.json`. The config drives lifecycle commands and records component registry aliases:

```json
{
  "$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:

```bash
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:

```bash
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](/docs/cli/new-site)
- [Generators](/docs/cli/generators)
- [Format, lint, and check](/docs/cli/format-lint-check)
- [Site inspection](/docs/cli/site)
- [Static chunk reports](/docs/cli/chunks)
- [CI usage](/docs/guides/ci)