CLI Reference

The odeion binary has six subcommands:

Subcommand	Purpose
serve (default)	Starts the HTTP server. Running odeion with flags but no subcommand is shorthand for odeion serve.
psql	Opens a psql session against the embedded database.
doctor	Collects a diagnostic bundle for bug reports.
reset-password	Generates a password recovery link for a user when an admin is locked out.
config	Reads and writes server settings as YAML (export, import, edit). See Configuration.
reload	Signals a running server to re-read settings from the database.

Database migrations run automatically on server startup.

odeion serve

Starts the HTTP server.

Flag	Env Variable	Default	Description
--database-url	DATABASE_URL	(required)	PostgreSQL connection URL, or local for embedded postgres
--port	ODEION_PORT	8080	HTTP port
--data-dir	ODEION_DATA_DIR	Platform default	Persistent data directory for databases, caches, logs, and thumbnails
--version			Print version info and exit

The server always binds to 0.0.0.0 on the specified port.

Usage

# Start with an external PostgreSQL database
odeion serve --database-url "postgres://user:pass@localhost/odeion"

# Start with embedded postgres (data stored in --data-dir)
odeion serve --database-url local --port 3000

# Using environment variables
DATABASE_URL=local ODEION_PORT=3000 odeion serve

odeion psql

Opens a psql session connected to the embedded PostgreSQL database. Only works while odeion serve is running. Requires the psql client binary on PATH (the official Docker image ships it).

By default connects as a read-only role (odeion_ro) that only has SELECT on the schema. Pass --full-access to connect as the superuser.

Flag	Default	Description
--data-dir	Matches serve	Must point at the same data directory the server is using
--database-url	local	Only local is supported. For external DBs, use psql directly
--full-access	false	Connect as the superuser instead of the read-only role

Arguments after -- are forwarded to psql verbatim:

# Interactive read-only session
odeion psql

# Run a one-off query
odeion psql -- -c 'SELECT count(*) FROM users'

# Full admin access (for writes / DDL)
odeion psql --full-access -- -c 'VACUUM ANALYZE'

# Execute a script
odeion psql --full-access -- -f migration.sql

odeion doctor

Collects a diagnostic bundle (system info, embedded postgres state, redacted logs, admin settings) into a single zip suitable for attaching to a bug report or sending to support.

# Default: all sections, redacted, unencrypted
odeion doctor

# Server is broken, grab everything else
odeion doctor --no-db

# Encrypt for secure transfer to support
odeion doctor --age-recipient=age1qz...zk2

See Debugging for the full flag list, what’s collected, how redaction works, and how the age encryption flow works.

odeion reset-password

Generates a one-time password recovery link for a user. Intended as an escape hatch when the only admin is locked out and there’s no other admin to issue a reset through the UI. Requires the server to be running (or a --database-url pointing at the external database).

Flag	Default	Description
<username> (positional)	(required)	The username of the account to reset.
--expires-in	24h	How long the recovery link is valid.
--data-dir	$ODEION_DATA_DIR	Must match the serve process.
--database-url	local	Connect to the embedded postgres, or an external DSN.

odeion reset-password admin
odeion reset-password alice --expires-in=1h

The command prints the reset token, expiry time, and (when base_url is set in system_settings) a full URL to open in a browser. If the account was locked, the lock is cleared at the same time. See Password Reset for the full reset flows.

odeion reload

Sends SIGHUP to a running odeion serve process so it re-reads DB-backed settings. Useful after a direct SQL edit of system_settings, or in scripts that bypass odeion config import (which already triggers a reload on success).

Flag	Default	Description
--data-dir	$ODEION_DATA_DIR	Must match the serve process.

odeion reload

Boot-time keys (HTTP port, embedded-postgres configuration) still require a full restart.

Version

odeion --version

Prints the version number, git commit hash, and build timestamp.