Server administration via the CLI#

This page documents the qcfractal-server command line interface used to initialize, start, and administer a QCFractal server. The CLI is implemented in qcfractal/qcfractal/qcfractal_server_cli.py and uses argparse.

Quick start#

  • Create an initial configuration with secrets:

    qcfractal-server init-config --config /srv/qcfractal/server.yaml

  • Initialize the database (creates DB and tables; starts managed Postgres if applicable):

    qcfractal-server init-db --config /srv/qcfractal/server.yaml

  • Start the server (API + internal job runner):

    qcfractal-server start --config /srv/qcfractal/server.yaml -v

Getting help#

  • Top-level help and version:

    qcfractal-server --help
qcfractal-server --version

  • Help for a subcommand (eg, user):

    qcfractal-server user --help

Global options#

These options can be provided before any subcommand, or after the subcommand when shown as part of a subcommand’s help.

  • --config PATH Path to a QCFractal YAML configuration. See Server Configuration.

  • -v/--verbose Increase logging verbosity for the command itself. Use -vv for debug output.

Subcommands#

init-config#

Create an initial configuration file, generating secure random secrets and writing an example configuration you can edit.

Synopsis:

qcfractal-server init-config --config /path/to/server.yaml [--full] [-v]

Options:

  • --full Include all available configuration fields with their default values.

Notes:

  • The file is created or overwritten at the path given to --config.

  • You will likely want to edit the file (database credentials, API host/port, etc.) before initializing the database or starting the server.

init-db#

Initialize the PostgreSQL database described in the configuration. If QCFractal is configured to manage its own Postgres instance (database.own: true), this command will initialize that instance and create the target database and tables. If using an external Postgres, the database must exist and be reachable; this command will create tables within it.

Synopsis:

qcfractal-server init-db --config /path/to/server.yaml [-v]

start#

Start a QCFractal server, running both the HTTP API and the internal job runner (service updates and manager cleanup). This command will ensure Postgres is alive and that the database schema is up-to-date before starting.

Synopsis:

qcfractal-server start --config /path/to/server.yaml \
                       [--host HOST] [--port PORT] \
                       [--logfile PATH] [--loglevel LEVEL] \
                       [--enable-security {true,false}] \
                       [--disable-job-runner] [-v]

Useful options (override configuration values):

  • --host / --port Bind address and port for the HTTP API (same keys as api.host and api.port).

  • --logfile File to write server logs to; if omitted, logs are written to stdout.

  • --loglevel One of DEBUG, INFO, WARNING, ERROR, CRITICAL.

  • --enable-security Override the configuration’s security toggle at startup.

  • --disable-job-runner Expert: start only the API and skip the internal job-runner processes.

Signals and shutdown:

  • Press Ctrl+C or send SIGTERM to stop. The CLI will terminate child processes cleanly.

start-job-runner#

Start only the internal job runner (background processes that advance services and perform manager cleanup). This is primarily useful in advanced deployments where API and job runner are separated.

Synopsis:

qcfractal-server start-job-runner --config /path/to/server.yaml \
                                  [--logfile PATH] [--loglevel LEVEL] [-v]

start-api#

Start only the HTTP API server. As with start, the command checks connectivity to Postgres before launching the API.

Synopsis:

qcfractal-server start-api --config /path/to/server.yaml \
                           [--logfile PATH] [--loglevel LEVEL] [-v]

upgrade-db#

Upgrade the QCFractal database schema to the latest version. Use this after updating QCFractal to a newer release when migration is required.

Synopsis:

qcfractal-server upgrade-db --config /path/to/server.yaml [-v]

If the database cannot be upgraded (eg, incompatible or missing revisions), an error is printed and the command exits non-zero.

upgrade-config#

Upgrade an older QCFractal configuration file to the current format. The original file is backed up to <path>.backup (or .backup.N if needed), and a new file is written with converted settings and fresh secrets.

Synopsis:

qcfractal-server upgrade-config --config /path/to/old_server.yaml [-v]

info#

Display server and environment information, or show Alembic CLI invocation used for DB migrations.

Synopsis:

qcfractal-server info --config /path/to/server.yaml [server|alembic]

  • server (default) Prints Python executable, QCFractal version, Postgres server version, and the active QCFractal configuration rendered in YAML.

  • alembic Prints the exact Alembic CLI command QCFractal would use to operate on the database.

user#

Manage users in the QCFractal database. All user operations require database access via --config.

Synopsis:

