CLI reference¶

Audited at b67fdde3. Run relay --help or append --help to a command for its installed version. These are shell commands; chat commands go in the composer.

Server and configuration¶

RELAY_HOME=/path/to/data relay start
RELAY_HOME=/path/to/data relay start -c host=127.0.0.1 -c port=9001
relay --version

-c / --config key.path=value can be repeated and has highest startup precedence. Quote arrays, for example -c 'messageStorage=[sqlite,text]'. start --dev relaxes script CSP for local development; it does not start Vite or watch Go source. See configuration for paths and defaults.

Users¶

Run start once to initialize users/. Use the same data directory and operating-system account for every command. The users group is absent in public mode.

Command	Effect
`relay users add --admin <name>`	Create an administrator; omit `--admin` for an ordinary user
`relay users list`	List persisted account names
`relay users edit <name>`	Edit account JSON with `$EDITOR` (defaults to `vi`)
`relay users reset <name>`	Reset password and clear saved sessions; retains MFA factors
`relay users remove <name>`	Remove the account; this is not a complete history/upload erasure procedure

add prompts for a password of at least eight characters and whether to save logs (default yes). Both add and reset accept --password, but interactive entry avoids exposing the password in shell history and process arguments. Noninteractive add --password … defaults to logging off unless --save-logs is supplied.

For manual account-file edits or recovery, stop Relay first to avoid concurrent writes, back up the file, preserve its permissions and valid JSON, then restart. Prefer the Administration > Users controls for normal live account changes. See first administrator and account recovery.

Storage¶

Command	Effect
`relay storage migrate [username]`	Open the configured provider and apply its schema migrations; skips accounts with logging off
`relay storage import-sqlite [username]`	Copy SQLite history into configured PostgreSQL; requires its connection string
`relay storage clean [user]`	Apply configured retention to stored messages
`relay storage backends`	Current master: list database modules compiled into this server
`relay storage import-shortlinks-sqlite`	Current master: import legacy short links into the configured non-SQLite backend; see migration prerequisites

Omitting the optional account selects all accounts. storage clean rejects a disabled retention policy; it does not enable one for you. Stop Relay for migrations/imports, preserve the original files, and verify restored history before removing any source. Review retention and backups.

Migration¶

Legacy JavaScript configuration is not loaded by the Go server. From a source checkout with the dumper script available:

relay migrate-config --home /path/to/legacy-data \
  --dump-script /path/to/relay/scripts/migrate-config-dump.js \
  --out /path/to/review/config.yaml

Create the output directory first. This evaluates config.js using Node (--node selects the executable); only evaluate trusted configuration. --dump /path/to/dump.json accepts a pre-generated dump without Node. --home is required even with a dump. The default output is <home>/config.yaml, and an existing output file is overwritten. Back it up first. Unsupported function-valued WEBIRC settings require conversion to structured {password, hostnamePrefix} entries; the command reports affected paths. Review the output and administrator overrides before moving it into service.

Packages¶

Command	Effect
`relay install <source>`	Install a compatible theme package from a `file:` directory or HTTP(S) tar.gz URL
`relay uninstall <name>`	Remove an installed package
`relay outdated`	Check installed package versions
`relay upgrade [packages...]`	Upgrade selected packages, or all installed packages

Packages require a valid theme.json; installed files and source metadata live under packages/. relay upgrade upgrades packages, not the Relay server binary or container. Use the server upgrade procedure for those.