Skip to content

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 / region failure (place not found, unknown NUTS id, bad or mismatched CRS)
5 Network / scraping failure
6 Hazard tile error
7 Cache schema mismatch (rebuild or re-mirror the index)
8 Raster processing error
9 Publishing failure (Source Cooperative / Zenodo)
10 Verification failure (published index or local mirror not ready)

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

Region options

floods, download, hazard and the mirror / verify subcommands all select a region the same way: a PLACE argument, or exactly one of --nuts, --bbox, --point and --shapefile.

Option Meaning
PLACE A place name, geocoded (OpenStreetMap, then the offline NUTS dataset).
--bbox MINX MINY MAXX MAXY A bounding box, in WGS 84 lon/lat or in --crs.
--point LAT LON A point, with --radius around it. X Y (easting, northing) with a projected --crs.
--radius M Radius in ground metres around --point.
--shapefile PATH Any vector file. Its own CRS is used; --crs fills in a missing one.
--nuts ID A Eurostat NUTS region (NL22); repeat the option to union several. Find ids with euroflood nuts.
--buffer M Extra buffer around the region, in ground metres.
--shape exact\|bbox\|hull The raw boundary (default), its bounding box, or its convex hull.
--crs CRS Coordinate reference system of --bbox / --point: anything pyproj accepts (EPSG:28992, 3035, WKT). Default: WGS 84 lon/lat. 
euroflood floods --bbox 200000 455000 220000 475000 --crs EPSG:28992          # Dutch RD New, metres
euroflood hazard --point 308400 5780300 --radius 5000 --crs EPSG:32632 -r 100  # UTM 32N: X Y
euroflood mirror all --bbox 6.1 52.0 6.3 52.2 -r 100                            # WGS 84 (the default)
euroflood nuts Gelderland                       # find NUTS identifiers by name -> NL22, NL224
euroflood nuts --country NL --level 2           # list a country's NUTS-2 regions
euroflood floods --nuts NL22                    # every flood in Gelderland (exact NUTS boundary)
euroflood hazard --nuts NL22 --nuts NL21 -r 100 # the union of two regions

A bad or mismatched --crs, degrees typed into a metre CRS, or coordinates outside the CRS's domain exit with code 4 and a one-line hint naming the fix.

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; ~39 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 a region (cheap; no rasters downloaded).
download

Search a region and download + crop the matching flood maps.
hazard

Query global GLOFAS flood-hazard maps for a region by return period.
nuts

Find Eurostat NUTS regions: search QUERY by name, or list by --country/--level.
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; ~39 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 producer entry point: runs the export aggregation and immediately validates the bundle with the doctor, the gate a publish goes 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,
    record_id: int | None,
    readme_only: 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]").

For any Zenodo release after the first, pass --record-id so the existing concept DOI keeps resolving to the latest version; without it a separate record (and a separate concept DOI) is created.

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,
    nuts: tuple[str, ...],
    buffer_m: float,
    shape: str,
    crs: str | None,
    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,
    nuts: tuple[str, ...],
    buffer_m: float,
    shape: str,
    crs: str | None,
    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,
    nuts: tuple[str, ...],
    buffer_m: float,
    shape: str,
    crs: str | None,
    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,
    nuts: tuple[str, ...],
    buffer_m: float,
    shape: str,
    crs: str | None,
    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,
    nuts: tuple[str, ...],
    buffer_m: float,
    shape: str,
    crs: str | None,
    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,
    nuts: tuple[str, ...],
    buffer_m: float,
    shape: str,
    crs: str | None,
    return_periods: tuple[int, ...],
    deep: bool,
) -> None

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

floods 

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

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

The region is PLACE, or exactly one of --bbox / --point / --shapefile.

download 

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

Search a region and download + crop the matching flood maps.

The region is PLACE, or exactly one of --bbox / --point / --shapefile.

hazard 

hazard(
    place: str | None,
    bbox: Any,
    point: Any,
    radius_m: float,
    shapefile: str | None,
    nuts: tuple[str, ...],
    buffer_m: float,
    shape: str,
    crs: str | None,
    return_periods: tuple[int, ...],
    do_download: bool,
    query_expr: str | None,
    out_path: str | None,
    dry_run: bool,
) -> None

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

The region is PLACE, or exactly one of --bbox / --point / --shapefile.

nuts 

nuts(
    query: str | None,
    level: int | None,
    country: str | None,
    with_geometry: bool,
    out_path: str | None,
) -> None

Find Eurostat NUTS regions: search QUERY by name, or list by --country/--level.

Prints each region's identifier, level, country and name. A QUERY that is an identifier lists the region and its descendants (e.g. 'NL2' with --level 3). Pass an identifier to floods/hazard/download with --nuts.

build_hazard_manifest_cmd 

build_hazard_manifest_cmd(dry_run: bool) -> None

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