Command Line Interface (CLI)

Last updated: May 29, 2026

The xltrail CLI is the primary tool for managing your Compose-based xltrail installation. It wraps Docker Compose and handles versioning, configuration, backups, and upgrades.

Installation

To install or update the CLI, run as root:

curl -sSL https://www.xltrail.com/cli -o /usr/local/bin/xltrail
chmod +x /usr/local/bin/xltrail

Commands

xltrail install

Performs a fresh installation of xltrail. In online mode, it downloads the Docker Compose manifest and pulls images from the registry. In air-gapped mode, it loads images from a local tarball.

The install command automatically stops any running instance and starts the new one.

# Online — install latest or a specific version:
xltrail install
xltrail install -v 4.3.5487
 
# Air-gapped — install from a local tarball:
xltrail install -f /path/to/xltrail-4.3.5487.tar.gz

xltrail update

Checks for a newer version and upgrades in place. Downloads the new manifest, pulls updated images, then stops and restarts the application automatically. Online mode only — for air-gapped environments, use xltrail install -f.

# Update to the latest available version:
xltrail update
 
# Update to a specific version:
xltrail update -v 4.3.5487

xltrail config

Interactive configuration wizard. Creates the config file at /etc/xltrail/xltrail.conf if it doesn’t exist (generating secrets for SECRET_KEY, POSTGRES_PASSWORD, and FILESTORE_SECRET), then prompts for the Docker registry password and hostname.

For advanced settings, edit /etc/xltrail/xltrail.conf directly.

xltrail config

xltrail start / stop / restart

Controls the application lifecycle via Docker Compose.

xltrail start    # docker-compose up -d
xltrail stop     # docker-compose down --remove-orphans
xltrail restart  # stop + start

xltrail version

Displays the current app version, build number, and CLI version.

xltrail version

xltrail status

Shows the status of all xltrail Docker containers, or Stopped if none are running.

xltrail status

xltrail logs

View container logs. Requires at least one argument.

# All containers:
xltrail logs --all
 
# Follow logs in real-time:
xltrail logs --all --follow
 
# Specific service:
xltrail logs server
xltrail logs server --follow

xltrail backup / restore

Creates or restores a full backup including the PostgreSQL database, filestore, and Git repositories.

The application must be running to create a backup. A restore will stop the application, replace all data, then restart it.

# Create a backup (default: ./xltrail_backup_<timestamp>.tar.gz):
xltrail backup
 
# Create a backup at a specific path:
xltrail backup -f /path/to/backup.tar.gz
 
# Restore from a backup:
xltrail restore -f /path/to/backup.tar.gz

xltrail backupdb / restoredb

Database-only backup and restore. Useful for PostgreSQL major version upgrades where a full backup is not needed.

The application must be running to create a database backup. A restore will stop the database, replace its data, then restart.

# Back up the PostgreSQL database:
xltrail backupdb
 
# Restore the PostgreSQL database:
xltrail restoredb

See Database: Upgrade PostgreSQL version for the full upgrade procedure.

xltrail password

Resets the password for the built-in admin user. The application must be running.

xltrail password

xltrail encrypt

Encrypts a configuration value for use in xltrail.conf. Prefix the config key with SECURE_ to use encrypted values. The application must be running.

xltrail encrypt

xltrail checks

Runs diagnostic checks: network connectivity to xltrail.com and the Docker registry, Docker and Docker Compose availability, and free disk space on /tmp, /var/lib/xltrail, and /var/lib/docker.

xltrail checks

xltrail support

Generates a support package containing logs from all xltrail containers. The application must be running.

# Default: ./xltrail_support_<timestamp>.tar.gz
xltrail support
 
# Custom path:
xltrail support -f /path/to/support-package.tar.gz