Skip to content
These docs describe Tradr v0.17.0. Running an older release? Check the release notes for what changed.

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:

Terminal window
docker compose exec api tradr --help

Expected result: exit code 0, and the 7 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 position or 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.
tradr unlock <email> Clear a sign-in lockout for an address from the server.
tradr disable-2fa <email> Remove a lost second factor so the password alone signs in.

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

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.

Terminal window
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.

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.

Terminal window
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.

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

Terminal window
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.

gc also refuses to run while an account import is in progress: it deletes nothing and asks you to re-run it once the import has finished, so it can never remove an object a live import just wrote.

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.

Terminal window
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>]

Section titled “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.

Terminal window
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.

Clears the failed-sign-in counter and any active lock for one address, so a user locked out by repeated bad passwords can sign in again at once. On an instance with no email configured there is no unlock link, so the operator clears the lock directly.

Terminal window
docker compose exec api tradr unlock someone@example.com

Expected result: exit code 0, reporting either that the lockout was cleared or that there was none to clear.

It touches nothing but the lockout state — no password, no session and no second factor. It exits 1 only when the address has neither an account nor a lock, and 2 when it cannot reach the database.

Removes the two-factor secret and backup codes for an account, clears any lock, and ends every session the user has open, all in one transaction. Afterwards the password alone signs in — this is the recovery path when a user loses their authenticator and there is no email to send a reset to.

Terminal window
docker compose exec api tradr disable-2fa someone@example.com

Expected result: exit code 0, reporting that two-factor was disabled and all sessions ended. If the account has no two-factor enabled it changes nothing and says so.

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