CLI Reference
The Polyphony backend ships a command-line interface for administration tasks that
are not exposed through the web UI. All commands are run from the backend/
directory (or inside the running container).
Contents
python cli.py <group> <command> [options]
Inside Docker:
docker compose exec backend python cli <group> <command> [options]
Groups
| Group | Purpose |
|---|---|
users | User account and role management |
projects | Project export / import |
database | Full-database backup, restore, and reset |
users
users list
List every registered user together with their assigned roles.
python cli.py users list
Output: one line per user — id, email, name, roles=…
users add-admin
Create a new user and assign all three roles (admin, researcher, annotator) in
one step. The command prompts for name, email, and password interactively.
python cli.py users add-admin
All three prompts can also be passed as options to skip interactive input:
python cli.py users add-admin --name "Alice" --email alice@example.com --password secret
users add-role
Add a role to an existing user.
python cli.py users add-role --email <email> --role <role>
| Option | Required | Values |
|---|---|---|
--email | yes | user's e-mail address |
--role | yes | admin, researcher, or annotator |
users remove-role
Remove a role from a user.
python cli.py users remove-role --email <email> --role <role>
Same options as add-role.
users change-password
Interactively set a new password for a user (input is hidden and must be confirmed).
python cli.py users change-password --email <email>
projects
projects list
List all projects with their IDs and names.
python cli.py projects list
projects export
Export a single project to a portable JSON file that can be imported into another Polyphony installation.
python cli.py projects export --id <project_id> [-o <file>]
| Option | Required | Description |
|---|---|---|
--id | yes | Numeric project ID (see projects list) |
-o, --output | no | Destination file. Defaults to stdout. |
projects import
Import a project from a JSON file previously created by projects export.
python cli.py projects import -f <file> --user-id <id> --team-id <id> [--name-suffix <suffix>]
| Option | Required | Description |
|---|---|---|
-f, --file | yes | Path to the JSON export file |
--user-id | yes | ID of the user who will own the imported project |
--team-id | yes | ID of the team the project belongs to |
--name-suffix | no | Appended to the project name (default: (imported)) |
All internal IDs (annotations, corpus entries, etc.) are remapped so existing data is never overwritten.
database
These commands operate on the entire database. They require pg_dump / pg_restore
to be available in PATH for PostgreSQL installations.
database reset
Drop all data and schema, then automatically re-apply all Alembic migrations so the database is immediately ready to use. You will be asked to confirm before anything is deleted.
python cli.py database reset
Warning: This is irreversible. All users, projects, annotations, and plugin data are permanently deleted.
Supported databases: PostgreSQL, SQLite.
database export
Create a binary dump of the PostgreSQL database using pg_dump. The dump file can
be used later with database import or with standard PostgreSQL tools.
python cli.py database export -o <file>
| Option | Required | Description |
|---|---|---|
-o, --output | yes | Destination file path (e.g. backup.dump) |
Example:
python cli.py database export -o /backups/polyphony_$(date +%Y%m%d).dump
Inside Docker:
docker compose exec backend python cli database export -o /tmp/backup.dump
docker compose cp backend:/tmp/backup.dump ./backup.dump
Supported databases: PostgreSQL only.
database import
Restore a dump file produced by database export into the running database. You
will be asked to confirm before the operation begins because all existing data is
replaced.
python cli.py database import -f <file>
| Option | Required | Description |
|---|---|---|
-f, --file | yes | Path to the dump file |
Example:
python cli.py database import -f ./backup.dump
Inside Docker:
docker compose cp ./backup.dump backend:/tmp/backup.dump
docker compose exec backend python cli database import -f /tmp/backup.dump
Warning: This replaces all existing data in the database with the contents of the dump file.
Supported databases: PostgreSQL only.
Environment
The CLI reads the same .env file and environment variables as the application
server. The most relevant variable is DATABASE_URL:
DATABASE_URL=postgresql+psycopg2://user:password@host:5432/dbname
When running inside Docker, this variable is already set via docker-compose.yml.
When running locally against a remote database, export it before calling the CLI:
export DATABASE_URL=postgresql+psycopg2://workbench:workbench@localhost:5432/llm_workbench
python cli.py users list