CLI & output

The euroflood command line mirrors the Python API — every query is also a command. See Tutorial 7 — CLI & configuration for a guided tour; this page is the reference for the output contract, global options, and exit codes, followed by the auto-generated command listing.

Two output streams

EuroFlood keeps stdout and stderr cleanly separated so results are easy to read interactively and easy to parse on a server:

stdout — user-facing results. Query tables, status confirmations, and progress bars are rendered by a rich console. On a non-TTY (a pipe, a file, an HPC job) styling and live progress are dropped automatically, so redirected output stays plain.
stderr — logs. Structured structlog events. On a TTY they render as colored key=value lines; when piped or run on HPC they render as one JSON object per line. Importing euroflood configures no logging at all — the CLI opts in, and library users call euroflood.setup_logging() explicitly.

Global options

These apply to every command and go before the sub-command:

Option	Effect
`-v`, `--verbose`	Log at `DEBUG`; show a full traceback on error (for developers).
`-q`, `--quiet`	Suppress secondary status and progress; the primary result still prints.
`--json`	Emit machine-readable JSON records for `floods`/`hazard` instead of a table.
`--no-color`	Disable ANSI styling (`NO_COLOR` is also honored).

euroflood floods "Zutphen, Netherlands"        # pretty table + summary line
euroflood --json floods "Zutphen, Netherlands" # JSON records to stdout (pipe to jq)
euroflood -q download "Zutphen, Netherlands" -o out/   # just the result, no chatter

Errors & exit codes

Domain errors are rendered as a single clean line with an actionable next step — never a Python traceback:

$ euroflood floods "Zutphn"
Error [GeocodingError] No local boundary match for 'Zutphn'. Did you mean: zutphen?
→ Try a more specific name, or set EUROFLOOD_ALLOW_REMOTE_GEOCODING=1 for online lookup.

Pass -v to restore the traceback. Each error class maps to a distinct exit code so scripts can branch on the failure kind:

Exit	Meaning
`0`	Success
`1`	Generic EuroFlood error
`2`	Missing index / dictionary (build or mirror it first)
`3`	Configuration error
`4`	Geocoding failure (place not found)
`5`	Network / scraping failure
`6`	Hazard tile error
`7`	Cache schema mismatch (rebuild or re-mirror the index)
`8`	Raster processing error

Unexpected (non-EuroFlood) exceptions are never swallowed — they surface with a full traceback so real bugs stay loud.

Command listing

cli

Command Line Interface using Click.

Consumer commands: floods (cheap query, prints/writes a catalogue) and download (search + download + crop). Producer commands: ingest and export.

All user-facing output flows through console (a rich Console on stdout); structlog keeps owning logs on stderr. Domain exceptions are caught by EuroFloodCLI and rendered as a clean one-block message (no traceback) with a per-type exit code; -v/--verbose restores the traceback for developers.

Classes:

Name	Description
`EuroFloodCLI`	A click Group that renders EuroFlood errors cleanly (no traceback).

Functions:

Name	Description
`cli`	EuroFlood: Satellite Flood Map Processing Tool.
`ingest`	Download and process flood maps.
`mirror`	Download ALL source flood-map tiles to the cache (download-only; resumable).
`export`	Generate the Global Index Raster.
`build_index`	Build the index COG + Parquet dictionary + publish manifest, then validate.
`doctor`	Validate a built index bundle (COG + Parquet dictionary + publish manifest).
`publish`	Publish the built index bundle to Source Cooperative and/or Zenodo.
`verify_remote`	Verify a published index end-to-end over HTTP (manifest, /vsicurl COG, a query).
`mirror_index`	Download the published index bundle to the local cache (offline / HPC mirror).
`floods`	Query historic flood events for PLACE (cheap; no rasters downloaded).
`download`	Search PLACE and download + crop the matching flood maps.
`hazard`	Query global GLOFAS flood-hazard maps for PLACE by return period.
`mirror_hazard`	Download ALL GLOFAS hazard tiles into the cache for offline/local access.
`build_hazard_manifest_cmd`	Author the hazard reference manifest (provenance; references JRC, no copies).

Classes

EuroFloodCLI

Bases: Group

A click Group that renders EuroFlood errors cleanly (no traceback).

Methods:

Name	Description
`invoke`	Dispatch, turning known EuroFlood errors into clean CLI output.

Methods:

invoke

invoke(ctx: Context) -> Any

