CLI Reference

This page is generated from the live Click command tree. Use firecube <command> --help for the same information in your terminal.

firecube

batch ingestion tool for EO datasets

Batch ingestion and management tool for Earth Observation datasets. Writes Zarr and Parquet stores with built-in resume safety, idempotent chunk tracking, and multi-resolution support. Run firecube ingest to start a job, or explore subcommands for storage management and diagnostics.

Usage:

firecube [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--version`	boolean	Show the version and exit.	`False`
`--config-file`	path	Firecube TOML config file (default: ~/.config/firecube/config.toml)	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube advise

performance advice helpers

Read-only helpers for configuring ingestion. Use advise batch-size to get a recommended pipeline_batch_size before running large ingestion jobs.

Usage:

firecube advise [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube advise batch-size

recommend optimal batch size

Recommends an optimal pipeline_batch_size based on the Zarr store's time chunk shape. Reads the store metadata to compute how many time steps fit into memory without partial chunks. Run before a long ingestion job to set --option pipeline_batch_size=N.

Usage:

firecube advise batch-size [OPTIONS]

Options:

Name	Type	Description	Default
`-p`, `--product`	text	Firecube product URI (file:///abs/path or s3://bucket/key); storage flags inferred from URI scheme.	`Sentinel.UNSET`
`-g`, `--group`	text	group path inside the product (e.g. F024/FWI)	`Sentinel.UNSET`
`--storage-driver`	choice (`fsspec` \| `obstore`)	Storage backend driver.	`Sentinel.UNSET`
`--storage-type`	choice (`local` \| `s3`)	Storage locality/class.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube advise compliance

run structural compliance checks

Opens a Zarr cube and runs the selected compliance profile. Findings are emitted as human-readable text (default) or as JSON. Exit codes: 0 on clean (or warnings/info without --strict), 1 if any error finding is reported, 2 if warnings/info appear under --strict.

Usage:

firecube advise compliance [OPTIONS]

Options:

Name	Type	Description	Default
`--profile`	choice (`cf-18`)	compliance profile to run	`Sentinel.UNSET`
`-p`, `--product`	text	Firecube product URI (file:///abs/path or s3://bucket/key); storage flags inferred from URI scheme.	`Sentinel.UNSET`
`-g`, `--group`	text	group path inside the cube ('.' or '/' for root, otherwise e.g. F024/FWI)	`Sentinel.UNSET`
`--format`	choice (`text` \| `json`)	output format for the report	`text`
`--strict`	boolean	treat any warning or info finding as a non-zero exit (code 2)	`False`
`--storage-driver`	choice (`fsspec` \| `obstore`)	Storage backend driver.	`Sentinel.UNSET`
`--storage-type`	choice (`local` \| `s3`)	Storage locality/class.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube archive

create and manage Tensogram archives

Archives compress all array groups from a Zarr store into a single portable file using configurable codecs. Use archive create to produce an archive and archive restore to extract it back to Zarr.

Usage:

firecube archive [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube archive create

convert a Zarr store to a .tgm archive

reads all selected array groups, encodes them with the chosen codec (default: zstd), and writes a single portable .tgm file. use --start-date and --end-date to archive a specific time window, or --group to select one product group.

Usage:

firecube archive create [OPTIONS]

Options:

Name	Type	Description	Default
`-s`, `--source`	text	Zarr store URI (file:///abs/path or s3://bucket/key)	`Sentinel.UNSET`
`-a`, `--archive`	text	Target archive URI; runtime decides what is supported (file:///abs/path or s3://bucket/key).	`Sentinel.UNSET`
`--storage-type`	choice (`local` \| `s3`)	N/A	`Sentinel.UNSET`
`--storage-driver`	choice (`fsspec` \| `obstore`)	N/A	`Sentinel.UNSET`
`--start-date`	text	ISO 8601 start date for time range filter	None
`--end-date`	text	ISO 8601 end date for time range filter	None
`-g`, `--group`	text	product group to archive (e.g. F024, NORDLIS)	None
`--variables`	text	comma-separated variable names to include	None
`--compression`	choice (`blosc2` \| `szip` \| `zstd` \| `lz4` \| `zfp` \| `sz3`)	compression codec for .tgm encoding (default: zstd)	None
`--overwrite`	boolean	overwrite existing target file	`False`
`--allow-nan` / `--no-allow-nan`	boolean	allow NaN values in archive (default: true)	None
`--allow-inf` / `--no-allow-inf`	boolean	allow Inf values in archive (default: true)	None
`--dry-run`	boolean	Show what would happen without making any changes.	`False`
`--yes-i-really-mean-it`	boolean	Skip confirmation prompts. Required for destructive operations in non-TTY.	`False`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube archive info

show metadata for a .tgm archive

reads the archive header to display variable names, dimension sizes, codec, and time coverage. no data is decoded or written; suitable for quick inspection.

Usage:

firecube archive info [OPTIONS]

Options:

Name	Type	Description	Default
`-a`, `--archive`	text	Archive URI to inspect (file:///abs/path or s3://bucket/key).	`Sentinel.UNSET`
`-f`, `--format`	choice (`table` \| `json` \| `csv`)	Output format.	`table`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube archive list

list contents of a .tgm archive

displays per-variable group entries including name, dimensions, and time range. no data is decoded; useful for reviewing archive contents before restoring.

Usage:

firecube archive list [OPTIONS]

Options:

Name	Type	Description	Default
`-a`, `--archive`	text	Archive URI to inspect (file:///abs/path or s3://bucket/key).	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube archive restore

restore a .tgm archive to a Zarr store

decodes all encoded array groups from the .tgm file and writes them back to the target Zarr store. archive groups restore to their original paths.

Usage:

firecube archive restore [OPTIONS]

Options:

Name	Type	Description	Default
`-a`, `--archive`	text	Target archive URI; runtime decides what is supported (file:///abs/path or s3://bucket/key).	`Sentinel.UNSET`
`-t`, `--target`	text	Target Firecube product URI; --storage-type must match URI scheme.	`Sentinel.UNSET`
`--storage-type`	choice (`local` \| `s3`)	N/A	`Sentinel.UNSET`
`--storage-driver`	choice (`fsspec` \| `obstore`)	N/A	`Sentinel.UNSET`
`--overwrite`	boolean	overwrite existing Zarr store	`False`
`--dry-run`	boolean	Show what would happen without making any changes.	`False`
`--yes-i-really-mean-it`	boolean	Skip confirmation prompts. Required for destructive operations in non-TTY.	`False`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube archive validate

check integrity of a .tgm archive

reads the archive header and validates internal structure without fully decoding data. exits with code 0 if the archive is valid, code 1 if it is corrupted or incomplete.

Usage:

firecube archive validate [OPTIONS]

Options:

Name	Type	Description	Default
`-a`, `--archive`	text	Archive URI to inspect (file:///abs/path or s3://bucket/key).	`Sentinel.UNSET`
`--quick`	boolean	structure-only check (no hash verification)	`False`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube catalog

generate Intake YAML catalogs

Generate Intake YAML catalogs for Firecube products. Use catalog intake to produce a machine-readable catalog that describes a product's storage layout, groups, and storage options for use with the Intake data discovery library.

Usage:

firecube catalog [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube catalog intake

generate an Intake product catalog

Generates an Intake YAML catalog for a supported product store. Discovers dataset groups using the specified plugin and writes a catalog file with source specs and optional storage_options placeholders. Requires --product, --output, and --collection-id.

Usage:

firecube catalog intake [OPTIONS] PLUGIN

Options:

Name	Type	Description	Default
`-p`, `--product`	text	Firecube product URI (file:///abs/path or s3://bucket/key); storage flags inferred from URI scheme.	`Sentinel.UNSET`
`-o`, `--output`	text	Output artifact URI (file:///abs/path); s3:// accepted but runtime support coming later	`Sentinel.UNSET`
`--collection-id`	text	explicit collection id for the generated catalog	`Sentinel.UNSET`
`--include-storage-options` / `--no-storage-options`	boolean	include generic storage_options using FIRECUBE_* placeholders	`True`
`--storage-driver`	choice (`fsspec` \| `obstore`)	Storage backend driver.	`Sentinel.UNSET`
`--storage-type`	choice (`local` \| `s3`)	Storage locality/class.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube chunks

inspect and manage chunk records

Inspect and manage tracked chunk records across all products.

firecube tracks chunk state in a product-local control plane (event log, snapshots, claims). use chunks list to inspect, chunks delete to remove storage and records, and chunks runs to review ingestion run history

Usage:

firecube chunks [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--workspace`	path	local workspace directory to use	`Sentinel.UNSET`
`--quiet`	boolean	Suppress storage configuration banner.	`False`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube chunks claims

manage write-coordination claims

inspect and manage chunk write claims.

Usage:

firecube chunks claims [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube chunks claims clear

clear a blocking write claim

clear a blocking write-coordination claim for a product and domain. claims are normally released when a writer exits cleanly; use this when a crashed process left a stale claim that blocks ingestion. verify the original writer is no longer running first.

--force bypasses the is_stale check (operational bypass for active claims). --yes-i-really-mean-it is the confirmation flag, required in non-TTY contexts.

Usage:

firecube chunks claims clear [OPTIONS]

Options:

Name	Type	Description	Default
`-n`, `--product-name`	text	product owning the claim	`Sentinel.UNSET`
`--domain`	text	full write-domain identifier	`Sentinel.UNSET`
`--all-stale`	boolean	clear all stale claims for the product (mutually exclusive with --domain)	`False`
`--workspace`	path	workspace directory override	`Sentinel.UNSET`
`--force`	boolean	operational bypass: clear even if the claim is still active (skips is_stale check)	`False`
`--dry-run`	boolean	Show what would happen without making any changes.	`False`
`--yes-i-really-mean-it`	boolean	Skip confirmation prompts. Required for destructive operations in non-TTY.	`False`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube chunks claims list

list active write claims

list active write-coordination claims for one or all products. claims are short-lived locks written to .firecube/claims/ to coordinate concurrent writes. stale claims from crashed processes can block ingestion -- use claims clear to release them

Usage:

firecube chunks claims list [OPTIONS]

Options:

Name	Type	Description	Default
`-n`, `--product-name`	text	filter by product name	`Sentinel.UNSET`
`--workspace`	path	workspace directory override	`Sentinel.UNSET`
`-f`, `--format`	choice (`table` \| `json`)	output format	`table`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube chunks delete

delete chunks and storage data

delete chunk records and storage data tracked in the .firecube/ control plane. CAUTION: this operation is destructive and cannot be undone -- it removes both control-plane records and the underlying storage files. use --dry-run to preview deletions before committing

Usage:

firecube chunks delete [OPTIONS]

Options:

Name	Type	Description	Default
`--pattern`	text	glob pattern to match chunk keys (can specify multiple)	`Sentinel.UNSET`
`-n`, `--product-name`	text	Filter by product name.	`Sentinel.UNSET`
`--all-products`	boolean	Apply to all products (mutually exclusive with --product-name).	`False`
`--end-date`	text	delete chunks created before date (YYYY-MM-DD)	`Sentinel.UNSET`
`--start-date`	text	delete chunks created after date (YYYY-MM-DD)	`Sentinel.UNSET`
`--range`	text	delete chunks in date range (YYYY-MM-DD,YYYY-MM-DD)	`Sentinel.UNSET`
`--type`	text	filter by chunk type (chunk, meta)	`Sentinel.UNSET`
`--meta`	text	filter by tracked chunk metadata key=value (value may be JSON)	`Sentinel.UNSET`
`--workspace`	path	workspace directory override	`Sentinel.UNSET`
`--manifest-only`	boolean	remove tracked chunk records only, keep storage files	`False`
`--storage-only`	boolean	delete from storage only, keep tracked chunk records	`False`
`--yes-i-really-mean-it`	boolean	skip confirmation prompts	`False`
`--dry-run`	boolean	show what would be deleted without doing it	`False`
`--include-metadata`	boolean	include metadata chunks (zarr.json, etc.) - DANGEROUS!	`False`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube chunks delete-span

delete storage chunks from a span

delete storage chunks described by specific tracked span records. removes data written as part of a particular ingestion span or run. CAUTION: data removed from storage cannot be recovered -- use --dry-run first

Usage:

firecube chunks delete-span [OPTIONS]

Options:

Name	Type	Description	Default
`-n`, `--product-name`	text	target product (e.g. product.zarr)	`Sentinel.UNSET`
`--run-id`	text	filter span records by run_id	`Sentinel.UNSET`
`--batch-id`	text	filter span records by batch_id	`Sentinel.UNSET`
`-g`, `--group`	text	filter by group (e.g. F120)	`Sentinel.UNSET`
`--meta`	text	filter by tracked span metadata key=value (value may be JSON)	`Sentinel.UNSET`
`--include-replaced`	boolean	include spans already marked replaced (useful to retry deletions after a partial failure)	`False`
`--workspace`	path	workspace directory override	`Sentinel.UNSET`
`--time-dim`	text	time dimension name for cubes written with a custom time_dim_name; only needed when span records predate dim recording and the cube has no timestamp-state array (must match the cube layout)	`Sentinel.UNSET`
`--dry-run`	boolean	show what would be deleted without doing it	`False`
`--force`	boolean	allow deletion even when spans are not chunk-aligned	`False`
`--yes-i-really-mean-it`	boolean	skip confirmation prompts	`False`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube chunks list

list tracked chunk records

list chunk records tracked in the .firecube/ control plane for one or all products. filter by product, date range, span, or chunk type. supports table and JSON output for scripting

Usage:

firecube chunks list [OPTIONS]

Options:

Name	Type	Description	Default
`--pattern`	text	glob pattern to match chunk keys (can specify multiple)	`Sentinel.UNSET`
`-n`, `--product-name`	text	filter by product name	`Sentinel.UNSET`
`--end-date`	text	show chunks created before date (YYYY-MM-DD)	`Sentinel.UNSET`
`--start-date`	text	show chunks created after date (YYYY-MM-DD)	`Sentinel.UNSET`
`--time-range`	text	filter spans by time range START:END (ISO8601); matches spans overlapping the window	None
`--type`	text	filter by chunk type (chunk, meta)	`Sentinel.UNSET`
`--meta`	text	filter by tracked chunk metadata key=value (value may be JSON)	`Sentinel.UNSET`
`--workspace`	path	workspace directory override (local path)	`Sentinel.UNSET`
`-f`, `--format`	choice (`table` \| `json` \| `csv`)	output format	`table`
`--limit`	integer	limit number of results	`Sentinel.UNSET`
`--include-span`	boolean	include span coverage payload (time_index_ranges, arrays, alignment) in output	`False`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube chunks runs

manage ingestion run records

inspect and manage tracked chunk runs.

Usage:

firecube chunks runs [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube chunks runs abandon

mark a stuck run as abandoned

mark a non-terminal ingestion run as abandoned to unblock resume. a run stuck in 'started' state blocks future ingestion for that product. use this after confirming the original process is no longer active

Usage:

firecube chunks runs abandon [OPTIONS]

Options:

Name	Type	Description	Default
`-n`, `--product-name`	text	product owning the run	`Sentinel.UNSET`
`--target`	text	Explicit product target URI (file://... or s3://...). Overrides config/env backend resolution. Use when --product-name alone resolves to the wrong backend (e.g. after moving a product or when config points elsewhere).	None
`--run-id`	text	run identifier (mutually exclusive with --all-stale)	None
`--all-stale`	boolean	abandon all stale non-terminal runs for the product (mutually exclusive with --run-id)	`False`
`--reason`	text	operator reason for abandonment	`Sentinel.UNSET`
`--workspace`	path	workspace directory override	`Sentinel.UNSET`
`--dry-run`	boolean	Show what would happen without making any changes.	`False`
`--yes-i-really-mean-it`	boolean	Skip confirmation prompts. Required for destructive operations in non-TTY.	`False`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube chunks runs list

list tracked ingestion runs

list tracked ingestion runs for a product from the .firecube/ control plane. shows run status (started, complete, failed, abandoned), timestamps, and span counts. use to identify stuck or failed runs before abandoning

Usage:

firecube chunks runs list [OPTIONS]

Options:

Name	Type	Description	Default
`-n`, `--product-name`	text	product to inspect	`Sentinel.UNSET`
`--target`	text	Explicit product target URI (file://... or s3://...). Overrides config/env backend resolution. Use when --product-name alone resolves to the wrong backend (e.g. after moving a product or when config points elsewhere).	None
`--status`	text	filter runs by status (started, complete, failed, abandoned)	None
`--workspace`	path	workspace directory override	`Sentinel.UNSET`
`-f`, `--format`	choice (`table` \| `json`)	output format	`table`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube chunks snapshots

manage control-plane snapshots

rebuild derived chunk snapshots.

Usage:

firecube chunks snapshots [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube chunks snapshots rebuild

rebuild the chunk snapshot

rebuild the derived chunk snapshot for a product from the chunk event log. snapshots are cached read models; use after the snapshot is missing, corrupt, or very stale to restore fast query performance for chunks list

Usage:

firecube chunks snapshots rebuild [OPTIONS]

Options:

Name	Type	Description	Default
`-n`, `--product-name`	text	product to rebuild into a fresh chunk snapshot	`Sentinel.UNSET`
`--workspace`	path	workspace directory override	`Sentinel.UNSET`
`-f`, `--format`	choice (`table` \| `json`)	output format	`table`
`--dry-run`	boolean	Show what would happen without making any changes.	`False`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube chunks snapshots status

show snapshot age and status

show snapshot age and status for a product's .firecube/ control plane. reports whether the snapshot exists, how many events it covers, and when it was last rebuilt. use to decide whether a rebuild is needed

Usage:

firecube chunks snapshots status [OPTIONS]

Options:

Name	Type	Description	Default
`-n`, `--product-name`	text	product to check snapshot status for	`Sentinel.UNSET`
`--workspace`	path	workspace directory override	`Sentinel.UNSET`
`-f`, `--format`	choice (`table` \| `json`)	output format	`table`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube completion

generate shell completion scripts

Generates a shell completion script for firecube for bash, zsh, or fish. Run the output through eval in your shell profile to enable tab completion for all firecube commands and options.

Usage:

firecube completion [OPTIONS] {bash|zsh|fish}

Options:

Name	Type	Description	Default
`--output`	path	write the completion script to a file instead of stdout	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube ingest

run an ingestion job for a plugin

The plugin handles source reading; firecube manages write strategy (staged or direct), pipeline parallelism, and chunk tracking. Use --option to pass plugin-specific overrides, or --show-options to list available options for a plugin.

Usage:

firecube ingest [OPTIONS] PLUGIN

Options:

Name	Type	Description	Default
`-i`, `--input-data`	text	Raw plugin input data: local path, file:///abs/path, or s3:// prefix. Interpreted by the plugin.	`Sentinel.UNSET`
`-t`, `--target`	text	Target product URI required (file:///abs/path or s3://bucket/key); -t short available.	`Sentinel.UNSET`
`-n`, `--product-name`	text	Logical product name. Overrides the plugin class default and the per-plugin config default.	None
`--output-format`	text	output format to deliver (e.g. parquet, zarr)	`Sentinel.UNSET`
`--storage-type`	choice (`local` \| `s3`)	Storage locality/class. Inferred from URI scheme when omitted (file://→local, s3://→s3). Explicit value overrides inference and is rejected on mismatch.	`Sentinel.UNSET`
`--storage-driver`	choice (`fsspec` \| `obstore`)	Storage backend driver. Defaults to fsspec; overridable via FIRECUBE_STORAGE_DRIVER or [storage].driver.	`Sentinel.UNSET`
`-w`, `--write-mode`	choice (`staged` \| `direct`)	Write strategy (staged=workspace-first, direct=stream to target). Required. No local-target inference.	`Sentinel.UNSET`
`--slot-start`	integer	Parallel ingestion: first slot index (inclusive).	None
`--slot-end`	integer	Parallel ingestion: last slot index (exclusive).	None
`--slot-size`	integer	Slot size for orchestrated parallel ingestion range derivation.	None
`--slot-group`	text	Group name this worker owns when running multi-group parallel ingestion. Only workers with matching group are scheduled writes for that group. Defaults to None (all groups — single-group or non-parallel mode).	None
`--in-memory`	boolean	use in-memory DuckDB	`False`
`--option`	TYPED_OPTION	Plugin/engine option in key=value form.	`Sentinel.UNSET`
`--show-options`	boolean	show available options for the specified plugin and exit	`False`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube parquet

validate and consolidate Parquet datasets

Validation and consolidation of Parquet datasets. Use parquet validate to check file integrity and parquet consolidate to merge scattered files into a single optimized file.

Usage:

firecube parquet [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube parquet consolidate

merge Parquet files into one

Merges a scattered Parquet dataset into a single optimized file using DuckDB. Reads all .parquet files under the product path and writes a single consolidated file with the specified codec. The source dataset is not modified.

Usage:

firecube parquet consolidate [OPTIONS]

Options:

Name	Type	Description	Default
`-p`, `--product`	text	Firecube product URI (file:///abs/path or s3://bucket/key); storage flags inferred from URI scheme.	`Sentinel.UNSET`
`-o`, `--output`	text	Output artifact URI (file:///abs/path); s3:// accepted but runtime support coming later	`Sentinel.UNSET`
`--codec`	text	compression codec (default: zstd)	`zstd`
`--storage-type`	choice (`local` \| `s3`)	Storage locality/class.	`Sentinel.UNSET`
`--storage-driver`	choice (`fsspec` \| `obstore`)	Storage backend driver.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube parquet validate

validate Parquet files

Checks PAR1 magic bytes at head and tail. Scans all .parquet files under the product path and reports any missing or corrupt files. Read-only; does not modify any data.

Usage:

firecube parquet validate [OPTIONS]

Options:

Name	Type	Description	Default
`-p`, `--product`	text	Firecube product URI (file:///abs/path or s3://bucket/key); storage flags inferred from URI scheme.	`Sentinel.UNSET`
`--storage-type`	choice (`local` \| `s3`)	Storage locality/class.	`Sentinel.UNSET`
`--storage-driver`	choice (`fsspec` \| `obstore`)	Storage backend driver.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube plugins

inspect installed ingestion plugins

Plugins are discovered via Python entry points (firecube.plugins); use plugins list to see what is installed and plugins describe to explore a plugin's options.

Usage:

firecube plugins [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube plugins create

create a new plugin project structure

Usage:

firecube plugins create [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--target-dir`	path	target directory (default: current directory)	`/home/armagan/projects/opensource/firecube`
`--author`	text	author name	`Sentinel.UNSET`
`--email`	text	author email	`Sentinel.UNSET`
`--license`	text	license type (e.g. MIT, Apache-2.0)	`Sentinel.UNSET`
`--template`	choice (`base` \| `zarr` \| `parquet`)	ingestor template to use	`Sentinel.UNSET`
`--write-strategy`	choice (`xarray` \| `zarr-python`)	Zarr write strategy: 'xarray' (default, append-based) or 'zarr-python' (direct region writes)	`Sentinel.UNSET`
`--non-interactive`	boolean	do not ask interactive questions	`False`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube plugins describe

show metadata and config for a plugin

Displays all available ingestion options with their types, defaults, and descriptions. Useful for discovering what --option keys are accepted by firecube ingest.

Usage:

firecube plugins describe [OPTIONS] PLUGIN

Options:

Name	Type	Description	Default
`-f`, `--format`	choice (`table` \| `json` \| `csv`)	N/A	`table`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube plugins explain

explain a specific config option

Explains a config option for a plugin by its dotted path. Shows type, default, description, and allowed values for a single option field. The path format is .. (e.g. example_plugin.ingest.option).

Usage:

firecube plugins explain [OPTIONS] PATH

Options:

Name	Type	Description	Default
`-f`, `--format`	choice (`table` \| `json` \| `csv`)	N/A	`table`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube plugins install

install plugin packages

This is a wrapper around 'uv pip install'.

PACKAGE SPECIFIERS (passed through to uv pip install) - Distribution name: firecube-example-plugin - Local path (directory, wheel, or sdist): /path/to/firecube-example-plugin ./dist/firecube_example_plugin-0.1.0-py3-none-any.whl - Git URL (https or ssh): git+https://example.com/org/firecube-example-plugin.git git+ssh://git@example.com/org/firecube-example-plugin.git

EXAMPLES - Install from index: firecube plugins install firecube-example-plugin - Install from a local checkout: firecube plugins install /path/to/firecube-example-plugin - Install from git: firecube plugins install git+ssh://git@example.com/org/firecube-example-plugin.git - Editable install (local or VCS): firecube plugins install --editable /path/to/firecube-example-plugin

Usage:

firecube plugins install [OPTIONS] PACKAGES...

Options:

Name	Type	Description	Default
`-e`, `--editable`	boolean	install in editable mode (equivalent to 'uv pip install -e ...')	`False`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube plugins list

list all registered plugins

Lists all registered ingestion plugins discovered via entry points. Shows plugin name, module path, and a short description for each installed plugin. Use -f to control output format.

Usage:

firecube plugins list [OPTIONS]

Options:

Name	Type	Description	Default
`-f`, `--format`	choice (`table` \| `json` \| `csv`)	N/A	`table`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube plugins uninstall

uninstall a plugin

Resolves the plugin name to its distribution package and uninstalls it.

Usage:

firecube plugins uninstall [OPTIONS] PLUGIN

Options:

Name	Type	Description	Default
`--dist`	text	bypass resolution and uninstall this distribution package directly	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube zarr

Manage Zarr products

Validate, build multi-resolution pyramids, pre-allocate arrays for parallel ingestion, and plan chunk-aligned slot ranges. Use zarr validate to check structural consistency, zarr multires to build downsampled layers, and zarr slots to emit parallel ingestion plans.

Usage:

firecube zarr [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube zarr multires

Build multi-resolution Zarr pyramid for an existing product.

Usage:

firecube zarr multires [OPTIONS]

Options:

Name	Type	Description	Default
`-t`, `--target`	text	Target product URI required (file:///abs/path or s3://bucket/key); scheme must match --storage-type.	`Sentinel.UNSET`
`--resolutions`, `-r`	float	Resolution levels to build (repeatable, e.g. -r 1.0 -r 0.5).	`Sentinel.UNSET`
`--product-name`	text	Logical product name.	`Sentinel.UNSET`
`--storage-type`	choice (`local` \| `s3`)	Storage locality/class. Inferred from URI scheme when omitted (file://→local, s3://→s3).	`Sentinel.UNSET`
`--storage-driver`	choice (`fsspec` \| `obstore`)	Storage backend driver.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube zarr preallocate

Pre-allocate Zarr arrays for parallel ingestion.

Idempotent: if arrays already exist with matching shape, dtype, and chunks, this command is a no-op. If arrays exist with mismatched schema, exits non-zero with a diff showing expected vs found values. Safe to re-run.

Usage:

firecube zarr preallocate [OPTIONS] PLUGIN

Options:

Name	Type	Description	Default
`--target`	text	Target product URI required (file:///abs/path or s3://bucket/key).	`Sentinel.UNSET`
`--product-name`	text	Logical product name.	`Sentinel.UNSET`
`--storage-type`	choice (`local` \| `s3`)	Storage locality. Inferred from URI scheme when omitted (file://→local, s3://→s3).	`Sentinel.UNSET`
`--storage-driver`	choice (`fsspec` \| `obstore`)	N/A	`Sentinel.UNSET`
`-w`, `--write-mode`	choice (`staged` \| `direct`)	N/A	`Sentinel.UNSET`
`-i`, `--input-data`	text	Raw plugin input data: local path, file:///abs/path, or s3:// prefix. Interpreted by the plugin.	None
`--option`	TYPED_OPTION	Plugin/engine option in key=value form.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube zarr slots

Emit chunk-aligned slot ranges for orchestrated parallel ingestion.

Read-only: does NOT mutate target storage or tracking state. JSON output is Argo withItems / Kubeflow ParallelFor compatible.

Usage:

firecube zarr slots [OPTIONS] PLUGIN

Options:

Name	Type	Description	Default
`--target`	text	Target product URI required (file:///abs/path or s3://bucket/key).	`Sentinel.UNSET`
`--product-name`	text	Logical product name.	`Sentinel.UNSET`
`--storage-type`	choice (`local` \| `s3`)	Storage locality/class. Inferred from URI scheme when omitted (file://→local, s3://→s3).	`Sentinel.UNSET`
`--storage-driver`	choice (`fsspec` \| `obstore`)	Storage backend driver.	`Sentinel.UNSET`
`-w`, `--write-mode`	choice (`staged` \| `direct`)	Write mode.	`Sentinel.UNSET`
`--slot-size`	integer	Slot partition size (default: chunk_shape[0] of first array of first group).	None
`--no-resume`	boolean	Disable resume-aware narrowing; emit full [0, total_slots) ranges.	`False`
`-f`, `--format`	choice (`table` \| `json` \| `csv`)	Output format.	`json`
`-h`, `--help`	boolean	Show this message and exit.	`False`

firecube zarr validate

validate a Zarr array group

Checks dimension shapes, dtypes, chunk boundaries, and required metadata without modifying any data. Requires --product and --group; exits with a structured JSON summary.

Usage:

firecube zarr validate [OPTIONS]

Options:

Name	Type	Description	Default
`-p`, `--product`	text	Firecube product URI (file:///abs/path or s3://bucket/key); storage flags inferred from URI scheme.	`Sentinel.UNSET`
`-g`, `--group`	text	relative group path inside the product (e.g. F024/FWI)	`Sentinel.UNSET`
`--timeout`	float	wall-clock timeout in seconds for chunk validation	None
`--max-chunks`	integer	maximum number of chunks to process before stopping	None
`--on-timeout`	choice (`warn` \| `fail`)	behavior when budget is exceeded: warn returns partial report, fail raises an error	`warn`
`--storage-driver`	choice (`fsspec` \| `obstore`)	Storage backend driver.	`Sentinel.UNSET`
`--storage-type`	choice (`local` \| `s3`)	Storage locality/class.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`False`

Bulk Sweep: `--all-stale`

Both firecube chunks claims clear and firecube chunks runs abandon support --all-stale for sweeping every stale entry for a product in one command. Use this after a cluster crash or pod eviction leaves multiple stuck runs or claims behind.

Safety gate: `--yes-i-really-mean-it`

Both commands require explicit confirmation before mutating anything. In an interactive terminal you get a prompt. In a non-TTY context (CI, scripts, cron) the command exits with an error unless you pass --yes-i-really-mean-it. This prevents accidental bulk mutations from copy-pasted commands or automation that runs without human review.

--dry-run always works without the confirmation flag. Use it first to see exactly what would change.

`chunks claims clear --all-stale`

Clears every stale write-coordination claim for a product. A claim is considered stale when the writer that created it is no longer active.

--all-stale and --domain are mutually exclusive. Pass one or the other, not both.

Step 1: preview the sweep

firecube chunks claims clear \
  --product-name MY_PRODUCT \
  --all-stale \
  --dry-run

Expected output:

[dry-run] Would clear 3 stale claim(s) for MY_PRODUCT

Step 2: commit the sweep

firecube chunks claims clear \
  --product-name MY_PRODUCT \
  --all-stale \
  --yes-i-really-mean-it

Expected output:

Cleared 3 stale claim(s) for MY_PRODUCT

Verify:

firecube chunks claims list --product-name MY_PRODUCT

Expected output when all claims are gone:

No claims found.

`chunks runs abandon --all-stale`

Marks every non-terminal run for a product as abandoned. A run stuck in started state blocks future ingestion for that product.

--all-stale and --run-id are mutually exclusive. Pass one or the other, not both.

--reason is required even in bulk mode. It records why the runs were abandoned and appears in the run history.

Step 1: preview the sweep

firecube chunks runs abandon \
  --product-name MY_PRODUCT \
  --all-stale \
  --reason "cluster-crash" \
  --dry-run

Expected output:

[dry-run] Would abandon 2 stale run(s) for MY_PRODUCT (reason: cluster-crash)

Step 2: commit the sweep

firecube chunks runs abandon \
  --product-name MY_PRODUCT \
  --all-stale \
  --reason "cluster-crash" \
  --yes-i-really-mean-it

Expected output:

Abandoned 2 stale run(s) for MY_PRODUCT

Verify:

firecube chunks runs list --product-name MY_PRODUCT --status started

Expected output when no stuck runs remain:

No runs found.

Troubleshooting

Symptom	Cause	Fix
`--all-stale and --domain are mutually exclusive`	Both flags passed to `claims clear`	Remove `--domain` when using `--all-stale`
`--all-stale and --run-id are mutually exclusive`	Both flags passed to `runs abandon`	Remove `--run-id` when using `--all-stale`
`--reason is required`	`runs abandon --all-stale` called without `--reason`	Add `--reason "<description>"`
Command exits without mutating in non-TTY	`--yes-i-really-mean-it` not passed	Add `--yes-i-really-mean-it` or run `--dry-run` first
No stale entries found	All claims/runs are already terminal or active	Run `firecube chunks claims list` or `firecube chunks runs list` to inspect current state

CLI Reference

firecube

firecube advise

firecube advise batch-size

firecube advise compliance

firecube archive

firecube archive create

firecube archive info

firecube archive list

firecube archive restore

firecube archive validate

firecube catalog

firecube catalog intake

firecube chunks

firecube chunks claims

firecube chunks claims clear

firecube chunks claims list

firecube chunks delete

firecube chunks delete-span

firecube chunks list

firecube chunks runs

firecube chunks runs abandon

firecube chunks runs list

firecube chunks snapshots

firecube chunks snapshots rebuild

firecube chunks snapshots status

firecube completion

firecube ingest

firecube parquet

firecube parquet consolidate

firecube parquet validate

firecube plugins

firecube plugins create

firecube plugins describe

firecube plugins explain

firecube plugins install

firecube plugins list

firecube plugins uninstall

firecube zarr

firecube zarr multires

firecube zarr preallocate

firecube zarr slots

firecube zarr validate

Bulk Sweep: --all-stale

Safety gate: --yes-i-really-mean-it

chunks claims clear --all-stale

chunks runs abandon --all-stale

Troubleshooting

Bulk Sweep: `--all-stale`

Safety gate: `--yes-i-really-mean-it`

`chunks claims clear --all-stale`

`chunks runs abandon --all-stale`