- Concept
- Version ยท 6.0.2
- Create
Command reference
Last updated: November 17, 2026
Detailed usage, flags, and examples for all Liquibase Secure server CLI commands.
Every command except pull takes --dir, the deployment directory. Without --dir, install uses the directory in the LIQUIBASE_PLATFORM_DIR environment variable, or else the current directory, and creates the directory when it is missing. The other commands look in LIQUIBASE_PLATFORM_DIR, then in the current directory when it holds docker-compose.yml, then in the directory install recorded. When none of these holds a deployment, they stop with LB-SEC-INS-0018 and No installation found.
install
Set up a new self-hosted Liquibase Secure server deployment. This is the primary first-run command that handles everything from secret generation to health verification.
Warning: install stops when it finds an existing deployment's containers or data volumes on the host, even with --force. It generates new database passwords, and a database keeps the password it was created with, so an install over existing data would fail partway through. To bring an existing deployment up to a new version, run update, which keeps your data and secrets. To start over, run uninstall without --keep-data, which deletes the data the volumes hold.
What it does
Resolve the deployment directory (
--dir, elseLIQUIBASE_PLATFORM_DIR, else the current directory), creating it when missing. Any directory works. A directory used only for the deployment is safest, becauseinstallplaces the release's deployment files there, writes its own beside them, and can replace a file that has the same nameRefuse a
--tagnewer than this CLI, withLB-SEC-INS-0038, before anything is downloaded. See A release newer than the CLICheck for an existing
.env(prevents accidental reinstall)Refuse when a deployment's containers or data volumes are already on this host, even with
--forcePre-flight checks: Docker 24+, Compose 2.20+, and the HTTP and HTTPS ports free (80 and 443, or the
--http-portand--https-portvalues). With--db-host, also check thatLIQUIBASE_PLATFORM_DB_PASSWORDis set and that the--db-tls-ca-filefile existsDownload and verify the deployment files for
--tagwith your license, or read them from--files, then pull the container images from--registryand place the deployment filesCreate the
db-tls/directory beside.env, and copy the--db-tls-ca-filefile into itWith
--db-host, check that the external database accepts the connection, with the same--db-*settings the migrations use, and that it runs PostgreSQL 17. When it does not accept the connection,installstops withLB-SEC-INS-0041and the database's reason. When it runs an older PostgreSQL,installstops withLB-SEC-INS-0031, and when its version can't be read, withLB-SEC-INS-0039. Each stop comes beforeinstallwrites.env,secrets/orcerts/. The bundled database is not checkedGenerate the four platform secrets into
secrets/beside.env, one file each with file mode 0600, then generate.envfrom.env.samplewith those four lines left empty. With--db-host,secrets/db_passwordgets the password fromLIQUIBASE_PLATFORM_DB_PASSWORD, and.envgets the connection withCOMPOSE_PROFILESleft empty. Without it,.envgetsCOMPOSE_PROFILES=bundled-dbInstall TLS certificates: the pair given by
--tls-certand--tls-key, or a generated self-signed certificateStart database containers (
db,secrets-db,redis). The bundleddbstarts only when the primary database is bundledWait for database health
Run Liquibase migrations (primary DB + secrets DB), then record the version tag
Start full stack
Wait for the
api,nginxandwebcontainers to report healthy, then display the success message
If a step fails, install removes what that run created, so the next run starts clean.
When install succeeds, it records the deployment directory for later commands, and it prints that status, logs and stop find the deployment from any directory. If it cannot write the record, it warns you, and later commands need --dir or the deployment directory as the current directory.
Flags
Flag | Required | Default | Description |
| Yes, unless | None | Your license file, or the directory holding your license files. |
| No | None | A directory that |
| No |
| Registry to pull the images from. Set it to your own registry after you copy the images there with |
| No | The version of the CLI | Version to install |
| No |
| Hostname or IPv4 address for the TLS certificate and application URLs. A generated self-signed certificate covers this value, |
| No |
| Overwrite the |
| No |
| Host port the proxy publishes for HTTP |
| No |
| Host port the proxy publishes for HTTPS. Application URLs in |
| No | None | Path to a TLS certificate in PEM format. Without it, a self-signed certificate is generated. Requires |
| No | None | Path to the TLS private key in PEM format. Requires |
| No |
| Also run the nginx, PostgreSQL and Redis images from |
| No |
| Deployment directory, created when missing |
| No | None | Host of an external PostgreSQL 17 database. Omit it to run the bundled database. Needs the password in the |
| No |
| Port of the external database. Requires |
| No |
| Name of the external database. Requires |
| No |
| User the server and its migrations connect as. Requires |
| No |
| Connect to the external database over TLS. The database's certificate is always verified. Requires |
| No | The system's trusted CAs | CA file in PEM format to verify the database's certificate against, copied into |
Examples
pull
Copy a release's images from oci.liquibase.com into your own registry, so you can scan and approve them there and then install from that registry with install --registry. The images are copied by digest, with every platform they are built for. With --files, pull also saves the release's verified deployment files, so a host that cannot reach Liquibase can install with install --registry and install --files.
Before you run it
Sign in to your registry with
docker login.pullpushes with your own Docker credentials for that registry, and reads fromoci.liquibase.comwith your license.Install the Docker buildx plugin, which
pulluses to copy the images. Without it,pullstops withLB-SEC-INS-0010. On Linux, buildx is a separate package that some distribution Docker packages leave out.
What it does
With
--files, downloads and verifies the release's deployment files into that directory. This runs first, so a license that does not cover the version fails before any image is copiedCopies the
liquibase-platform-api,liquibase-platform-web,liquibase-platform-migrateandliquibase-platform-lltimages for--taginto the--toregistry, and prints each image's digestWith
--include-third-party, also copies the nginx, PostgreSQL and Redis images the stack runsPrints the
installcommand that installs from the copy
Flags
Flag | Required | Default | Description |
| Yes | None | Your license file, or the directory holding your license files |
| Yes | None | Registry, with an optional path, to copy the images into. Pass the same value to |
| No | The version of the CLI | Version to copy |
| No |
| Also copy the nginx, PostgreSQL and Redis images, for |
| No | None | Also save the release's verified deployment files in this directory, for |
Examples
update
Upgrade an existing deployment to a new version in place. Pulls the new images, runs the new version's database migrations, and recreates the services, preserving your data and secrets. install is refused over an existing deployment, even with --force.
What it does
Refuses a
--tagnewer than this CLI, withLB-SEC-INS-0038, before it downloads anything.Checks that the HTTP and HTTPS ports are free, that Docker Compose is 2.20 or newer, and that the database settings in
.envare usable, before it downloads or writes anything.With an external primary database, checks that the database accepts the connection, before it downloads the deployment files or changes anything in the deployment directory. The check runs through the installed version's migrate image, or pulls the new version's migrate image first when the installed one is no longer on the host. When the database does not accept the connection,
updatestops withLB-SEC-INS-0041and the database's reason, and.envis left unchanged. The bundled database is not checked.Downloads and verifies the new version's deployment files with your license, or reads them from
--files. Until the migrations run, a failure puts the deployment directory back as it was.Pulls the new version's images. The images are pulled before the old containers are released, so a pull that fails leaves your existing deployment one
startaway.When the release moves PostgreSQL to a new major version, checks that the move can go ahead and that there is enough free disk, and stops if not. Then, when the new version has upgrade notices this deployment hasn't applied yet, lists them and asks you to type
yes. Nothing has changed yet at this point. See Upgrade notices.Copies the bundled databases to new volumes on PostgreSQL 17 when the release moves PostgreSQL to a new major version, after you type
upgradeto confirm.Updates
IMAGE_TAGin your existing.env. Secrets are never regenerated. The previous file is kept beside it as.env.bak, and the new one is written atomically, so.envis never left half-written. If the download or the pull fails, nothing in.envchanges. If the deployment still keeps its four platform secrets in.env, this step also moves them intosecrets/. On a deployment with a bundled database and noCOMPOSE_PROFILESline, it addsCOMPOSE_PROFILES=bundled-dbto.env, and it creates thedb-tls/directory beside.envif there is none.Starts the
db,secrets-db, andrediscontainers and waits for the databases to report healthy. With an external primary database, the bundleddbdoes not start.Removes the TimescaleDB extension, if it is installed, from the
postgresdatabase, from the platform database whenLIQUIBASE_PLATFORM_DB_NAMEnames another, and fromtemplate1. Releases that ran the database on the TimescaleDB image installed the extension in each. Nothing uses it, and it blocks migrations on standard PostgreSQL. On any other install, and when the primary database is external, this step does nothing.Runs the new version's migrations against the primary database, then against the secrets database.
Recreates the services with the new images.
Waits for the
apiandnginxcontainers to report healthy, and exits non-zero if the API does not become reachable.updatedoes not wait forweb.
If a migration or the final health check fails, the command stops and says so. Your data and volumes are left intact and the databases stay running, so you can inspect them before retrying. If any step after the .env update fails, .env already names the new version and .env.bak holds the previous file. Re-run update once the cause is fixed, or restore .env from .env.bak to stay on the version you had.
If you run docker compose yourself on a deployment with a bundled database, .env must have COMPOSE_PROFILES=bundled-db, or the db service does not start.
When update copied the databases to PostgreSQL 17, a failure at any step before the new version is healthy is handled differently. update removes the new volumes and puts the previous version back on its old volumes, running if it was running before. With an external primary database, this ends when the migration of the primary database starts. Your server holds the only copy of that data, so there is nothing to go back to after that point.
Moving the secrets out of .env
A deployment installed with an earlier release keeps its four platform secrets in .env, so docker inspect shows them in the configuration of the containers that use them. update moves them into files in secrets/ as part of the upgrade, so there is no step to do by hand:
Before it writes anything,
updatechecks that each of the four secrets has a value. If one has none, it names the setting and stops without changing anything.It writes each value from
.envto its own file insecrets/, with file mode 0600. Adocker-compose.ymlfile that does not read these files ignores them, so the deployment keeps working if the upgrade stops here.After the images are pulled and
.envis backed up as.env.bak, it backs updocker-compose.ymlasdocker-compose.yml.bak-followed by a timestamp, and installs thedocker-compose.ymlfile that ships with the CLI, which reads the secrets from those files.It empties the four lines in
.envand leaves a comment above each one that names its file.
Warning: After the move, .env.bak still holds the four secrets as plain values, so that it can take you back to the version you had. Delete it once the upgraded deployment runs, or keep it with your backups. uninstall removes it, and the next update replaces it with a copy of the current .env, which no longer holds them.
A deployment that already reads its secrets from secrets/ is left as it is, so running update again changes nothing more. If you copy the new docker-compose.yml file into the deployment yourself instead, start and migrate write any missing file in secrets/ from the value .env still holds, and say so. Until you run update, those values stay in .env, and so in the API container's environment.
Moving the database to standard PostgreSQL
Earlier releases ran the primary database on the timescale/timescaledb:2.17.2-pg14 image. This release runs both databases on standard PostgreSQL 17, postgres:17.11-alpine, which your organization can review and approve like any other PostgreSQL image. Nothing the server stores uses TimescaleDB.
Before you upgrade, set the database settings for your host size in
.env. The TimescaleDB image tuned memory settings for your host, and after the upgrade the database uses the release's defaults instead.Run
./liquibase-platform update --license your_license_file --tag your_version. It copies your data to PostgreSQL 17 without the TimescaleDB extension and installs the release'sdocker-compose.ymlfile, which runs the database on standard PostgreSQL.
If .env pins TIMESCALEDB_IMAGE to an image in your own registry, update sets POSTGRES_IMAGE to postgres:17.11-alpine in that registry and comments the old line out. Copy that image to your registry before you run update, for example with pull --to --include-third-party. If POSTGRES_IMAGE is already set, update only comments the old line out. A pin that update cannot place under a registry is commented out with a warning, and the image then comes from Docker Hub. To pull it from your registry, set POSTGRES_IMAGE in .env to your copy of postgres:17.11-alpine and run ./liquibase-platform start.
If you edited your docker-compose.yml file, update stops before it changes anything and leaves the release's copy beside it as docker-compose.yml.new. Merge your changes into the new file, replace docker-compose.yml with it, and run update again.
Keep a data volume on the PostgreSQL build that created it. An Alpine volume run on a Debian image, or the reverse, starts without an error but silently corrupts its text indexes. Moving your data to another PostgreSQL build, or to a PostgreSQL server of your own, is a dump and restore. Never move the data volume itself.
Upgrading the databases to PostgreSQL 17
PostgreSQL 17 is the only supported major version from this release on. PostgreSQL 17 cannot start on data that PostgreSQL 14 wrote, so update copies the primary database and the secrets database into new volumes whose names end in -pg17. Plan a maintenance window. The server is down from the start of the copy until update finishes.
Before it stops anything,
updatechecks that the filesystem holding the Docker volumes has free space of at least 1.2 times the size of the databases it copies. It prints the databases, their sizes, the free disk and the downtime, then asks you to typeupgrade. Any other answer printsAborted.and stopsupdatewithout changing anything. Add--non-interactiveto skip the prompt, for example in a pipeline. With no terminal and no--non-interactive,updatestops withLB-SEC-INS-0027without changing anything. When the release also has upgrade notices,updateasks about those first, so with no terminal it stops earlier, withLB-SEC-INS-0020.It stops the
nginx,webandapiservices and the old databases, then copies each database into its new volume withpg_dump. The copy carries the roles, the databases and their settings, the settings made withALTER SYSTEM, andpg_hba.conf, and leaves out the TimescaleDB extension.If any step fails before the new version is healthy,
updateremoves the new volumes and puts the previous version back on the old ones.The old volumes are kept, untouched.
updatelists them with their sizes and thedocker volume rmcommand that removes them.
With an external primary database, update copies only the secrets database. It reads your server's version before it changes anything, and stops when the server runs a version older than PostgreSQL 17, so upgrade it first.
If install --include-third-party set POSTGRES_IMAGE to your registry, update changes it to postgres:17.11-alpine in the same registry. Copy that image to your registry first. If POSTGRES_IMAGE names any other image, update keeps it, and the image must be a PostgreSQL 17 build. With a PostgreSQL 14 image, update stops before it changes anything. Set POSTGRES_IMAGE to your PostgreSQL 17 build, then run update again with the same tag.
To go back to the previous version after a successful upgrade, put back the docker-compose.yml file that update kept beside it as docker-compose.yml.bak- followed by a timestamp. Then run update with the previous release's CLI, passing that release's version as --tag. That docker-compose.yml file mounts the old volumes, which nothing has written since the copy, so anything written after the upgrade is lost. This release's CLI does not go back: given an earlier release, it stops before it changes anything. Remove the old volumes only once you no longer need to go back.
To upgrade again after you go back:
Back up and remove the
-pg17volumes, for example withdocker volume rm liquibase-platform_db-data-pg17 liquibase-platform_secrets-db-data-pg17.Run
update. It stops and says thatdocker-compose.ymlhas local changes, because you put the file back by hand.Replace
docker-compose.ymlwithdocker-compose.yml.new, whichupdateleft beside it, and runupdateagain. It copies the old volumes to PostgreSQL 17 again.
Warning: Remove the -pg17 volumes before step 3. If they are still there, update does not copy and does not stop. It starts the new version on the data those volumes hold from the first upgrade, and anything written after you went back is left behind on the old volumes.
Upgrade notices
Some releases change something you rely on, such as who can see or edit content that already exists. When the new version has upgrade notices this deployment hasn't applied yet, update prints them right after it pulls the images, before it changes anything, and asks you to confirm:
This upgrade makes changes you may need to act on:
- Entry Tier roles lose governance write access on existing catalogs.
Type "yes" to continue the upgrade:Type
yesto continue. Any other answer printsAborted.and exits with status 0, leaving the deployment as it was, with the previous version still running.With
--non-interactive,updateprints the notices and continues without asking. With no terminal and no--non-interactive, it stops withLB-SEC-INS-0020and names the flag.After the success message,
updatelists the notices it applied again.A notice is shown until the change behind it is applied, so if a migration fails, the next
updateshows it again.When the release also moves the databases to PostgreSQL 17,
updateasks twice: first about the notices, then for you to typeupgrade.--non-interactiveskips both.
To read the notices, update connects to both databases the way the migrations do. If the bundled databases are stopped, for example after stop, it starts them for the notices and stops them again if you decline. If it can't reach one, it stops with LB-SEC-INS-0037 before it changes anything.
A release newer than the CLI
install and update refuse a --tag whose version is newer than the CLI you run them with. They stop with LB-SEC-INS-0038 before anything is downloaded, because a newer release can need install or upgrade steps an older CLI doesn't know. Download the CLI archive for that release and run the command with its CLI. Only the version number is compared: a 6.0.1 CLI refuses 6.0.2, and a pre-release such as 6.0.1-rc.1 counts as 6.0.1.
Flags
Flag | Required | Default | Description |
| Yes | None | Version to upgrade to (letters, digits, |
| Yes, unless | None | Your license file, or the directory holding your license files. |
| No | None | A directory that |
| No |
| Override the image registry |
| No |
| Skip both confirmation prompts, for pipelines. |
| No |
| Deployment directory, the one that holds |
Examples
start
Start the Liquibase Secure server stack.
Checks that .env exists (must be installed first), writes any missing file in secrets/ from the value .env still holds, runs docker compose up -d, waits for the api, nginx and web containers to report healthy, and displays the access URL. Health comes from each service's Docker Compose healthcheck, which runs inside its container, so the host's network, published ports and certificate play no part in it. A service whose entry in docker-compose.yml has no healthcheck, as in a file from an earlier release, gets one warning instead, as long as its container stays up. If update kept your edited docker-compose.yml file, the warning tells you to merge the healthcheck blocks from docker-compose.yml.new into it.
Flags
Flag | Default | Description |
|
| Deployment directory, the one that holds |
Example
liquibase-platform startstop
Stop the Liquibase Secure server stack.
Flags
Flag | Default | Description |
|
| Remove data volumes. Prompts for confirmation before proceeding. |
|
| Skip confirmation prompts (for scripting) |
|
| Deployment directory, the one that holds |
Without --reset, data volumes are preserved and the stack can be restarted with liquibase-platform start.
With --reset, the prompt shows the deployment directory before you confirm. stop --reset --non-interactive never uses the directory install recorded, because nothing would confirm which deployment it deletes. Name the deployment with --dir, LIQUIBASE_PLATFORM_DIR, or the current directory.
Examples
status
Show deployment status.
Displays a table with the name, status, health, and image of each container, then the version, the API health, and the URL. API health is read from Docker. It is OK when the api and nginx containers both report healthy, and Unreachable otherwise. The --json output keeps apiResponseMs, which is how long reading that health took.
Flags
Flag | Default | Description |
|
| Output as JSON (includes all metrics) |
|
| Deployment directory, the one that holds |
Example output
logs
View or bundle logs from the stack.
Flags
Flag | Default | Description |
| all | One or more service names to filter (can repeat) |
|
| Number of lines to show from end |
|
| Stream logs in real time |
|
| Generate a support diagnostic bundle |
|
| Deployment directory, the one that holds |
Diagnostic bundle
When filing a support ticket, use --bundle to generate a tarball containing:
Docker logs (last 1000 lines per service)
System info (Docker version, OS, disk usage)
Container status (JSON)
Redacted
.envfile (secret settings replaced with***REDACTED***)
Settings whose names mark them as secret, such as passwords, tokens and keys (the AI API key among them), are replaced with ***REDACTED***. Their values, the password in any URL with embedded credentials, and the token in any invitation, password-reset, or email-verification link are also removed from the logs, the system info and the container status. A secret value shorter than 8 characters is redacted in the .env file only.
liquibase-platform logs --bundle
# Creates: liquibase-platform-support-<timestamp>.tar.gzExamples
migrate
Run database migrations independently. Primarily used during upgrades to apply schema changes before restarting services.
What it does
Loads registry and tag from
.envWith an external primary database, checks that the database accepts the connection, through the installed migrate image. When it does not,
migratestops withLB-SEC-INS-0041and the database's reason before it starts anything. This check also runs for--dry-runEnsures databases are running (starts them if needed). The bundled
dbstarts only when the primary database is bundledRemoves the unused TimescaleDB extension, if it is installed, from the
postgresdatabase, from the platform database whenLIQUIBASE_PLATFORM_DB_NAMEnames another, and fromtemplate1(skipped for dry-run and for an external primary database)Runs Liquibase
updateagainst the primary database (insights-api.yml)Runs Liquibase
updateagainst the secrets databaseTags the migration (skipped for dry-run)
Flags
Flag | Default | Description |
|
| Run |
|
| Deployment directory, the one that holds |
Examples
reset-password
Create a one-time password reset link for an account, without email. Use it when outbound email is not set up and someone cannot reset their own password. Run it on the Docker host, because it reads the account from the deployment's database. Run it from the deployment directory, or add --dir with the path to that directory.
./liquibase-platform reset-password your_user_emailReplace your_user_email with the address of the account. For example, priya.shah@example.com.
What it does
Finds the account by email address, ignoring case
Prints a reset link that is valid for one hour and can be used once
Leaves the current password in place until someone opens the link and chooses a new one
Example output
When it refuses
The command creates no link and says why in these cases:
No account uses the address.
Several accounts match the address. Resolve the duplicates first.
The account signs in through single sign-on and has no password. The user signs in with their organization account instead.
The account is deactivated. Reactivate it on the Users & Access page, then run the command again.
The account has no sign-in identity left, which happens when the single sign-on provider it came from was deleted.
A refusal is reported as LB-SEC-INS-0023 and names the account and the reason.
When the database cannot be reached, the command stops with LB-SEC-INS-0024. If the stack is stopped, start it with liquibase-platform start, then run the command again. Otherwise, check the database with liquibase-platform status and liquibase-platform logs --service db.
uninstall
Remove the Liquibase Secure server deployment.
What it does
Asks you to type
uninstallto confirm, unless--non-interactiveStops and removes the containers
Removes the data volumes, unless
--keep-data. After an upgrade to PostgreSQL 17, that is both sets: the PostgreSQL 14 volumesinsights_insights-db-dataandinsights_insights-secrets-db-data, whichupdatekept, and the PostgreSQL 17 volumesliquibase-platform_db-data-pg17andliquibase-platform_secrets-db-data-pg17. Theinsights_redis-datavolume goes tooDeletes the generated files
.env,.env.bak,secrets/,certs/and.liquibase-platform/, unless--keep-dataKeeps the template files
.env.sample,docker-compose.ymlanddefault.conf.template
Flags
Flag | Default | Description |
|
| Preserve the data volumes, |
|
| Skip confirmation prompts |
|
| Deployment directory, the one that holds |
Note: With --keep-data, the deployment's data stays on disk in the volumes liquibase-platform_db-data-pg17, liquibase-platform_secrets-db-data-pg17 and insights_redis-data, and in insights_insights-db-data and insights_insights-secrets-db-data if an upgrade to PostgreSQL 17 kept them. Remove those yourself when you no longer need the data.
The prompt shows the deployment directory before you confirm. uninstall --non-interactive never uses the directory install recorded, because nothing would confirm which deployment it deletes. Name the deployment with --dir, LIQUIBASE_PLATFORM_DIR, or the current directory.
uninstall forgets the recorded directory when it removes that deployment. uninstall --keep-data keeps the record, so a later update still finds the deployment.