Backend CLI reference
This page provides a comprehensive reference for the Platforma backend command-line options.
Common examples
Here are a few examples of how to combine flags for common setup scenarios.
To run a simple backend for your lab on a local network server:
# Listen on the server's network IP
# Point to a shared folder on the server for data
./platforma --license <YOUR_LICENSE_KEY> \
--listen-address 'http://10.0.1.50' \
--primary-storage-fs-url 'http://10.0.1.50:6347' \
--data-library-fs "lab-data=/mnt/shared/sequencing_data"
To set up a secure, multi-user backend with a custom domain:
# Listen securely on your domain
# Use a password file for user accounts
# Disable the default host data library for better security
./platforma --license <YOUR_LICENSE_KEY> \
--listen-address 'https://platforma.mylab.edu' \
--listen-tls '/path/to/cert.pem,/path/to/key.pem' \
--auth-htpasswd '/etc/platforma/users.htpasswd' \
--no-host-data-library
Core & licensing
| Option | Description | Default | Env Var |
|---|---|---|---|
--license | Your license key (e.g., E-XXXX...). | PL_LICENSE | |
--license-file | Path to a file containing your license key. | ~/.pl.license | PL_LICENSE_FILE |
--config | Path to a custom YAML configuration file. Overrides all other CLI options. | PL_CONFIG_FILE | |
--version | Show version info and exit. | ||
--full-version | Show a more detailed version report and exit. |
Local storage
| Option | Description | Default | Env Var |
|---|---|---|---|
--main-root | Path to the root directory for all local data (database, software, logs, etc.). | ~/.platforma/backend/ | PL_MAIN_ROOT |
--db-dir | Path to store the backend's state database. Useful for placing the DB on a faster local drive when --main-root is on a network share. | <main-root>/rocksdb | PL_DB_DIR |
--work-dir | Path to store temporary working directories for block execution. | <main-root>/work | PL_WORK_DIR |
--packages-dir | Path to store downloaded software packages required by blocks. | <main-root>/packages | PL_PACKAGES_DIR |
Network & connection
| Option | Description | Default | Env Var |
|---|---|---|---|
--listen-address | The network address to listen on (e.g., http://192.168.1.10 or https://platforma.my-company.com). | http://127.0.0.1 | PL_LISTEN_ADDRESS |
--listen-port | The TCP port for the main gRPC API. | 6345 | PL_LISTEN_PORT |
--listen-http-port | The TCP port for the HTTP file storage service. | 6347 | PL_LISTEN_HTTP_PORT |
--listen-tls | Enables TLS (HTTPS). Provide a path to cert and key files (cert.pem,key.pem). If no path is given, a self-signed certificate is generated. | Disabled | PL_LISTEN_TLS |
--self-signed-tls-domain | When generating a self-signed certificate, add this domain. Can be used multiple times. | PL_LISTEN_TLS_DOMAINS | |
--self-signed-tls-ip | When generating a self-signed certificate, add this IP address. Can be used multiple times. | PL_LISTEN_TLS_IPS |
Primary storage
This is the main storage for workflow results.
| Option | Description | Default | Env Var |
|---|---|---|---|
--primary-storage-fs-url | For the default filesystem storage, this is the URL that the Desktop App must use to download results. | http://127.0.0.1:6347 | PL_PRIMARY_STORAGE_FS_URL |
--primary-storage-s3 | Use an S3 bucket as primary storage. Accepts s3://bucket/prefix or https://endpoint/bucket/prefix URLs. | Filesystem | PL_PRIMARY_STORAGE_S3 |
--primary-storage-gcs | Use a Google Cloud Storage bucket as primary storage. Accepts gs://bucket/prefix URLs. | Filesystem | PL_PRIMARY_STORAGE_GCS |
--primary-storage-s3-region | The AWS region for the S3 bucket. | PL_PRIMARY_STORAGE_S3_REGION | |
--primary-storage-s3-key | S3 access key ID. | PL_PRIMARY_STORAGE_S3_KEY | |
--primary-storage-s3-secret | S3 secret access key. | PL_PRIMARY_STORAGE_S3_SECRET | |
--primary-storage-s3-external-endpoint | An alternative S3 endpoint URL for the Desktop App to use, if different from the one the backend uses. | PL_PRIMARY_STORAGE_S3_EXTERNAL_ENDPOINT | |
--primary-storage-s3-no-data-integrity | Disable modern data integrity checks for S3 uploads. May be needed for some S3-compatible services like older MinIO or Ceph. | PL_PRIMARY_STORAGE_S3_NO_DATA_INTEGRITY |
Data libraries
Connects the backend to existing raw data sources.
| Option | Description | Default | Env Var |
|---|---|---|---|
--no-host-data-library | Disables the default host=fs:/ data library, which exposes the entire server filesystem. | Enabled | PL_NO_HOST_DATA_LIBRARY |
--data-library-fs | Attach a local filesystem directory as a data library. Format: id=path. Can be used multiple times. | PL_DATA_LIBRARY_FS_PATH | |
--data-library-s3 | Attach an S3 bucket as a data library. Format: id=s3://bucket/prefix. Can be used multiple times. | PL_DATA_LIBRARY_S3_URL | |
--data-library-s3-region | The AWS region for a specific S3 data library. Format: id=region. | PL_DATA_LIBRARY_S3_REGION | |
--data-library-s3-key | S3 access key ID for a specific data library. Format: id=key. | PL_DATA_LIBRARY_S3_KEY | |
--data-library-s3-secret | S3 secret access key for a specific data library. Format: id=secret. | PL_DATA_LIBRARY_S3_SECRET | |
--data-library-s3-no-data-integrity | Disable data integrity checks for a specific S3 library. Format id=true. | PL_DATA_LIBRARY_S3_NO_DATA_INTEGRITY |
Runner options
Controls how and where analysis jobs are executed. For Google Batch options, see the advanced GCP installation guide.
| Option | Description | Default | Env Var |
|---|---|---|---|
--runner-local-cpu | Limit the number of CPU cores available for local job execution. | All available cores | PL_RUNNER_LOCAL_CPU |
--runner-local-ram | Limit the amount of RAM available for local job execution. Accepts suffixes (GB, GiB) or percentages (e.g., 50%). | 95% of total RAM | PL_RUNNER_LOCAL_RAM |
User authentication
| Option | Description | Default | Env Var |
|---|---|---|---|
--auth-htpasswd | Enable authentication using a static htpasswd file. Provide the path to the file. | Disabled | PL_AUTH_HTPASSWD |
--auth-ldap-server | Enable LDAP authentication. Provide the LDAP server URL (e.g., ldap://server.com). | PL_AUTH_LDAP_SERVER | |
--auth-ldap-dn | The Distinguished Name (DN) template for LDAP user lookup. %u is replaced with the username. | PL_AUTH_LDAP_DN | |
--auth-ldap-start-tls | Use the StartTLS extension to secure a plain ldap:// connection. | PL_AUTH_LDAP_START_TLS |
Logging
| Option | Description | Default | Env Var |
|---|---|---|---|
--log-level | Logging level: info, warn, debug, or error. | info | PL_LOG_LEVEL |
--log-dir | Directory to store log files. | <main-root>/log | PL_LOG_DIR |
--log-rotation-size | Max size of a log file before rotation (e.g., 20MB). | 20MiB | PL_LOG_ROTATION_SIZE |
--log-rotation-backups | Number of old log files to keep. | 20 | PL_LOG_ROTATION_BACKUPS |
--no-log-rotation | Disable automatic log rotation. | PL_NO_LOG_ROTATION | |
--no-log-compression | Do not compress rotated log files. | PL_NO_LOG_COMPRESSION | |
--quiet | Disable logging to stdout/stderr. |
Special options
| Option | Description | Env Var |
|---|---|---|
--use-restricted-network-mode | Start the backend in a mode intended for networks with limited internet access. | PL_USE_RESTRICTED_NETWORK_MODE |
--skip-extended-self-check | Skips slower startup checks, such as verifying Google Batch connectivity. | PL_SKIP_EXTENDED_SELF_CHECK |
--only-verify-config | Performs all deep configuration verification checks and then exits. | |
--cancel-running-blocks | Cancels all currently running blocks and exits without starting the full service. | |
--get-queue-limits | Estimates and prints the CPU/RAM limits for job queues and exits. |