Command line

The qumasc command initialises the database, runs the API and the workers and administers users, API keys and settings without the API. The text below is the help of the commands as the installed version prints it.

Wherever a command names a user (--user, --owner, --on-behalf-of), the user name or the identifier may be given; the user name is tried first. The identifier never changes; the user name is the login name and may change (see Your account).

Commands for accounts and e-mail:

qumasc admin create-user --username <name> [--email <address>] [--role <role>]

Create an account. The identifier is generated (16 hexadecimal digits); --id is only for accounts of earlier installations. The account has no password until one is set.

qumasc admin set-password --user <name or identifier> [--stdin]

Set the password of an account: typed twice without echo, or the first line of standard input with --stdin. The password rules apply and all sessions of the account end. This is how existing accounts get a password for the login.

qumasc admin rename-user --user <name or identifier> --username <new name>

Change the user name. The identifier, and everything stored with it, stays as it is; the former name stays reserved for accounts.username_reserve_days.

qumasc admin set mail.smtp.password <password>

Store the password of the mail server, encrypted with QUMASC_SECRET_KEY; it is printed masked.

qumasc admin credentials rotate

After a change of QUMASC_SECRET_KEY: encrypt the stored source credentials, the two-factor secrets of the users and the password of the mail server with the new key.

qumasc admin examples prepare <file> --user <staff user> [--dry-run] [--timeout S]

Run the examples of a YAML file (template, title, parameters) as jobs of a staff user, with that user’s own provider keys, wait for the workers and publish the results as example datasets; with --dry-run only build and validate the recipes. Runbook and the proposed first set: Example datasets and public sharing.

qumasc mail send [--limit N]

Send the messages of the mail outbox that are due (the workers do it between jobs).

qumasc cleanup

Expire data, create notifications, delete accounts whose e-mail address was never verified (accounts.unverified_days), forget the former user names of deleted accounts after accounts.username_reserve_days, and remove records older than their retention periods (retention.audit_days, retention.usage_days, retention.job_logs_days, retention.mail_outbox_days; 0 keeps them). Each removal is written to the audit log (retention.purge).

Command for the maps of the web portal:

qumasc reference build-tiles [--code-list NUTS|TERYT] [--version <version>] [--force]

Build the boundary tiles (PMTiles) of every NUTS version whose GISCO file and every TERYT state whose PRG package lies in the reference cache (nothing is downloaded), into <reference.tiles.directory>/<code list>/<version>.pmtiles (default: the folder tiles of the reference cache). An up-to-date file (same boundary file, same settings reference.tiles.*) is kept unless --force is given.

qumasc

usage: qumasc [-h] [--database-url DATABASE_URL] [--config CONFIG] [-v]
              {db,serve,worker,cleanup,mail,reference,openapi,admin} ...

Qumasc service commands.

positional arguments:
  {db,serve,worker,cleanup,mail,reference,openapi,admin}
    db                  Database schema.
    serve               Run the service API.
    worker              Run a queue worker.
    cleanup             Expire data, create notifications, remove unverified accounts.
    mail                Outgoing e-mail.
    reference           Reference data (code lists, boundaries).
    openapi             Write the OpenAPI document of the API (no database needed).
    admin               Administration without the API.

options:
  -h, --help            show this help message and exit
  --database-url DATABASE_URL
                        SQLAlchemy URL of the job database.
  --config CONFIG       TOML file with the settings of this installation that differ
                        from the packaged defaults (default: the file named by
                        QUMASC_CONFIG).
  -v, --verbose         Log more.

qumasc db

usage: qumasc db [-h] {init} ...

positional arguments:
  {init}
    init      Create or migrate the schema.

options:
  -h, --help  show this help message and exit

qumasc db init

usage: qumasc db init [-h]

options:
  -h, --help  show this help message and exit

qumasc serve

usage: qumasc serve [-h] [--host HOST] [--port PORT] [--root-path ROOT_PATH]
                    [--workers WORKERS]

options:
  -h, --help            show this help message and exit
  --host HOST
  --port PORT
  --root-path ROOT_PATH
                        Path prefix behind a proxy.
  --workers WORKERS     Number of API processes (uvicorn workers; default 1).

qumasc worker

usage: qumasc worker [-h] [--once] [--poll-interval POLL_INTERVAL]
                     [--worker-id WORKER_ID]

options:
  -h, --help            show this help message and exit
  --once                Process at most one job.
  --poll-interval POLL_INTERVAL
  --worker-id WORKER_ID

qumasc cleanup

usage: qumasc cleanup [-h]

options:
  -h, --help  show this help message and exit

qumasc mail

usage: qumasc mail [-h] {send} ...

positional arguments:
  {send}
    send      Send the messages of the outbox that are due.

options:
  -h, --help  show this help message and exit

qumasc mail send

usage: qumasc mail send [-h] [--limit LIMIT]

options:
  -h, --help     show this help message and exit
  --limit LIMIT  Most messages to handle.

qumasc reference

usage: qumasc reference [-h] {build-tiles} ...

positional arguments:
  {build-tiles}
    build-tiles  Build the boundary tiles (PMTiles) of the NUTS and TERYT versions
                 whose boundary files are in the reference cache (nothing is
                 downloaded).

options:
  -h, --help     show this help message and exit

qumasc reference build-tiles

usage: qumasc reference build-tiles [-h] [--code-list {NUTS,TERYT}]
                                    [--version VERSION] [--force]

options:
  -h, --help            show this help message and exit
  --code-list {NUTS,TERYT}
                        Only this code list (default: both).
  --version VERSION     Only this version, e.g. 2024 or 2026-01-01.
  --force               Build again even if the file is up to date (same boundary file
                        and settings).

