Installation & local state
The installation identity, SQLite journal and state directory form the basis of recovery.
One installation, one state directory
init creates an installation UUID and migration-managed SQLite state. The default is %LOCALAPPDATA%\coldctl\data on Windows, ~/Library/Application Support/com.coldctl.coldctl on macOS, or $XDG_DATA_HOME/coldctl (otherwise ~/.local/share/coldctl) on Linux. Use --data-dir PATH globally for isolation. status is read-only.
coldctl --data-dir ./test-state init
coldctl --data-dir ./test-state statusPreserve the recovery set
Keep the state directory, archive files and referenced staging files together. Per-job and per-policy OS locks coordinate workers sharing this state. Do not delete lock files while processes run, use copied state concurrently against the same archive, or mix old and new binaries.
Back up safely
state backup uses the SQLite backup API and includes committed WAL changes. It excludes archive files and environment credentials. For a consistent state-and-files set, stop all writers, create the backup and copy destination files while they remain stopped. Restore a trusted backup into a fresh empty state directory, not over a live database.
coldctl state backup --to ./backups/state.db --output jsonUpgrades and service accounts
The current local schema is version 17, including remote destinations and recurring schedules. Stop workers and run coldctl init before using new commands. Preserve state backups and remote archive objects. A service must use the same --data-dir, connector installation, identity or environment credentials, and storage permissions as the operator. Scheduling coordinates one machine, not a distributed fleet.