Skip to main content
Manage local Observal deployments. The lifecycle commands operate the embedded PostgreSQL, ClickHouse, Redis, and API processes. Upgrade, rollback, and version commands operate a local Docker Compose deployment. Local filesystem, process, Docker, and database access are the authorization boundary. These commands do not require a reachable Observal API or an API role.

​
Command summary

​
Embedded lifecycle

Start in the foreground:
Start for automation:
JSON start and restart require --background because foreground mode remains attached until shutdown.
start accepts --port/-p and --host. When the default API port is occupied, it tries the documented local fallback ports and reports the selected port. An explicitly selected occupied port is a conflict. Background start and restart verify all four final service states before returning success; stop verifies that none remains running. Their JSON results include the verified services list, and an unverified transition exits with code 9 plus observed state in error.result. Startup performs these steps in order:
  1. Installs embedded dependencies when missing. Downloads require a published SHA-256 checksum and archives reject links and path traversal.
  2. Starts PostgreSQL, ClickHouse, and Redis.
  3. Applies PostgreSQL and ClickHouse migrations. Migration failures stop startup; the CLI never stamps a failed PostgreSQL schema as current.
  4. Starts the API.
  5. Bootstraps a local admin only on a fresh embedded server and persists the real access and refresh tokens. It never writes placeholder credentials or an API key.
  6. Attempts telemetry hook installation. Optional hook failures are explicit warnings.

​
Status and configuration

Status is a finite diagnosis command. It exits successfully when checks run, including when healthy is false.
Configuration output contains paths and ports only. It never returns generated secrets.

​
Logs

Read a bounded snapshot:
Follow one service as JSON Lines:
JSON follow requires one service so every event has an unambiguous service field. Valid services are postgres, clickhouse, redis, and api.

​
Install and reset

Reset deletes embedded database directories and the generated server secret. It does not delete CLI configuration, downloaded binaries, logs, or unrelated files. Human mode confirms. JSON mode requires --force:
Deletion is confined to the managed embedded data directory.

​
Docker upgrade

Preview an upgrade:
Apply one non-interactively:
An upgrade validates the target version and image, acquires the server upgrade lock, creates a managed PostgreSQL backup unless --skip-backup is set, pulls images, atomically updates OBSERVAL_VERSION, recreates containers, and runs the configured health check. A failed health check requests the previous image version again and returns an unavailable error. JSON mutation requires --force; dry run does not.

​
Docker rollback

Rollback accepts only backup directories under the managed backup root. It restores PostgreSQL, atomically restores the image version, recreates containers, and checks health. ClickHouse telemetry is not restored by this command. JSON and human results state clickhouse_restored: false. Use observal server migrate for ClickHouse export and import.

​
Docker versions

The result distinguishes the current version, available GHCR images, and local PostgreSQL backups. Failure to query GHCR is reported as unavailable rather than as an empty registry.

​
Error and output contract

All finite commands accept --output table|json. JSON success writes one document to stdout. Failures leave stdout empty and write one categorized error to stderr. Log following is the only JSON Lines stream.