Command-line interface

The cairndb command runs CairnDB’s maintenance jobs. Install it with the cli extra (pip install "cairndb[cli]"). It reads storage settings from the CAIRNDB_* environment variables. It loads application code (handler registries, schema initializers) from module:attribute references, so your package must be importable, for example installed in the same environment or on PYTHONPATH.

Every command operates on one log: the root log, or the named log given by --log or CAIRNDB_LOG (see Operations → Named logs). The output is structured JSON logs followed by a one-line summary. The exit status is non-zero on failure.

CairnDB jobs: snapshots, garbage collection, projection rebuild

cairndb snapshot

Build a snapshot by replaying the commit log, and upload it.

cairndb snapshot [OPTIONS]

Option	Type	Default	Description
--handlers	str	required	HandlerRegistry reference, e.g. ‘myapp.projections:registry’
--init-schema	str		Schema initializer reference (async callable taking a db path)
--schema-version	str	1	Projection schema version (snapshots/v{version}/ prefix); must equal the projection’s version
--end-at	int		Last commit to include (point-in-time snapshot)
--log	str		Named log to operate on (logs/{name}/); the root log when omitted

cairndb gc

Apply retention policy to snapshots (and optionally the log).

cairndb gc [OPTIONS]

Option	Type	Default	Description
--schema-version	str	1	Projection schema version
--keep-snapshots	int range	3	Snapshots to keep
--prune-log	flag		Also delete commits covered by the oldest kept snapshot (destroys replayable history before it!)
--log	str		Named log to operate on (logs/{name}/); the root log when omitted

cairndb rebuild

Rebuild the local projection from the ledger (debug/ops). Client settings (db path, storage) come from CAIRNDB_* env vars.

cairndb rebuild [OPTIONS]

Option	Type	Default	Description
--handlers	str	required	HandlerRegistry reference, e.g. ‘myapp.projections:registry’
--init-schema	str		Schema initializer reference
--log	str		Named log to operate on (logs/{name}/); the root log when omitted