Skip to main content
The omni CLI manages self-hosted Omni Docker Compose deployments. v1 supports Docker Compose only.

​
Install

Install the latest release with the install script:
By default, the script installs to $XDG_BIN_HOME when set, otherwise $HOME/.local/bin. Make sure that directory is on your PATH. Install a specific release or choose a different install directory:
The script detects Linux/macOS and x86_64/arm64, downloads the matching GitHub release artifact, and verifies its .sha256 file when present. You can also download the binary manually from the Omni GitHub release assets:
  • omni-linux-x86_64
  • omni-linux-arm64
  • omni-macos-x86_64
  • omni-macos-arm64
  • omni-windows-x86_64.exe
Then place it on your PATH and make it executable on Unix:

​
Upgrade

Run from your Omni Docker Compose install directory, or pass --install-dir:
By default, omni upgrade uses the latest stable GitHub release. To target a specific release:
The upgrade command:
  1. downloads the target release’s omni-docker-compose.tar.gz and verifies omni-docker-compose.tar.gz.sha256 when present;
  2. backs up .env and managed deployment files under .omni/backups/<timestamp>/;
  3. updates managed files such as docker/docker-compose.yml, .env.example, and Caddyfile;
  4. updates OMNI_VERSION in .env to the release image tag;
  5. warns about variables missing from .env and prompts you to append new values;
  6. warns about variables in your .env that no longer appear in .env.example;
  7. runs docker compose pull and docker compose up -d --remove-orphans;
  8. runs a doctor summary.
Useful flags:

​
Managed Compose files and customization

Omni’s Compose files are vendor-managed release assets. The CLI replaces these files during upgrades instead of attempting to merge YAML. This keeps upgrades predictable because service definitions, anchors, profiles, health checks, and image tags often change together. Do not customize docker/docker-compose.yml directly. Put local changes in user-owned override files instead, for example:
  • docker/docker-compose.override.yml
  • docker-compose.override.yml
The CLI includes these override files in its Compose commands and never overwrites them. After a successful upgrade, the CLI records hashes for managed files in .omni/managed-files.json. On the first CLI-managed upgrade, if that manifest does not exist yet, the CLI compares against the currently configured release when possible and otherwise treats changed existing managed files conservatively as local edits.

​
Environment variables

.env.example is the canonical template for a release. During upgrade, the CLI preserves your existing .env values, updates OMNI_VERSION, and prompts for variables that exist in the target .env.example but not in your .env. Missing variables are warnings, not hard errors, because not every variable is required in every deployment. Preview env changes without upgrading:

​
Doctor

Run diagnostics:
doctor checks local deployment files, Docker and Docker Compose availability, Compose service state, container health, image tags, service health endpoints, connector-manager source/connector status where reachable, recent sync run status, and recent logs for suspicious errors.

​
Other commands