CLI Reference¶

The gathering command-line tool is installed automatically with the package. You can also run it via python -m gathering.

General Usage¶

gathering [--verbose] [--log-file FILE] <command> [options]

Flag	Description
`--verbose`	Enable debug-level logging
`--log-file FILE`	Write logs to a file

List Available Sources¶

gathering list

Displays a table of all registered gatherers, their aliases, and whether they require authentication.

Run from YAML Configuration¶

# Execute a local YAML configuration file
gathering config.yaml

# Run a built-in example directly using the example: prefix
gathering run example:cdse/cdse_sentinel2_msi.yaml

# With verbose logging and log persistence
gathering --verbose --log-file run.log config.yaml

See YAML Configuration for the full specification.

Built-in Examples¶

Gathering includes a suite of 22+ ready-to-run configuration examples packaged directly with the CLI:

# List all packaged examples grouped by source category
gathering examples list

# Filter examples by category (e.g., cdse, eumdac, modis, pandonia, aeronet)
gathering examples list --category cdse

# Print an example's YAML content to stdout
gathering examples show aeronet/aeronet_aod_inversions.yaml

# Copy an example to your current workspace for editing
gathering examples copy cdse/cdse_sentinel2_msi.yaml .

Source Subcommands¶

Each registered source gets an automatic CLI subcommand derived from its parameter model.

AERONET¶

gathering aeronet \
  --station Magurele_Inoe \
  --product AOD15 \
  --start_date 2023-05-01 \
  --end_date 2023-05-21

ACTRIS Ares¶

gathering actris_ares \
  --station waw \
  --product optical \
  --start_date 2020-04-01 \
  --end_date 2020-04-07 \
  --ewls 355 532 \
  --file_types b \
  --levels 1.0

ACTRIS Cloudnet¶

gathering actris_cloudnet \
  --station hyytiala \
  --date 2021-01-01 \
  --product mwr radar

Pandonia¶

gathering pandonia \
  --station Thessaloniki \
  --start_date 2023-05-01 \
  --end_date 2023-05-21 \
  --product fnvh3

CDSE (Copernicus)¶

gathering cdse \
  --instrument MSI \
  --product_type S2MSI2A \
  --start_time 2024-07-01T00:00:00Z \
  --end_time 2024-07-05T23:59:59Z

EUMDAC (EUMETSAT)¶

gathering eumdac \
  --instrument FCI \
  --start_time 2024-09-01T10:00:00Z \
  --end_time 2024-09-01T14:00:00Z

EarthCARE¶

gathering earthcare \
  --product_types ATL_NOM_1B \
  --collections EarthCAREL1InstChecked \
  --start_time 2024-07-31T13:00:00Z \
  --end_time 2024-07-31T14:00:00Z

PACE¶

gathering pace \
  --instrument OCI \
  --product_type L1C \
  --start_time 2024-06-01T10:00:00Z \
  --end_time 2024-06-01T14:00:00Z

MODIS¶

gathering modis \
  --satellite Terra \
  --product_type MOD04_L2 \
  --start_time 2024-07-01T10:00:00Z \
  --end_time 2024-07-01T14:00:00Z

Authentication Commands¶

# Generate a template .env file
gathering auth env

# Save credentials interactively
gathering auth login earthcare

# Write credentials to .env
gathering auth login earthcare --env

# Check credentials status
gathering auth status

# Remove credentials
gathering auth logout earthcare

Free-Form Parameters¶

A gatherer that declares no PARAMS_MODEL still gets a subcommand, taking free-form --set parameters:

gathering my_source --set station=Roma --set product=x --set product=y

Repeat a key to build a list.