Dispatch, turning known EuroFlood errors into clean CLI output.

Unknown (non-EuroFlood) exceptions propagate untouched so real bugs stay loud. -v/--verbose re-raises the domain error too, restoring the traceback for developers. click exceptions keep click's own handling.

Functions:

cli

cli(
    ctx: Context,
    verbose: int,
    quiet: bool,
    json_mode: bool,
    no_color: bool,
) -> None

EuroFlood: Satellite Flood Map Processing Tool.

A toolset for downloading, indexing, and extracting European Satellite-Derived Flood Depth Maps.

ingest

ingest(
    year: int | None,
    month: str | None,
    update: bool,
    shard_count: int | None,
    shard_index: int | None,
    limit: int | None,
    dry_run: bool,
) -> None

Download and process flood maps.

Runs the ingestion pipeline which: 1. Scrapes the JRC website for available files. 2. Downloads matching files to the cache. 3. Processes them into optimized Parquet files.

For HPC: a SLURM array maps $SLURM_ARRAY_TASK_ID -> --shard-index so each task ingests a deterministic, resumable slice of the inventory.

mirror

mirror(
    year: int | None,
    update: bool,
    verify: bool,
    retry_failed: bool,
    limit: int | None,
    dry_run: bool,
) -> None

Download ALL source flood-map tiles to the cache (download-only; resumable).

The stable "download first, then process" path for the full archive (~35 GB). Re-running skips files already present; --verify re-fetches any whose on-disk size doesn't match the JRC listing; a later ingest only processes the cached files.

export

export(dry_run: bool) -> None

Generate the Global Index Raster.

Aggregates all processed Parquet files into a single, high-resolution GeoTIFF index covering Europe. This index maps every pixel to a unique combination of historical flood events.

build_index

build_index(dry_run: bool) -> None

Build the index COG + Parquet dictionary + publish manifest, then validate.

The Phase-5a producer entry point: runs the export aggregation and immediately validates the bundle with the doctor (the gate Phase 5b publishes through).

doctor

doctor(dry_run: bool) -> None

Validate a built index bundle (COG + Parquet dictionary + publish manifest).

publish

publish(
    version: str | None,
    to_source_coop: bool,
    to_zenodo: bool,
    sandbox: bool,
    no_verify: bool,
    dry_run: bool,
) -> None

Publish the built index bundle to Source Cooperative and/or Zenodo.

Source Cooperative is the live /vsicurl query host; Zenodo mints a citable DOI. With no target flag, defaults to --source-coop. Credentials come from the environment / a local .env (AWS STS for Source Cooperative, ZENODO_TOKEN for Zenodo). --source-coop needs the publish extra (pip install "euroflood[publish]").

verify_remote

verify_remote(url: str | None, deep: bool) -> None

Verify a published index end-to-end over HTTP (manifest, /vsicurl COG, a query).

mirror_index

mirror_index(tables_only: bool, dry_run: bool) -> None

Download the published index bundle to the local cache (offline / HPC mirror).

Reads index_base_url; pulls the COG + normalized dictionary + events table + manifest so floods() runs fully offline. --tables-only mirrors just the ~20 MB tables and leaves the COG to stream via /vsicurl.

floods

floods(
    place: str,
    year: int | None,
    start: str | None,
    end: str | None,
    buffer: float,
    shape: str,
    query_expr: str | None,
    out_path: str | None,
    dry_run: bool,
) -> None

Query historic flood events for PLACE (cheap; no rasters downloaded).

download

download(
    place: str,
    year: int | None,
    start: str | None,
    end: str | None,
    buffer: float,
    shape: str,
    query_expr: str | None,
    output_dir: str | None,
    dry_run: bool,
) -> None

Search PLACE and download + crop the matching flood maps.

hazard

hazard(
    place: str,
    return_periods: tuple[int, ...],
    buffer: float,
    shape: str,
    do_download: bool,
    query_expr: str | None,
    out_path: str | None,
    dry_run: bool,
) -> None

Query global GLOFAS flood-hazard maps for PLACE by return period.

mirror_hazard

mirror_hazard(
    return_periods: tuple[int, ...], dry_run: bool
) -> None

Download ALL GLOFAS hazard tiles into the cache for offline/local access.

build_hazard_manifest_cmd

build_hazard_manifest_cmd(dry_run: bool) -> None

Author the hazard reference manifest (provenance; references JRC, no copies).