qumasc openapi

usage: qumasc openapi [-h] [--output OUTPUT]

options:
  -h, --help       show this help message and exit
  --output OUTPUT  File to write (default: standard output).

qumasc admin

usage: qumasc admin [-h]
                    {create-user,set-password,rename-user,create-key,list-keys,revoke-key,credentials,set,register-dataset,examples}
                    ...

positional arguments:
  {create-user,set-password,rename-user,create-key,list-keys,revoke-key,credentials,set,register-dataset,examples}
    create-user         Create a user.
    set-password        Set the password of an account (asked twice, never shown).
    rename-user         Change the user name (login name) of an account.
    create-key          Create an API key (printed once).
    list-keys           List API keys (never the secrets).
    revoke-key          Revoke a key by identifier or all keys with a label.
    credentials         Source credentials stored by users (never the values).
    set                 Change a setting.
    register-dataset    Register a dataset package that lies on disk, by reference
                        (nothing is copied).
    examples            Example datasets of the Qumasc team (docs/admin/examples.md).

options:
  -h, --help            show this help message and exit

qumasc admin create-user

usage: qumasc admin create-user [-h] [--name NAME] [--email EMAIL]
                                [--role {regular,advanced,group_manager,data_steward,admin,administrator,service_account}]
                                [--group GROUP] [--manages MANAGES]
                                [--username USERNAME] [--id ID]

options:
  -h, --help            show this help message and exit
  --name NAME
  --email EMAIL
  --role {regular,advanced,group_manager,data_steward,admin,administrator,service_account}
  --group GROUP         Group to join (repeatable).
  --manages MANAGES     Group to manage (repeatable).
  --username USERNAME   Login name (lower-case letters, digits, '.', '_', '-').
  --id ID               Identifier (generated if omitted; only for accounts of earlier
                        installations).

qumasc admin set-password

usage: qumasc admin set-password [-h] --user USER [--stdin]

options:
  -h, --help   show this help message and exit
  --user USER  User name or identifier.
  --stdin      Read the password from the first line of standard input (automation).

qumasc admin rename-user

usage: qumasc admin rename-user [-h] --user USER --username USERNAME

options:
  -h, --help           show this help message and exit
  --user USER          Current user name or identifier.
  --username USERNAME  New user name.

qumasc admin create-key

usage: qumasc admin create-key [-h] --user USER [--name NAME]
                               [--expires-days EXPIRES_DAYS] [--scope SCOPE]
                               [--on-behalf-of ON_BEHALF_OF]

options:
  -h, --help            show this help message and exit
  --user USER           User name or identifier.
  --name NAME
  --expires-days EXPIRES_DAYS
  --scope SCOPE         Action prefix (repeatable).
  --on-behalf-of ON_BEHALF_OF
                        User a service token is restricted to (user name or
                        identifier).

qumasc admin list-keys

usage: qumasc admin list-keys [-h] [--user USER] [--all]

options:
  -h, --help   show this help message and exit
  --user USER  Only the keys of this user (user name or identifier).
  --all        Include revoked keys.

qumasc admin revoke-key

usage: qumasc admin revoke-key [-h] (--id ID | --name NAME) [--user USER]

options:
  -h, --help   show this help message and exit
  --id ID      Key identifier (see list-keys).
  --name NAME  Label; every key with this label is revoked.
  --user USER  Only keys of this user (user name or identifier).

qumasc admin credentials

usage: qumasc admin credentials [-h] {list,rotate} ...

positional arguments:
  {list,rotate}
    list         Which users have credentials for which connectors.
    rotate       Encrypt all stored credentials again with the current
                 QUMASC_SECRET_KEY (old key in QUMASC_SECRET_KEY_PREVIOUS).

options:
  -h, --help     show this help message and exit

qumasc admin credentials list

usage: qumasc admin credentials list [-h] [--user USER] [--connector CONNECTOR]

options:
  -h, --help            show this help message and exit
  --user USER           Only the credentials of this user (user name or identifier).
  --connector CONNECTOR
                        Only the credentials for this connector.

qumasc admin credentials rotate

usage: qumasc admin credentials rotate [-h]

options:
  -h, --help  show this help message and exit

qumasc admin set

usage: qumasc admin set [-h] [--comment COMMENT] key value

positional arguments:
  key
  value              JSON value (plain text is taken as a string).

options:
  -h, --help         show this help message and exit
  --comment COMMENT

qumasc admin register-dataset

usage: qumasc admin register-dataset [-h] --owner OWNER [--id ID] [--no-pin] path

positional arguments:
  path           Directory of the package (holds stac-item.json).

options:
  -h, --help     show this help message and exit
  --owner OWNER  User who owns the record (user name or identifier).
  --id ID        Dataset identifier (default: that of the STAC item).
  --no-pin       Do not pin the dataset (it is pinned by default: no expiry).

qumasc admin examples

usage: qumasc admin examples [-h] {prepare} ...

positional arguments:
  {prepare}
    prepare   Run the examples of a YAML file as jobs of a staff user and publish the
              results.

options:
  -h, --help  show this help message and exit

qumasc admin examples prepare

usage: qumasc admin examples prepare [-h] --user USER [--timeout TIMEOUT] [--dry-run]
                                     file

positional arguments:
  file               YAML file: a list of template, title and parameters.

options:
  -h, --help         show this help message and exit
  --user USER        Staff user (administrator or data steward) who runs and owns the
                     examples; the jobs use this user's provider keys.
  --timeout TIMEOUT  Longest wait for the jobs in seconds (default 6 hours).
  --dry-run          Only build and validate the recipes; submit nothing.