- Concept
- Version · 6.0.2
- Create
What is the Liquibase Secure server CLI?
Last updated: November 17, 2026
The Liquibase Secure server CLI, liquibase-platform, installs, updates, and runs a self-hosted Liquibase Secure server deployment with Docker Compose.
The Liquibase Secure server CLI is a lightweight command-line tool that automates self-hosted deployment and management of Liquibase Secure server. It wraps Docker Compose operations with secret generation, health checking, and database migrations into simple, repeatable commands.
What it does
The CLI provides 10 commands that cover the full deployment lifecycle:
Command | Purpose |
|---|---|
| Full first-run setup from your license file: deployment files, image pull, secrets, migrations, health check |
| Upgrade an existing deployment in place, preserving data and secrets |
Copy a release's images into your own registry, and save the deployment files for a host that cannot reach Liquibase | |
| Start the stack |
| Stop the stack (with optional data reset) |
| Show service health and versions |
| Tail logs or generate a support bundle |
| Run database migrations independently (for upgrades) |
| Create a one-time password reset link for an account when email is not set up |
| Remove the deployment |
Why a CLI
The CLI approach was chosen over bash scripts for several key advantages:
Testability: Comprehensive automated test coverage, which is difficult to achieve with bash
Error handling: Structured error messages with recovery suggestions
Cross-platform: Consistent behavior across Linux and macOS
Discoverability: Built-in
--helpfor every command, automatic usage generation
Design principles
Thin wrapper: The CLI runs
docker composeto manage the stack. It does not add its own orchestration layer.No daemon: Each command is a one-shot invocation. No background process runs between commands.
Standard files: The deployment runs from a standard
docker-compose.yml,.envanddefault.conf.templatein the deployment directory, so you can inspect it with Docker Compose. The CLI downloads and verifies these files with your license. It also places the license terms there,LICENSE.txt,THIRD-PARTY-LICENSES.mdandlicenses.tar.gz, for your legal and security reviews.
How the CLI finds your deployment
Every command works on a deployment directory, which holds the deployment's docker-compose.yml, its .env settings file, its secrets, and its certificates. When install succeeds, it records the deployment directory in ~/.config/liquibase-platform/install-dir, or in liquibase-platform/install-dir under $XDG_CONFIG_HOME when that variable is set. That record is the only state the CLI keeps.
A command uses the directory you pass with --dir. Without --dir, it uses the first of these that applies:
The directory in the
LIQUIBASE_PLATFORM_DIRenvironment variable. It must holddocker-compose.yml, just as a--dirdirectory must.The current directory, when it holds
docker-compose.yml.The directory
installrecorded, when it still holdsdocker-compose.yml.
When none of these holds a deployment, the command stops with LB-SEC-INS-0018 and No installation found. An empty LIQUIBASE_PLATFORM_DIR is ignored, and a relative path in --dir or in the variable resolves against the current directory.
install uses --dir, then LIQUIBASE_PLATFORM_DIR, then the current directory, and creates the directory when it is missing. It never uses the record, because it creates the deployment.
uninstall --non-interactive and stop --reset --non-interactive never use the recorded directory, because nothing would confirm which deployment they delete. Name the deployment with --dir, LIQUIBASE_PLATFORM_DIR or the current directory. Without --non-interactive, both commands show the deployment directory and ask before they continue. uninstall --keep-data keeps the record, and uninstall without --keep-data removes the record when it names the deployment being removed.
Note: The record belongs to the user who ran install, so run later commands as that user. sudo drops LIQUIBASE_PLATFORM_DIR by default, so sudo liquibase-platform install installs into the current directory and records it in the root user's home directory. When you run the CLI with sudo, pass --dir, or run sudo --preserve-env=LIQUIBASE_PLATFORM_DIR liquibase-platform followed by the command.
The CLI and the server it manages have separate versions:
CLI version: The version of the
liquibase-platformcommand itself.liquibase-platform --versionprints it.Server version: The release the deployment runs. It is
IMAGE_TAGin the deployment's.envfile, andliquibase-platform statusshows it asVersion.
The record lives outside the CLI, so a newer CLI finds an existing deployment the same way. That is how an update works. You download the CLI of the new release, then run its update with --dir set to your deployment directory. You can leave --dir out when the deployment is the one install recorded. update --non-interactive uses the record too.
Warning: Do not run install from a new folder to point a new CLI at an existing deployment. install would try to create a second deployment, and it refuses with LB-SEC-INS-0011, because one deployment runs per Docker host. install --force does not get around this. It only replaces a leftover .env file that has no deployment behind it.
How to get the CLI
Download the CLI archive for your platform and verify it, then run liquibase-platform install --license your_license_file. The CLI uses your license file to download and verify the deployment files and to pull the images, so you need no separate registry credential. If your organization vets images before they run, or the host can't reach Liquibase, install Liquibase Secure server in a restricted or air-gapped network instead.