CLI reference

Generated from gaia --help.

gaia COMMAND

Commands:

• align: Align staged rasters onto one grid and time step, writing a new store.

• catalog: STAC catalog of staged stores.

• prism: Manage the gaia PRISM cache.

• stage: Stage datasets clipped to an AOI and time range.

gaia stage¶

gaia stage COMMAND --config STR [OPTIONS]

Stage datasets clipped to an AOI and time range.

Commands:

• burn-severity: USFS BAER soil burn severity map, clipped to an AOI.

• dem: Digital elevation model, clipped to an AOI.

• hrrr: HRRR hourly analysis, clipped to an AOI.

• nlcd: Annual NLCD land cover, clipped to an AOI.

• prism: PRISM daily 800 m grids, clipped to an AOI.

• soil: Soil property maps, clipped to an AOI.

• synoptic: Weather station reports from the Synoptic API, clipped to an AOI.

Parameters:

• --config, -c STR: Path or http(s) URL of a stage.yaml file, or the name of a preset. A file read from a URL gives its AOIs as URLs or inline. [required]

• --input, -i STR: With a preset only: path to a vector file defining the AOI.

• --start, -s STR: With a preset only: start (inclusive), a date or UTC time.

• --end, -e STR: With a preset only: end; a date includes the whole day.

• --output, -o STR: Output folder for <name>.zarr, its STAC Item <name>.json and the resolved stage.yaml. Default: the file’s output.

• --only STR: Comma-separated datasets from the file to stage, e.g. prism,hrrr.

• --dry-run: Validate the file, read the AOIs and print the resolved configuration, including datasets skipped for coverage, without fetching any data. [default: False]

• --overwrite: Write into an output folder that isn’t empty, replacing its store. Default False. [default: False]

• --skip-existing: Add to an existing store, skipping datasets whose group it already has. Use it to retry the datasets that failed. Default False. [default: False]

gaia stage synoptic¶

gaia stage synoptic INPUT START END OUTPUT [ARGS]

Weather station reports from the Synoptic API, clipped to an AOI.

