Admin & Maintenance

Commands you run against a deployment rather than against a config: create the account that can sign in, produce and settle the secrets the environment needs, and upgrade the binary in place.

sovrium admin create

Provision an admin user directly in the database. This is the bootstrap path — it needs no running server and no full config.

# Prompt for the password (echo disabled, like sudo)
sovrium admin create me@example.com

# Supply it non-interactively (CI, provisioning scripts)
sovrium admin create me@example.com --password 's3cret-pass'

# Resolve auth settings from a specific config
sovrium admin create me@example.com --config app.yaml

The auth configuration is resolved in order: an explicit --config <path>, then APP_SCHEMA, then a minimal built-in default — so the bare form works with no config file at all. Migrations run first, so this also works against an empty database.

Two things to know before scripting it:

• No TTY and no --password is an error. In a non-interactive shell you must pass --password, or the command exits 1 rather than hanging on a prompt.
• It is idempotent. If the email already has an account, nothing is changed.

If the resolved config has no auth block, the command refuses and tells you to add one.

sovrium secret generate

Print freshly generated, cryptographically random secrets as paste-ready .env lines. Each is 256 bits, rendered as 64 hexadecimal characters.

sovrium secret generate                  # both
sovrium secret generate auth >> .env     # append one to your .env
sovrium secret generate encryption       # encryption key only

Neither secret has to be set. An unset SOVRIUM_ENCRYPTION_KEY is generated and kept in the data directory on first start, and AUTH_SECRET is derived from it. Generate them when you want to manage them yourself — see Secrets for when that is worth doing.

sovrium secret adopt

Write the encryption key this process already has into <data dir>/encryption-key, where the server looks for it.

This is the one command that deliberately does persist a secret, and it exists for a single migration. A deployment that has always supplied SOVRIUM_ENCRYPTION_KEY cannot simply stop: the next start would find no key file, generate a fresh key, and quietly orphan every stored credential the old one protected. Adopting first makes removing the variable a no-op.

export SOVRIUM_ENCRYPTION_KEY=<the key currently in use>
sovrium secret adopt

Encryption key adopted — written to /srv/app/.sovrium/encryption-key (mode 0600)

Three outcomes, and the third is the point:

Overwriting a different key would make everything encrypted under the stored one unreadable, and only you know which of the two is authoritative. Keep the persisted key by unsetting the variable, or delete the file first if the environment holds the key your data was actually encrypted with.

sovrium update

Update Sovrium to the latest release. What actually happens depends on how it was installed, which the command detects for you:

sovrium update
sovrium update --help

Delegating to Homebrew and Scoop rather than self-replacing is deliberate: it keeps the package manager's own version ledger correct. Docker containers cannot self-update, so that path prints the pull command instead.

Related Pages

• CLI Overview — the full command surface.
• Environment Variables — where the generated secrets go.
• User Management — managing accounts after the first admin.
• Security Hardening — secret rotation and deployment posture.