CLI reference
The commands you'll use to run, administer, and back up Railbase.
Updated
The railbase binary is also its own admin tool. This reference covers the
commands an operator reaches for; run railbase <command> --help for the full
flag set on any of them. The same binary also includes developer helpers such as
railbase dev, railbase generate ..., and railbase ui ....
Important
The vault is opened by one process at a time. Any command that touches it
(admin, backup, jobs, cron, config, role, tenant, audit,
export, …) fails with "vault: file is locked by another process" while
serve is running — stop the server first. Day-two operations on a live
instance (jobs, backups, users, settings) are all available in the admin
console, which runs in-process.
serve
Start the HTTP server.
railbase serve [--addr :8095] [--data-dir <binary-dir>/pb_data]
[--vault-path <file>] [--vault-password <pw>]
[--vault-cache-mb 1024] [--log-level warn]
| Flag | Default | Purpose |
|---|---|---|
--addr |
:8095 |
HTTP listen address |
--data-dir |
<binary-dir>/pb_data |
Data directory (falls back to ./pb_data when the binary's own dir isn't writable) |
--vault-path |
<data-dir>/railbase.vault |
Data file location |
--vault-password |
— | Vault unlock password (required in production) |
--vault-cache-mb |
1024 |
Vault page-cache size in MB |
--log-level |
warn |
debug · info · warn · error |
Each flag has an env equivalent (RAILBASE_HTTP_ADDR, RAILBASE_DATA_DIR, …);
precedence is flag > env > default. See Environment variables.
Important
The vault won't unlock with no password. Locally, set RAILBASE_DEV=true
(or runtime.dev: true in railbase.yaml) to use the development key; in
production pass --vault-password, or better RAILBASE_VAULT_PASSWORD_FILE
(a path — keeps the secret out of /proc/<pid>/environ and ps; the
preferred production source). This applies to every command that opens the
vault — serve, migrate, admin, config, …
version
railbase version # tag, commit, build date, Go version
admin
Manage superusers. The email is a positional argument.
railbase admin bootstrap you@example.com [--password <p>] [--company <name>] [--no-email]
railbase admin list
railbase admin delete <email-or-id>
railbase admin reset-password <email-or-id>
bootstrap seeds the first administrator on a fresh install and refuses
once any admin exists. It also seeds the first company/workspace (tenant) so
the tenant-gated marketplace unlocks: pass --company <name>, or on a terminal
it prompts for one (Railbase never names your company for you). It prompts for a
password (twice) unless --password is given. Routine admin onboarding is the invite flow — admin
UI → Administrators → Invite, or POST /api/_admin/admins/invite — which sends a
single-use email link and lets the new admin set their own password. Two-factor
authentication is enrolled self-service from the admin's account settings. See
Security.
backup
Snapshot and restore the vault. A snapshot is a byte-exact copy of the .vault
file.
railbase backup [--out <file.vault>] # default <data-dir>/backups/backup-<UTC>.vault
railbase backup --restore <file.vault> # restore (no separate `restore` command)
railbase backup list [--dir <path>] # newest first
Full workflow in Backups & restore.
tenant
For multi-tenant deployments — registers tenants in the _tenants collection;
collections declared with .Tenant() scope their rows per tenant via the
X-Tenant request header.
railbase tenant create <name>
railbase tenant list
railbase tenant delete <id-or-name> # SOFT delete — marks the tenant deleted
tenant delete is a soft delete: it marks the _tenants row deleted so the
tenant stops resolving, but it does not remove that tenant's rows from other
collections or its _tenant_members entries. Purge tenant-scoped data
deliberately if you need it gone.
See Data & multi-tenancy.
migrate
Schema migrations apply automatically on boot, so you rarely run these by hand.
railbase migrate diff <slug> # generate a migration from your schema DSL
railbase migrate up [--allow-drift] # apply pending migrations
railbase migrate status # applied + pending, as a table
Note
migrate down is not implemented — it's a visible slot that refuses to run
(it returns an error). Write an explicit reversing migration instead of relying
on an automatic rollback.
config
Read and write runtime-mutable settings (stored in the vault).
railbase config get <key>
railbase config set <key> <value> [--string]
railbase config list
railbase config delete <key>
set parses the value as JSON by default (so 587 is a number, true a bool);
pass --string to force a literal string.
ui
Copy the public Preact UI-kit source into a frontend project.
railbase ui list
railbase ui peers
railbase ui init [--out <project-root>]
railbase ui add button input form
railbase ui add --all
The UI kit is a source-copy workflow, not an npm package. --out is the
project root (defaults to the current directory); the command writes into
its src/ itself — so pass --out ., not --out ./src, or the kit lands in
src/src/. ui add resolves component-local dependencies and refuses unknown
names.
audit
Verify and export the tamper-evident audit trail.
railbase audit verify [--target all|legacy|site|tenant]
railbase audit export --out <file|-> [--from <RFC3339>] [--to <RFC3339>]
Tip
There is no --config, --dev, or database-URL global flag — there's no
database to point at. Development orchestration (hot reload, frontend dev
server) lives in the separate railbase dev command.