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.
`fetch_sources`	Download ALL raw source flood-map tiles to the cache (producer; ~35 GB).
`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.
`mirror`	Stage data for offline/HPC use: index \| floods \| hazard \| all.
`verify`	Check local-mirror readiness: index \| floods \| hazard \| all \| remote.
`mirror_index_cmd`	Mirror the flood catalogue (index bundle) so floods() queries run offline.
`mirror_floods_cmd`	Mirror flood DEPTH maps for a region so floods().download() runs offline.
`mirror_hazard_cmd`	Mirror GLOFAS hazard tiles for a region so hazard().download() runs offline.
`mirror_all_cmd`	Mirror index + flood depths + hazard tiles for a region (one-shot prestage).
`verify_remote_cmd`	Verify a PUBLISHED index end-to-end over HTTP (manifest, /vsicurl COG, a query).
`verify_index_cmd`	Report index-bundle mirror readiness.
`verify_floods_cmd`	Report flood depth-map mirror readiness for a region.
`verify_hazard_cmd`	Report hazard-tile mirror readiness for a region.
`verify_all_cmd`	Report index + floods + hazard mirror readiness for a region.
`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.
`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.

fetch_sources

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

Download ALL raw source flood-map tiles to the cache (producer; ~35 GB).

The stable "download first, then process" path for the full archive, used to build the index. Not a consumer offline command. For that use mirror. 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]").

mirror

mirror() -> None

Stage data for offline/HPC use: index | floods | hazard | all.

verify

verify() -> None

Check local-mirror readiness: index | floods | hazard | all | remote.

mirror_index_cmd

mirror_index_cmd(dry_run: bool) -> None

Mirror the flood catalogue (index bundle) so floods() queries run offline.

mirror_floods_cmd

mirror_floods_cmd(
    place: str | None,
    bbox: Any,
    point: Any,
    radius_m: float,
    shapefile: str | None,
    buffer_m: float,
    shape: str,
    year: int | None,
    start: str | None,
    end: str | None,
    dry_run: bool,
) -> None

Mirror flood DEPTH maps for a region so floods().download() runs offline.

mirror_hazard_cmd

mirror_hazard_cmd(
    place: str | None,
    bbox: Any,
    point: Any,
    radius_m: float,
    shapefile: str | None,
    buffer_m: float,
    shape: str,
    return_periods: tuple[int, ...],
    dry_run: bool,
) -> None

Mirror GLOFAS hazard tiles for a region so hazard().download() runs offline.

mirror_all_cmd

mirror_all_cmd(
    place: str | None,
    bbox: Any,
    point: Any,
    radius_m: float,
    shapefile: str | None,
    buffer_m: float,
    shape: str,
    return_periods: tuple[int, ...],
    year: int | None,
    start: str | None,
    end: str | None,
    dry_run: bool,
) -> None

Mirror index + flood depths + hazard tiles for a region (one-shot prestage).

verify_remote_cmd

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

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

verify_index_cmd

verify_index_cmd(deep: bool) -> None

Report index-bundle mirror readiness.

verify_floods_cmd

verify_floods_cmd(
    place: str | None,
    bbox: Any,
    point: Any,
    radius_m: float,
    shapefile: str | None,
    buffer_m: float,
    shape: str,
    deep: bool,
) -> None

Report flood depth-map mirror readiness for a region.

verify_hazard_cmd

verify_hazard_cmd(
    place: str | None,
    bbox: Any,
    point: Any,
    radius_m: float,
    shapefile: str | None,
    buffer_m: float,
    shape: str,
    return_periods: tuple[int, ...],
    deep: bool,
) -> None

Report hazard-tile mirror readiness for a region.

verify_all_cmd

verify_all_cmd(
    place: str | None,
    bbox: Any,
    point: Any,
    radius_m: float,
    shapefile: str | None,
    buffer_m: float,
    shape: str,
    return_periods: tuple[int, ...],
    deep: bool,
) -> None

Report index + floods + hazard mirror readiness for a region.

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.

build_hazard_manifest_cmd

build_hazard_manifest_cmd(dry_run: bool) -> None

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