Every report is kept, as a CF ragged array (see dev/stations.md). Requires SYNOPTIC_TOKEN (https://docs.synopticdata.com).

Parameters:

• INPUT, --input, -i: Vector file or URL holding the AOI, a single Polygon. [required]

• START, --start, -s: Start (inclusive), a date or UTC time. [required]

• END, --end, -e: End; a date includes the whole day. [required]

• OUTPUT, --output, -o: Output folder for the Zarr store (named after the folder), its STAC Item and the resolved stage.yaml. [required]

• VARIABLES, --variables, -v, --empty-variables: Synoptic variables, e.g. precip_accum air_temp. precip_accum is staged as precipitation, a running total. [default: (‘precip_accum’,)]

• DRY-RUN, --dry-run: Validate the flags, read the AOI and print the resolved configuration without fetching any data. [default: False]

• OVERWRITE, --overwrite: Write into an output folder that isn’t empty, replacing its store. [default: False]

• SKIP-EXISTING, --skip-existing: Add to an existing store, unless it already has this dataset’s group. [default: False]

gaia stage prism¶

gaia stage prism INPUT START END OUTPUT [ARGS]

PRISM daily 800 m grids, clipped to an AOI.

Data come from the gaia PRISM cache (s3://gaia/public/prism). Grids not yet cached are fetched from PRISM, which requires AWS_PROFILE with write access to the cache (see dev/prism.md).

Parameters:

• INPUT, --input, -i: Vector file or URL holding the AOI, a single Polygon. [required]

• START, --start, -s: Start (inclusive), a date or UTC time. [required]

• END, --end, -e: End; a date includes the whole day. [required]

• OUTPUT, --output, -o: Output folder for the Zarr store (named after the folder), its STAC Item and the resolved stage.yaml. [required]

• VARIABLES, --variables, -v, --empty-variables: PRISM variables (ppt, tmin, tmax, tmean). ppt is returned as precipitation; the others keep their names. [choices: ppt, tmin, tmax, tmean] [default: (‘ppt’,)]

• DRY-RUN, --dry-run: Validate the flags, read the AOI and print the resolved configuration without fetching any data. [default: False]

• OVERWRITE, --overwrite: Write into an output folder that isn’t empty, replacing its store. [default: False]

• SKIP-EXISTING, --skip-existing: Add to an existing store, unless it already has this dataset’s group. [default: False]

gaia stage hrrr¶

gaia stage hrrr INPUT START END OUTPUT [ARGS]

HRRR hourly analysis, clipped to an AOI.

Precipitation rate (kg m-2 s-1) is staged as hourly accumulation (mm). See dev/hrrr.md.

Parameters:

• INPUT, --input, -i: Vector file or URL holding the AOI, a single Polygon. [required]

• START, --start, -s: Start (inclusive), a date or UTC time. [required]

• END, --end, -e: End; a date includes the whole day. [required]

• OUTPUT, --output, -o: Output folder for the Zarr store (named after the folder), its STAC Item and the resolved stage.yaml. [required]

• VARIABLE, --variable, -v: HRRR variable name to extract. [choices: categorical-freezing-rain-surface, categorical-ice-pellets-surface, categorical-rain-surface, categorical-snow-surface, composite-reflectivity, dew-point-temperature-2m, downward-long-wave-radiation-flux-surface, downward-short-wave-radiation-flux-surface, geopotential-height-cloud-ceiling, percent-frozen-precipitation-surface, precipitable-water-atmosphere, precipitation-surface, pressure-reduced-to-mean-sea-level, pressure-surface, relative-humidity-2m, snow-area-fraction-surface, snow-thickness-surface, snow-water-equivalent-surface, snowfall-surface, temperature-2m, total-cloud-cover-atmosphere, wind-gust-surface, wind-u-10m, wind-u-80m, wind-v-10m, wind-v-80m] [default: precipitation-surface]

• DRY-RUN, --dry-run: Validate the flags, read the AOI and print the resolved configuration without fetching any data. [default: False]

• OVERWRITE, --overwrite: Write into an output folder that isn’t empty, replacing its store. [default: False]

• SKIP-EXISTING, --skip-existing: Add to an existing store, unless it already has this dataset’s group. [default: False]

gaia stage nlcd¶

gaia stage nlcd INPUT OUTPUT [ARGS]

Annual NLCD land cover, clipped to an AOI.

Parameters:

• INPUT, --input, -i: Vector file or URL holding the AOI, a single Polygon. [required]

• OUTPUT, --output, -o: Output folder for the Zarr store (named after the folder), its STAC Item and the resolved stage.yaml. [required]

• YEAR, --year, -y: Land cover year (1985-2024). [default: 2021]

• DRY-RUN, --dry-run: Validate the flags, read the AOI and print the resolved configuration without fetching any data. [default: False]

• OVERWRITE, --overwrite: Write into an output folder that isn’t empty, replacing its store. [default: False]

• SKIP-EXISTING, --skip-existing: Add to an existing store, unless it already has this dataset’s group. [default: False]

gaia stage dem¶

gaia stage dem INPUT OUTPUT [ARGS]

Digital elevation model, clipped to an AOI.

See dev/dem.md.

Parameters:

• INPUT, --input, -i: Vector file or URL holding the AOI, a single Polygon. [required]

• OUTPUT, --output, -o: Output folder for the Zarr store (named after the folder), its STAC Item and the resolved stage.yaml. [required]

• PRODUCT, --product, -p: cop30 (Copernicus GLO-30, global, EGM2008 heights) or usgs10m (USGS 3DEP 1/3 arc-second, US, NAVD88 heights). [choices: cop30, usgs10m] [default: cop30]

• DRY-RUN, --dry-run: Validate the flags, read the AOI and print the resolved configuration without fetching any data. [default: False]

• OVERWRITE, --overwrite: Write into an output folder that isn’t empty, replacing its store. [default: False]

• SKIP-EXISTING, --skip-existing: Add to an existing store, unless it already has this dataset’s group. [default: False]

gaia stage soil¶

gaia stage soil INPUT OUTPUT [ARGS]

Soil property maps, clipped to an AOI.

See dev/soil.md.

Parameters:

• INPUT, --input, -i: Vector file or URL holding the AOI, a single Polygon. [required]

• OUTPUT, --output, -o: Output folder for the Zarr store (named after the folder), its STAC Item and the resolved stage.yaml. [required]

• PRODUCT, --product, -p: solus100 (USDA SOLUS100, CONUS, 100 m): the seven layers landlab reads. statsgo (USGS, CONUS, 30 m, from 1:250,000 polygons): the K-factor, kffact. [choices: solus100, statsgo] [default: solus100]

• DRY-RUN, --dry-run: Validate the flags, read the AOI and print the resolved configuration without fetching any data. [default: False]

• OVERWRITE, --overwrite: Write into an output folder that isn’t empty, replacing its store. [default: False]

• SKIP-EXISTING, --skip-existing: Add to an existing store, unless it already has this dataset’s group. [default: False]

gaia stage burn-severity¶

gaia stage burn-severity INPUT OUTPUT [ARGS]

USFS BAER soil burn severity map, clipped to an AOI.

See dev/burn-severity.md.

Parameters:

• INPUT, --input, -i: Vector file or URL holding the AOI, a single Polygon. [required]

• OUTPUT, --output, -o: Output folder for the Zarr store (named after the folder), its STAC Item and the resolved stage.yaml. [required]

• FIRE, --fire, -f: Part of the fire’s BAER name (e.g. bolt creek), to choose when several fires intersect the AOI. Case and spaces are ignored.

• YEAR, --year, -y: The fire’s year, to choose when several fires intersect the AOI.

• DRY-RUN, --dry-run: Validate the flags, read the AOI and print the resolved configuration without fetching any data. [default: False]

• OVERWRITE, --overwrite: Write into an output folder that isn’t empty, replacing its store. [default: False]

• SKIP-EXISTING, --skip-existing: Add to an existing store, unless it already has this dataset’s group. [default: False]

gaia align¶

gaia align INPUT OUTPUT [ARGS]

Align staged rasters onto one grid and time step, writing a new store.

Each raster is first aggregated in time to the coarsest product’s intervals (using its time_bounds and cell_methods), then regridded once from its native grid onto the coarsest product’s grid.

Parameters:

• INPUT, --input, -i: Store written by gaia stage (local path or s3:// URL). [required]

• OUTPUT, --output, -o: Output folder for the aligned store (named after the folder) and its STAC Item. The input is never modified. [required]

• LIKE, --like: Group whose grid is the target, e.g. rasters/hrrr. Default: coarsest.

• TIME-LIKE, --time-like: Group whose time intervals are the target, e.g. rasters/prism. Default: coarsest.

• CRS, --crs: Target CRS for an explicit grid (use with --res), or utm for the UTM zone of the AOI. The grid covers --aoi (else every raster), its edges snapped outward to multiples of --res.

• RES, --res: Target resolution in --crs units.

• METHOD, --method, -m, --empty-method: Spatial resampling: conservative, average, bilinear, cubic, nearest or mode, for all continuous data, or GROUP=METHOD (or GROUP/VARIABLE=METHOD) for one dataset, categorical or not. Repeatable. Default: each dataset’s own (conservative for PRISM and HRRR, bilinear for DEMs, mode for categories), else nearest. conservative becomes nearest onto a finer grid.

• AOI, --aoi: Optional vector file; cells whose center is outside it are NaN.

• OVERWRITE, --overwrite: Write into an output folder that isn’t empty, replacing its store. Default False. [default: False]

gaia catalog¶

STAC catalog of staged stores.

gaia catalog rebuild¶

gaia catalog rebuild PREFIX

Write a STAC catalog of the gaia stores under PREFIX.

Finds the Items that gaia stage/gaia align write next to their stores, skips any whose store was deleted, and writes PREFIX/catalog.json. Requires AWS credentials for an s3:// PREFIX.

Parameters:

• PREFIX, --prefix, -p: Local directory or s3:// URL holding staged stores. [required]

gaia prism¶

Manage the gaia PRISM cache.

gaia prism fill¶

gaia prism fill START END [ARGS]

Fetch PRISM grids into the gaia cache (s3://gaia/public/prism).

Downloads grids that are missing and, unless --no-revalidate, re-fetches provisional grids that PRISM has since re-released. Requires AWS_PROFILE with write access to the cache.

Parameters:

• START, --start, -s: Start date (inclusive), e.g. ‘2025-12-01’. [required]

• END, --end, -e: End date (inclusive). [required]

• VARIABLES, --variables, -v, --empty-variables: PRISM variables. Default ppt. [choices: ppt, tmin, tmax, tmean] [default: (‘ppt’,)]

• REVALIDATE, --revalidate, --no-revalidate: Check cached provisional grids for newer releases. Default True. [default: True]

gaia prism rebuild-catalog¶

gaia prism rebuild-catalog

Regenerate the cache’s STAC catalogs and collection from its items.

The catalogs are normally updated as grids are cached; use this to repair them. Requires AWS_PROFILE with write access to the cache.