CLI reference

The commands you'll use to run, administer, and back up Railbase.

Updated 2026-06-10

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.

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 ./pb_data]
               [--vault-path <file>] [--vault-password <pw>]
               [--vault-cache-mb 1024] [--log-level info]

Flag	Default	Purpose
`--addr`	`:8095`	HTTP listen address
`--data-dir`	`./pb_data`	Data directory
`--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`	`info`	`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 / RAILBASE_VAULT_PASSWORD. This applies to every command that opens the vault — serve, migrate, admin, config, …

version

railbase version      # version, build info, installed plugins

admin

Manage superusers. The email is a positional argument.

railbase admin create you@example.com [--password <p>] [--no-email]
railbase admin list
railbase admin delete <email-or-id>
railbase admin reset-password <email-or-id>

create prompts for a password (twice) unless --password is given. 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 <name>

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 intentionally a no-op stub — 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.

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.