CLI reference (tradr)

The api image ships a tradr command for the jobs that need a server, not a browser. Run it inside the running container:

docker compose exec api tradr --help

Expected result: exit code 0, and the 5 commands below.

Command	Does
tradr migrate --status	Report whether the database schema is current.
tradr storage migrate-to-inline	Pull stored images out of object storage and back into the database.
tradr storage gc	Delete bucket objects no conversation references any more.
tradr create-user <email> [--password <value>]	Create an account from the server, without opening registration.
tradr reset-password <email> [--password <value>]	Set a user’s password from the server.

Every command exits 2 when it cannot reach the database, so a wrapper script can tell “it failed” from “it could not run”.

migrate --status

Reads both migration journals and prints what is applied and what is pending. It opens its own read-only connection and never takes the migration advisory lock, so it is safe to run against a live instance.

docker compose exec api tradr migrate --status

Expected result: exit code 0, ending in Schema is up to date.

Exit code	Meaning
0	The schema is current.
1	Migrations are pending on at least one track.
2	The command cannot reach the database.

The exit codes make it usable as a health gate in a deploy script. See Database & migrations.

storage migrate-to-inline

Only relevant if object storage was configured and you want to turn it off. It rewrites every image that lives as a bucket pointer back to inline data, so the backend can be disabled without stranding an image.

docker compose exec api tradr storage migrate-to-inline

The command is idempotent and resumable — run it again after a failure. An image whose object has gone missing is marked unrecoverable and the run continues rather than aborting.

Self-hosted instances do not need this. With no object storage configured, images are already stored inline.

storage gc

Reclaims objects orphaned by deleted records and retried uploads. Like migrate-to-inline, it applies only to an instance with object storage configured.

docker compose exec api tradr storage gc

The sweep is age-guarded: it never reaps an object young enough to belong to a request still in flight.

create-user <email> [--password <value>]

Creates a user directly. This is how you make the first account on an instance that runs with DISABLE_REGISTRATION=true — the flag closes POST /api/auth/register, but it does not apply to this command, because reaching the CLI already means shell access to the server.

docker compose exec api tradr create-user someone@example.com

Expected result: exit code 0, and a generated password printed to stdout. It is shown once and not stored anywhere else — copy it before you close the terminal, then sign in and change it.

Pass --password <value> to choose one instead. The password is generated by default so that the usual path leaves nothing secret in your shell history.

A password you supply must meet the same length rule the sign-up form applies. The command checks it first and exits 2 with the rule stated, rather than creating an account that the sign-in page would then refuse.

The account uses the same password hashing as the sign-up form, so it can sign in immediately. It is an ordinary user, not an administrator — see SEED_ADMIN_EMAIL in Environment variables.

It never overwrites an existing account. If the email is already taken the command changes nothing and exits 1 — use reset-password to set the password of an account that already exists. It exits 2 when it cannot reach the database.

reset-password <email> [--password <value>]

The recovery path on an instance with no email configured. Without SMTP there is no self-service reset, so the operator sets the password directly.

docker compose exec api tradr reset-password someone@example.com

Expected result: exit code 0, and a generated password printed to stdout. Pass --password <value> to choose one instead of having it generated. As with create-user, a password you supply must meet the same length rule the sign-up form applies, or the command exits 2 and changes nothing.

The command does not mark the account verified — running a command proves nothing about the mailbox. It does not sign existing sessions out either.

It exits 1 when no account matches the email, and 2 when it cannot reach the database.

Next steps

• Upgrade an instance — where migrate --status fits.
• Database & migrations — what the two tracks are.
• Environment variables — the configuration surface.