qcfractal-server user [list | info USERNAME | add USERNAME --role ROLE [--password PW]
                                 [--fullname NAME] [--organization ORG] [--email EMAIL]
                      | modify USERNAME [--fullname NAME] [--organization ORG]
                                 [--email EMAIL] [--role ROLE]
                                 [--enable | --disable]
                                 [--password PW | --reset-password]
                      | delete USERNAME [--no-prompt]] --config /path/to/server.yaml [-v]

Subcommands and options:

  • list Show a table of all users (username, role, auth type, enabled, fullname).

  • info USERNAME Show details for one user.

  • add USERNAME --role ROLE [--password PW] [--fullname ...] [--organization ...] [--email ...] Create a new user with the given role. If --password is omitted, a secure password is generated and printed once. The new user is enabled by default.

  • modify USERNAME with flags: - --fullname, --organization, --email: Update profile fields. - --role: Change the user role. - --enable / --disable: Toggle enabled state (mutually exclusive). - Password management:

    • --password PW: Set a specific password.

    • --reset-password: Generate and print a new random password.

  • delete USERNAME [--no-prompt] Delete the user. Without --no-prompt, a confirmation is required.

Note on roles: the available roles are built into the server and cannot be customized. Valid values for --role are admin, maintain, monitor, submit, read, compute, and anonymous; anything else is rejected. See Users, Roles, and Groups for what each one permits.

Groups have no CLI subcommand - manage them with a client (add_group() and friends).

backup#

Create a PostgreSQL backup (logical dump) of the current database to a file.

Synopsis:

qcfractal-server backup --config /path/to/server.yaml /path/to/backup.dump [-v]

The filename is required and may be absolute or relative to the current shell.

restore#

Restore the database from a backup file created by backup. The target database must be reachable and empty or suitable for restore per your Postgres setup.

Synopsis:

qcfractal-server restore --config /path/to/server.yaml /path/to/backup.dump [-v]

Common tasks and examples#

Fresh installation#

# 1) Create a config (edit afterwards as needed)
qcfractal-server init-config --config /srv/qcfractal/server.yaml --full

# 2) Edit /srv/qcfractal/server.yaml (db credentials, host/port, etc.)

# 3) Initialize the database
qcfractal-server init-db --config /srv/qcfractal/server.yaml

# 4) Start the server
qcfractal-server start --config /srv/qcfractal/server.yaml -v

External Postgres example#

# server.yaml (excerpt)
database:
  own: false
  host: db.example.org
  port: 5432
  database_name: qcarchive
  username: qcfractal
  password: "<secret>"

# Ensure the database exists and credentials work, then:
qcfractal-server init-db --config server.yaml
qcfractal-server start --config server.yaml

User management#

# Add an admin user with a generated password
qcfractal-server user add admin --role admin --fullname "QC Admin" --email admin@example.org \
    --config server.yaml

# List users
qcfractal-server user list --config server.yaml

# Show user info
qcfractal-server user info admin --config server.yaml

# Change role and reset password
qcfractal-server user modify admin --role maintain --reset-password --config server.yaml

# Disable a user
qcfractal-server user modify alice --disable --config server.yaml

# Delete a user (with confirmation)
qcfractal-server user delete temp_user --config server.yaml

Upgrading QCFractal and the database#

# After upgrading the QCFractal package, upgrade DB schema
qcfractal-server upgrade-db --config server.yaml

# If you have an older config file, upgrade it
qcfractal-server upgrade-config --config old_server.yaml

Backups and restore#

# Create a backup (logical dump)
qcfractal-server backup --config server.yaml /backups/qcfractal_$(date +%F).dump

# Restore from a backup
qcfractal-server restore --config server.yaml /backups/qcfractal_2025-10-01.dump

Running API and job runner separately#

# Terminal 1: API only
qcfractal-server start-api --config server.yaml --loglevel INFO

# Terminal 2: job runner only
qcfractal-server start-job-runner --config server.yaml --loglevel INFO

Logging and verbosity#

  • -v increases the CLI’s verbosity; -vv enables debug-level messages.

  • --logfile and --loglevel control server process logging during start, start-api, and start-job-runner.

Troubleshooting#

  • Use qcfractal-server info server --config server.yaml to print environment and the fully merged configuration.

  • If a child process dies shortly after start, check the server logs (stdout or the file specified by --logfile) for stack traces.

  • For database connection issues, verify credentials and reachability, and try psql to the configured host/port/database.

See also#

  • Server Configuration for the full configuration reference.

  • User and dataset administration via the SDK and API is covered elsewhere in the admin guide.