DocsWorking with Rahti
Commands
Cargo commands, markup formatting, scaffolding, the agent restart loop, generators, static builds, upgrades, and environment settings for a Rahti project.
Install
cargo-rahti is the only piece a Rahti project needs installed globally — everything else arrives as a normal Cargo dependency of the project it creates. cargo-watch is optional, and is what the cargo dev alias below hands the restart to.
cargo install cargo-rahti # the scaffolder — once per machine
cargo install cargo-watch # what `cargo dev` hands the restart to
# Optional, and separate installs on release lines of their own.
cargo install cargo-rahti-ui # shadcn/ui components
cargo install cargo-rahti-icons # icon components
cargo install cargo-rahti-native # Windows and Android packaging
cargo install rahti-mcp # local stdio; --mcp also enables secured HTTPThe UI, icons, native packaging, and MCP tools are optional packages — icons and native packaging. Installing neither is the normal case, and a project that has not asked for them compiles, downloads and depends on no part of either. Official packages is the whole list, and which line each crate is on.
Everyday commands
These are the ones you type inside a project. The dev alias rebuilds and restarts the server, and cargo rahti fmt formats authored markup. The build step runs from build.rs, so an ordinary Cargo command regenerates the router on its way to compiling.
cargo run # regenerate routes and serve
cargo dev # alias: cargo watch -x run — cargo run on every edit
cargo check # verify without running
cargo test # this application's tests
cargo fmt # ordinary Rust
cargo rahti fmt # authored html! markup
cargo rahti fmt --check # verify markup without writing
cargo rahti build --static # export pages and public assets to dist/
cargo rahti upgrade # refresh unedited scaffold files
cargo rahti restart # apply an edit to the running server
cargo rahti status # is the server running the current source?| Command | What it does |
|---|---|
| cargo run | Regenerates src/routes.rs, the component and model wiring, and .rahti/manifest.json; compiles CSS according to the configured engine; then serves. |
| cargo dev | The scaffold's alias in .cargo/config.toml. Re-runs cargo run on every change under src/ or to rahti.config.json, and the open tab reloads itself when the new server comes up. Needs cargo-watch. |
| cargo check | The same generation and validation, without producing a binary. A route, RPC or socket-name conflict is a build error, so this is what catches one fastest. |
| cargo test | The application's own tests. See Testing for driving the generated router in-process. |
| cargo fmt | Formats ordinary Rust; custom html! markup uses the Rahti formatter. |
| cargo rahti fmt | Formats authored html! nesting and long attribute lists. Preserves expressions, quoted values, script/style raw strings, comments, and attribute order. |
| cargo rahti fmt --check | Reports formatting differences without writing. Exits unsuccessfully when a file would change. |
| cargo rahti restart | Applies an edit to the running server. See below. |
| cargo rahti status | Says whether the server is running the current source, which routes loaded with what browser errors, and how jobs are doing. |
| cargo rahti stop | Stops the server the way Ctrl+C does. |
| cargo rahti generate job | Adds a typed #[job]. See below. |
| cargo rahti build --static | Renders exportable pages through the real router and copies public assets to dist/. See Static generation. |
| cargo build --release | A production binary. Development reload is off, and a busy port is an error rather than something to walk past. |
The scaffolder
cargo rahti creates, statically builds, and upgrades projects, applies edits to a running server, generates jobs, and formats authored markup. Every feature flag adds something, and leaving it out is how you say no — one spelling per answer, so there are no opposing flags to reconcile. An interactive run asks about whatever you did not name, defaulting to no; a run with nowhere to ask — a pipe, a CI job — takes the flags at their word.
cargo rahti new <name> [--tailwind] [--db [backend]] [--ws] [--mcp] [--local <path>]
cargo rahti build --static [--out <directory>]
cargo rahti fmt [--check] [path...]
cargo rahti upgrade [--dry-run] [--force [path...]] [--db [backend]] [--ws] [--mcp]
cargo rahti restart [--timeout <seconds>]
cargo rahti stop [--timeout <seconds>]
cargo rahti status [--json]
cargo rahti generate job <name> [--params name:Type,...]
cargo rahti generate job-store
cargo rahti help
cargo rahti --versioncargo rahti fmt
cargo fmt
cargo rahti fmt
cargo rahti fmt --check
# Select files or directories explicitly.
cargo rahti fmt src/app/page.rs src/componentsRun cargo fmt for ordinary Rust, then cargo rahti fmt for markup. The formatter uses four-space nesting, expands nested elements, and wraps long attribute lists at a soft limit of 100 bytes including indentation. Short text-only elements stay inline. A quoted string or expression can exceed that width: its contents are never split.
Client and server expressions, attribute order, and script/style raw strings stay as authored. Existing multiline expressions remain multiline; formatting does not add line breaks inside them. Put visible spaces inside quoted text, and move complicated browser logic into a named script function yourself.
Without paths, the command visits src/ and a configured app.dir outside it. Explicit paths select Rust files or directories recursively. Generated routing and component/model/migration module files, symlinks, and build directories are excluded. Blocks containing bare unquoted text stay untouched because moving their whitespace can change rendered output. Elements with comments inside the opening tag also stay as authored, and so does a block inside a macro_rules! template that writes a metavariable — <$el>, title=$label — in its markup, which is only complete once the macro expands.
--check writes nothing and is suitable for CI. Invalid Rust tokenization or malformed supported markup is reported before any files are written. A second formatting run produces no changes. See the formatted markup example.
cargo rahti build --static
# Render pages through the real application router and copy public assets.
cargo rahti build --static
# Write into another exporter-owned directory instead of dist/.
cargo rahti build --static --out siteThe exporter performs normal application startup without binding a listener, then renders the generated router. Non-dynamic pages are automatic; dynamic pages list exact URLs in static_paths(). The default output is dist/, and --out selects another safe, exporter-owned directory.
cargo rahti restart, status and stop
cargo dev suits a person watching a browser. A coding agent works in batches and has to know when its edit is live, so it owns the step. These commands are that step, and they work the same for a person.
# Build beside the running server, stop it gracefully, start detached,
# wait until it answers, and say how long each part took.
cargo rahti restart
# Running? Current? Which routes loaded, with what errors? How are jobs?
# Exits non-zero unless the server is up and running the current source.
cargo rahti status
cargo rahti status --json
# Stop the way Ctrl+C does.
cargo rahti stoprestart builds the project while the old server stays up, so a compile error costs nothing and is reported as still running the old code. It then stops the server gracefully, starts a detached server with its output in .rahti/dev-server.log, waits for that boot to answer, and prints the URL. The server is down only between that stop and that boot. --timeout bounds each wait and defaults to 60 seconds.
The server runs a copy of the built binary under .rahti/dev-server/, never the file in target/. Windows refuses to replace a running executable, and the copy is what lets this build, a plain cargo build, or cargo test run beside the server. A server started another way — cargo run or cargo dev — holds the file in target/; for that one restart the source is type-checked first and the server is stopped before the build.
Where the time went
Restart ends with one line that names each part of the wait.
[rahti] Building while the running server stays up.
[rahti] Stopped the server at http://localhost:3000.
[rahti] Ready at http://localhost:3000 (pid 4812, boot 18e6921233c41a04-12b58, output in .rahti/dev-server.log)
[rahti] Took 6.1s: compile 1.9s, link 2.4s, stop 0.3s, boot 1.5s.| Part | What it measures |
|---|---|
| compile | Everything up to the application's library: the code an edit changes. |
| link | From the library to the executable. |
| stop | The old server's graceful shutdown. |
| boot | Copying the binary and waiting for the new server to answer. |
| check | Only when the running server was not started by restart: the type check that runs before it is stopped. |
Read it before changing anything to make the loop faster: it names the part that is slow.
The development build profile
A scaffolded Cargo.toml ends with the profile that keeps the link short.
[profile.dev]
debug = "line-tables-only"
[profile.dev.package."*"]
debug = false
[profile.dev.build-override]
opt-level = 3Backtraces keep your crate's file and line numbers. Dependencies carry no debug info, which is most of what a linker otherwise copies into every build and most of what fills target/. Build scripts and proc macros run on every build, so they are optimized. Cargo.toml is your own file, so cargo rahti upgrade does not add these tables to a project that lacks them: paste them in, and expect one full rebuild. Remove debug = false for the session in which a debugger has to step into a dependency.
status compares the running server with the files on disk and names any source edited since it booted. It lists the routes that really loaded under this boot, so a route it does not list was never opened and proves nothing. It exits non-zero unless the server is up and current, and the same report is available as MCP server_status.
A dev server writes .rahti/dev-server.json with its address, boot id, and a token generated for that process. The status and shutdown routes need that token and exist only in development, and no output carries it.
cargo rahti generate
# A typed job in src/jobs.rs, with the module declared and workers started.
cargo rahti generate job send_receipt --params order_id:i64,note:Option<String>
# Keep jobs in the application's database. Needs a project with a database.
cargo rahti generate job-storegenerate job adds a #[job] to src/jobs.rs, declares the module, and makes sure workers start. A parameter with no type is a String. generate job-store writes a SeaORM adapter, an entity and a migration into the application. Both refuse rather than overwrite. See Background jobs.
cargo rahti new
# A plain project. An interactive run asks about the rest, defaulting to no.
cargo rahti new my-app
# Tailwind, a SQLite database, WebSockets and the MCP configuration —
# nothing left to answer.
cargo rahti new my-app --tailwind --db sqlite --ws --mcp
# Depend on a Rahti checkout by path. For working on the framework itself.
cargo rahti new my-app --local ../rahti| Flag | What it adds |
|---|---|
| --tailwind | Compiles src/app/globals.css with the pinned standalone Tailwind CLI. Without it, plain CSS. |
| --db [backend] | SeaORM wiring for sqlite, postgres or mysql — bare --db is SQLite, the one that needs no server. Writes src/db.rs, src/models/ and src/migrations/, adds SeaORM to Cargo.toml, and records the backend in rahti.config.json. |
| --ws | Puts features = ["ws"] on the rahti dependency, which is what compiles rahti::ws and the #[socket] attribute, and records "ws": true in the config. |
| --mcp | Enables the optional mcp Cargo feature, local .mcp.json, editable public/llms.txt, generated discovery and bearer-protected Streamable HTTP at /mcp/. See MCP server. |
| --local <path> | Path dependencies on a Rahti checkout instead of published crates. For working on the framework itself. |
Every project is written with its own documentation — AGENTS.md, the CLAUDE.md that points at it, and the convention documents under docs/conventions/, with the database and WebSocket documents only where the feature was chosen. They are ledgered scaffold files, so upgrade refreshes unedited copies as the framework moves.
cargo rahti upgrade
An upgrade rewrites or removes only files whose current hash still matches the ledger in rahti.config.json. A file you edited is yours: it is preserved and reported, never guessed at.
# Refresh unedited scaffold files, and move the version pins forward.
cargo rahti upgrade
# Print what would change, and change nothing.
cargo rahti upgrade --dry-run
# Add a feature to a project that started without it.
cargo rahti upgrade --db postgres
cargo rahti upgrade --ws
cargo rahti upgrade --mcp| Flag | What it does |
|---|---|
| -n, --dry-run | Print what would change, and change nothing. A dry run never asks a question — name the feature to preview adding it. |
| -f, --force [path...] | Take back scaffolded files you have edited. See below. |
| --db [backend] | Add a database to a project that has none — the same flag new takes. Writes the files, records the backend, and adds SeaORM to Cargo.toml and DATABASE_URL to .env. |
| --ws | Add WebSockets to a project without them, cargo feature and all. |
| --mcp | Add the optional MCP feature, local configuration, public service context, generated HTTP routes, and recorded choice to a project that started without them. |
| -h, --help | Print the usage message. cargo rahti help and a bare cargo rahti do the same. |
| -V, --version | Print the installed cargo-rahti version. |
It never regenerates Cargo.toml or .env from a template — that would undo your dependencies, a path dependency, or a real credential — but it does amend them, by the smallest edit that makes the files it just wrote compile and run. The amendments are driven by rahti.config.json rather than by what this run added, so a project that gained a feature by editing its config is repaired by running upgrade again; every edit is skipped when it is already there, so running it any number of times is the same as running it once.
In the config file, upgrade rewrites only what it owns: createdWith and the scaffold ledger. The port, the app directory, and every CSS setting stay exactly as you wrote them. The CSS engine is deliberately not offered: switching it rewrites an authored stylesheet, which is a migration rather than an addition.
Version pins move with the tool
upgrade moves the rahti and rahti-build version pins in Cargo.toml to the version of the tool that is running. The framework ships in lockstep, and the files an upgrade writes are written against its own version — a pin left behind is the failure that hides best, because the project still compiles and still runs, and quietly does none of what its new main.rs says.
- Only ever forward, never backward onto an older pin.
- Never onto a
--localpath dependency, which is a checkout you are deliberately building against. - Never over a requirement you wrote to float — a caret, a wildcard, a pre-release — which is you asking for something other than one exact version.
- A shape it cannot read — a
[dependencies.rahti]table, a dependency spread over several lines — is reported with the line to add rather than guessed at.
--force: rejoining the scaffold
An upgrade leaves edited files alone, which is right until the day you want the framework's current copy back. --force is how a project that diverged rejoins the scaffold.
# Preview first — a replaced file is not kept anywhere.
cargo rahti upgrade --force --dry-run
# Take back the framework's own files: src/main.rs, build.rs,
# .cargo/config.toml, the documents, the PulsePoint assets.
cargo rahti upgrade --force
# Take back exactly these, an application file included.
cargo rahti upgrade --force src/app/page.rs src/app/layout.rs| Form | What it takes |
|---|---|
| --force | The framework's own files — src/main.rs, build.rs, .cargo/config.toml, the documents, the PulsePoint assets — and nothing else under src/, because that is your application. A file the ledger has no record of is passed by: it may be your own under a name a newer template took. |
| --force <path...> | Exactly the paths named, an application file included — and a file the ledger has no record of, which is written and recorded, or only recorded when it already matches. A path that is not a scaffold file of this project is refused rather than silently ignored. |
The optional tools
Three more executables, each installed only when you want what it does. None of them is read by cargo rahti upgrade, and none holds the framework's own release line back.
cargo rahti-ui
Installs shadcn/ui components, ported to Rahti, into src/components/rahti_ui/ as source the application owns. One name brings the whole graph: the components it imports, and the icons it imports, which are handed to cargo rahti-icons. There is no crate to cargo add — the file is the component.
cargo rahti-ui add button card dialog # the components, and their graph
cargo rahti-ui list --search menu # what the catalog has
cargo rahti-ui update # re-fetch, keeping your edits
cargo rahti-ui theme # check globals.cssupdate re-fetches everything installed and leaves alone any file whose hash no longer matches the one rahti-ui.json recorded — so an edit is safe, and --force is what says otherwise. The first add also writes the theme those class strings name into src/app/globals.css, unless you have edited it. Full reference: UI components.
cargo rahti-icons
Fetches an icon once and writes it into src/components/rahti_icons/, where the build already looks. The application also needs the runtime those files call into, which is an ordinary cargo add.
cargo add rahti-icons # the runtime, once per project
cargo rahti-icons add user chevron-down
cargo rahti-icons update # re-fetch what is installed
cargo rahti-icons list --search arrowEvery command that changes what is installed rewrites rahti-icons.json and .github/instructions/rahti-icons.instructions.md at the project root — neither with a timestamp, so a run that changed nothing is an empty diff. Full flags and the props an icon takes: Icons.
cargo rahti native
Windows and Android packaging. cargo rahti native … is forwarded by cargo-rahti to the installed helper, and cargo rahti-native … reaches it directly through cargo's own subcommand dispatch. When the helper is not installed, cargo rahti native prints the line that installs it and installs nothing.
cargo rahti-native init --identifier com.example.myapp --windows --android
cargo rahti-native doctor
cargo rahti-native dev --target windows
cargo rahti-native dev --target android
cargo rahti-native build --target android --format aabPackaging itself is delegated to Tauri's CLI, which is a third install — cargo install tauri-cli --version "^2" --locked — because that CLI has to match the tauri version in the generated shell's manifest, which is yours to move on your own schedule. doctor checks only what the named target needs and installs nothing; build prints the absolute path of every artifact. Full reference: Native packaging.
Environment variables
These are read at run time, not at build time. rahti::load_env() is the one .env reader for the process: it is idempotent and never overwrites a variable the environment already carries, so a real environment variable always wins over the file.
| Variable | Read by | For |
|---|---|---|
| PORT | rahti::listen | Overrides the configured port. The name every managed platform sets. |
| HOST | rahti::listen | Overrides the configured host. Set it to 0.0.0.0 where a platform routes traffic in from outside the process. |
| RAHTI_DEV | the runtime | Forces development reload on or off, whatever the build profile says. |
| RAHTI_PUBLIC_DIR | the runtime | Overrides the configured static directory. |
| DATABASE_URL | src/db.rs | The connection string. See Database. |
| AUTH_SECRET | rahti::auth | Signing the session cookie. Generated per project. |
| AUTH_COOKIE_NAME | rahti::auth | The cookie's name. Generated per project. |
| SESSION_LIFETIME_HOURS | rahti::auth | Optional session lifetime. |
| APP_TIMEZONE | rahti::time | Optional IANA timezone for application dates and local daily schedules; defaults to UTC. |
| RAHTI_TAILWIND | the build step | A Tailwind binary to use instead of the one in .rahti/bin or on PATH. |
Four more belong to uploads — RAHTI_MAX_UPLOAD, RAHTI_MAX_FILE, RAHTI_SPILL_THRESHOLD and RAHTI_SPILL_DIR, all byte counts but the last. They are documented beside the limits they move, in RPC & uploads.
Six more belong to native packaging — the RAHTI_NATIVE_* signing variables — and are read by the build rather than by a running server. They are documented in Native packaging, which is also where the reason they are environment variables and not a config field is.
Where the server binds
rahti.config.json records the address a project develops on, and the generated routes.rs hands that pair to rahti::listen. A managed platform does not read that file: it starts the built binary and names the address through the environment, usually assigning a different port on every deploy. So the environment wins.
# A project scaffolds with host 0.0.0.0, so a deployment usually names
# only the port — no edit to main.rs, no second copy of the address.
PORT=8080 ./my-app
# HOST is there for the other direction: a project that narrowed its
# config to the loopback, or a platform that wants one specific address.
PORT=8080 HOST=0.0.0.0 ./my-appThat is the whole deployment story for the address — a project develops on the address it was scaffolded with and deploys with no edit to main.rs, no second copy of the port in the config, and no platform-specific branch. A variable exported empty counts as unset: a platform that writes PORT= has not chosen a port, and the configured value stands. A PORT that is not a number from 0 to 65535 stops the server rather than being guessed at.
// src/main.rs — the same two lines in development and in production.
let listener = rahti::listen(routes::HOST, routes::PORT).await;
// Not the bind address verbatim: `0.0.0.0` is every interface, which is
// not somewhere a browser can go.
println!("Server running on {}", rahti::local_url(&listener));The startup line names where to open a browser, which is not always the address that bound. 0.0.0.0 and [::] mean "every interface on this machine" — a sentence about listening, not a destination — and a browser handed one refuses it outright. So rahti::local_url prints a wildcard bind as localhost, the same server named the way this machine reaches it; any other address prints as it is.
When the port is taken
Binding's one common failure has two correct answers. In development the culprit is a server from an earlier run still holding the port, and the goal is a running server rather than that exact port — so the server walks forward to the next free one and says so, however the port was chosen. In release the port is a contract, because whatever routes traffic to the process points at it: a busy port is stated, the source of the value is named, and the process exits.
A port can also be half taken. 0.0.0.0 binds IPv4 only, and the operating system lets a different process hold the same port on IPv6. The bind succeeds, but http://localhost:… sends a browser to the other server, because localhost resolves to ::1 first. So a wildcard IPv4 bind counts as busy when another server answers on [::1] at its port: development moves on as it does for any busy port, and a release build keeps its port and says that localhost reaches someone else — use 127.0.0.1 or stop the other server.
