CLI reference

ogcat is the command-line interface.

Commands

ogcat init

Create a new catalog.

ogcat init <root> [--name NAME]

ogcat add

Ingest a file into a catalog.

ogcat add <file> --catalog <root> [--meta KEY=VALUE ...] [--operation copy|move]

If an add operation fails after an operation id has been created, the error message includes operation_id: ... so it can be correlated with ogcat logs --operation.

ogcat logs

Inspect catalog-local audit events.

ogcat logs --catalog <root> [--user USER] [--operation OPERATION_ID] [--record RECORD_ID] [--level LEVEL] [--event-type TYPE] [--limit N] [--json]

Audit events are stored as JSON Lines under <catalog-root>/.ogcat/logs/events.jsonl. Use --json for full structured events, or omit it for a compact table with timestamp, level, event type, operation id, record id, and message.

Examples:

ogcat logs --catalog <root> --level error
ogcat logs --catalog <root> --user alice --json
ogcat logs --catalog <root> --operation "$operation_id"

ogcat search

Search catalog records.

ogcat search --catalog <root> [FILTER ...] [OPTIONS]

Positional filter syntax

Syntax	Meaning
field=value	Exact equality
field:value	Contains / list membership
field~pattern	Glob or substring match
field?	Field exists
!field?	Field is missing

Output options

Flag	Behaviour
--json	Print full matching records as JSON
--ids	Print record ids only
--paths	Print stored paths only
--fields a,b,c	Choose displayed columns
--format table|plain|csv|tsv|pipe	Table format
--limit N	Cap on displayed results
--all	Show every match (no cap)
--include-deleted	Include tombstoned records
--only-deleted	Show only tombstoned records

--include-deleted and --only-deleted are mutually exclusive. Lifecycle fields such as status and lifecycle_metadata are reserved top-level search fields; use user_metadata.status for a domain metadata key named status.

Compatibility flags (also available): --where, --contains, --match, --regex, --exists, --missing, --ignore-case

Use --ids when piping search results into ID-based commands:

record_id=$(ogcat search --catalog <root> species=CO2 --ids --limit 1)
ogcat show "$record_id" --catalog <root>
ogcat path "$record_id" --catalog <root>

ogcat show

Print a single record.

ogcat show <id> --catalog <root>

show resolves records by id and can inspect tombstoned records.

ogcat path

Print the stored path of a record.

ogcat path <id> --catalog <root>

ogcat delete

Tombstone a record. Tombstoned records are hidden from normal search but remain inspectable by id and can be restored or purged.

ogcat delete <id> --catalog <root> [--reason TEXT] [--json]

ogcat restore

Restore a tombstoned record to normal search visibility.

ogcat restore <id> --catalog <root> [--reason TEXT] [--json]

ogcat purge

Permanently remove a tombstoned record and any managed catalog-local path-backed artifacts. External references and user-owned paths are skipped and audited. Purging an active record requires --force. The command always requires --yes because the operation is irreversible. If cleanup is incomplete, the command exits non-zero and leaves the tombstoned record with purge outcome metadata.

ogcat purge <id> --catalog <root> --yes [--force] [--json]

ogcat info

Print catalog statistics.

ogcat info --catalog <root>

ogcat fields

Print schema-declared metadata fields from the catalog spec, or inspect fields found in stored records.

ogcat fields --catalog <root> [--record-type TYPE] [--stored] [--values FIELD] [--json]

--stored lists field paths currently present in records, including nested metadata paths such as user_metadata.site.code. --values FIELD prints unique scalar values for one field.

ogcat spec

Update small, safe parts of catalog.json.

ogcat spec show-schema [TYPE] --catalog <root> [--json]
ogcat spec add-schema NAME --catalog <root> --schema-json JSON_OR_PATH [--overwrite]
ogcat spec set-default-schema NAME --catalog <root>
ogcat spec set FIELD=VALUE ... --catalog <root>

ogcat spec show-schema --json prints the full serialisable schema, including display_fields when configured.

ogcat spec set supports simple fields such as catalog_name, default_operation, and field_resolution_order. Storage root changes are rejected because they require a dedicated migration operation.