# 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.

```bash
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](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

```bash
railbase version      # version, build info, installed plugins
```

## admin

Manage superusers. The email is a **positional** argument.

```bash
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](security).

## backup

Snapshot and restore the vault. A snapshot is a byte-exact copy of the `.vault`
file.

```bash
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](backups-and-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.

```bash
railbase tenant create <name>
railbase tenant list
railbase tenant delete <name>
```

See [Data & multi-tenancy](data-and-tenancy).

## migrate

Schema migrations apply **automatically on boot**, so you rarely run these by
hand.

```bash
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).

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

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