CLI Reference#

gedih3 installs 10 command-line tools. All tools support -v (INFO) and -vv (DEBUG) verbosity, and -Q for quiet mode.

Tip: Every tool supports --help (-h) for a complete list of flags and examples:
gh3_build --help
gh3_aggregate --help
gh3_extract --help

Core Workflow Tools#

`gh3_download`#

Download GEDI data from NASA DAAC.

gh3_download -r "W,S,E,N" -l2a default -l4a default -N 8
gh3_download -r region.shp -l4a agbd -t0 2020-01-01 -t1 2021-01-01
gh3_download --s3  # Stream from NASA S3 without local download

Flag	Description
`-r, --region`	Spatial filter: bbox, vector file, or ISO3 code
`-t0, -t1`	Start/end date (YYYY-MM-DD)
`-l1b, -l2a, -l2b, -l4a, -l4c`	Products to download (`default`, `minimal`, or list)
`--gedi-version`	GEDI data version (default: latest)
`--s3`	S3 streaming mode

`gh3_build`#

Build H3 parquet database from downloaded HDF5 files.

gh3_build -r "W,S,E,N" -l2a default -l4a default -h3r 12 -h3p 3
gh3_build -r region.shp -l4a agbd --resume
gh3_build --s3 -r region.shp -l4a agbd  # Build directly from S3

Flag	Description
`-h3r`	H3 index resolution (default: 12, ~25 m²)
`-h3p`	H3 partition resolution (default: 3, ~12,393 km²)
`-i`	Input directory where GEDI HDF5 files are stored (default: `GH3_DEFAULT_SOC_DIR`)
`-d`	Output H3 database directory

`gh3_extract`#

Extract data from H3 database into simplified flat parquet files.

gh3_extract -d /path/to/database -r region.shp -l2a rh_098 -l4a agbd -y -o output/

Flag	Description
`-d`	H3 database path
`-r`	Spatial filter
`-t0, -t1`	Temporal filter
`-l*`	Product variables
`-y, --quality`	Apply pre-configured quality filters
`-q, --query`	Pandas-style filter string
`-g`	Include geometry
`-o`	Output directory

EGI variant#

For square-pixel indexing instead of H3 — see EGI Indexing.

gh3_extract -d /path/to/database -egi 6 -o output/       # ~1 km EGI index
gh3_extract -d /path/to/database -egi 6:10 -o output/    # explicit index:partition

Flag	Description
`-egi INDEX[:PART]`	EGI index level and optional partition level

`gh3_aggregate`#

Aggregate data to a coarser spatial resolution.

gh3_aggregate -d /path/to/database -h3 6 -o output/
gh3_aggregate -d /path/to/database -h3 6 -a "['mean','std','count']" -o output/

Flag	Description
`-h3 LEVEL`	Aggregate to H3 level
`-a`	Aggregation function: `mean`, `sum`, `median`, `std`, `count`
`-R, --rasterize`	Export as rasters after aggregation
`-o`	Output directory

EGI variant#

gh3_aggregate -d /path/to/database -egi 6 -a mean -o output/        # ~1 km
gh3_aggregate -d /path/to/database -egi 6:10 -a mean -o output/     # explicit partition
gh3_aggregate -d /path/to/database -egi 6 -a mean -R -o output/     # aggregate + rasterize

Flag	Description
`-egi INDEX[:PART]`	EGI aggregation level and optional partition level

`gh3_rasterize`#

Convert pre-aggregated dataset to GeoTIFF rasters.

gh3_rasterize -d /path/to/aggregated/ -o output/ --compress LZW  # tiled output
gh3_rasterize -d /path/to/aggregated/ -m -o output.tif           # merged GeoTIFF
gh3_rasterize -d /path/to/aggregated/ -l agbd_l4a -o output/     # select variables

Flag	Description
`-d`	Dataset from `gh3_aggregate` or `gh3_extract`
`-l`	Variable(s) to rasterize
`-m`	Merge all tiles into a single GeoTIFF
`--compress`	Compression: `LZW`, `DEFLATE`, `ZSTD`, `NONE`
`-o`	Output path (directory or `.tif` when `-m`)

Ancillary Data Tools#

`gh3_from_img`#

Sample raster pixel values at GEDI shot locations.

# Single raster
gh3_from_img -i /path/to/dem.tif -d /path/to/database -r region.shp -o output/

# Tile directory with band selection and window operations
gh3_from_img -i /path/to/tiles/ -B 0 2 -w 131 -d /path/to/database -o output/

# Custom band names, quality filter, include geometry
gh3_from_img -i /path/to/raster.vrt -b elevation slope -d /path/to/database -y -g -o output/

Flag	Description
`-i`	Raster file (tif), VRT, or tile directory
`-B`	Band indices to sample (0-based)
`-b`	Custom band names
`-w`	Window operations (3-digit BZO format)
`-F, --fillna`	Fill NoData value
`-g`	Include geometry in output

Window spec format (-w BZO):

B = band index (0-based)
Z = window size (odd, 1–9)
O = operation: 0=sum, 1=mean, 2=median, 3=mode

`gh3_from_polygon`#

Join polygon attributes to GEDI shots via spatial join.

gh3_from_polygon -i ecoregions.shp -c ECO_NAME BIOME_NAME -d /path/to/database -o output/
gh3_from_polygon -i landcover.gpkg -x lc_ --dropna -d /path/to/database -o output/
gh3_from_polygon -i boundaries.shp -p intersects -d /path/to/database -o output/

Flag	Description
`-i`	Polygon vector file (shapefile, GPKG, GeoJSON)
`-c`	Columns to include from polygon file
`-x, --prefix`	Column name prefix (avoids conflicts)
`-p`	Spatial predicate: `within` (default) or `intersects`
`--dropna`	Drop shots not matched to any polygon
`-g`	Include geometry in output

Utility Tools#

`gh3_list_resolutions`#

Display H3 and EGI resolution levels with pixel sizes.

gh3_list_resolutions        # H3 levels
gh3_list_resolutions -egi   # EGI levels

`gh3_read_schema`#

Inspect file or database schemas. Lists column names and types from parquet, feather, geopackage, HDF5 files, or H3 databases. When no path is given, reads from the default H3 database.

gh3_read_schema                        # default H3 database
gh3_read_schema /path/to/database/     # specific H3 database
gh3_read_schema /path/to/file.parquet  # single file
gh3_read_schema /path/to/file.h5       # HDF5 file
gh3_read_schema -p L2A                 # filter by product
gh3_read_schema --grep agbd            # grep filter

Flag	Description
`path`	File or directory to inspect (default: H3 database)
`-p`	Filter by product suffix (e.g., `L2A` → `_l2a` columns)
`--grep`	Filter columns by keyword (case-insensitive)
`-g`	HDF5 group/beam filter (e.g., `BEAM0101`)

Common Flags#

Flag	Description
`-r, --region`	Spatial filter: vector file, bbox `"W,S,E,N"`, or ISO3 code
`-t0, -t1`	Temporal filters (YYYY-MM-DD)
`-l1b, -l2a, -l2b, -l4a, -l4c`	Product variables (supports wildcards, e.g. `"rh_*"`)
`-N, -T, -M, -P`	Dask workers, threads, memory, dashboard port
`-s`	Connect to existing Dask scheduler
`-v, -vv`	Verbosity: INFO, DEBUG
`-Q`	Quiet mode (errors only)
`-egi INDEX[:PART]`	EGI indexing
`-R`	Rasterize after aggregation (`gh3_aggregate` only)

Remote Storage Credentials#

All tools that accept a database path (-d) can read from remote filesystems. Pass the appropriate credential flags alongside the remote URI:

Flag	Description
`--s3-endpoint`	S3 endpoint URL (e.g. `http://localhost:7000`)
`--s3-key`	S3 access key
`--s3-secret`	S3 secret key
`--s3-anon`	Anonymous S3 access (for public buckets)
`--remote-user`	Username for HTTP basic auth / FTP / SFTP
`--remote-pass`	Password for HTTP basic auth / FTP / SFTP
`--remote-token`	Bearer token for HTTP(S) auth
`--ssh-key`	Path to SSH/SFTP private key file

Note

Supported protocols: s3://, http://, https://, ftp://, sftp:// (or ssh://). Credentials are passed through to fsspec — any option that fsspec accepts for a given protocol will work.

# Public S3 bucket (anonymous)
gh3_extract -d s3://my-bucket/h3_database/ --s3-anon -r region.shp -o output/

# SFTP with SSH key
gh3_aggregate -d sftp://server.example.com/data/h3/ --ssh-key ~/.ssh/id_rsa -egi 6 -o output/

CLI Reference#

Core Workflow Tools#

gh3_download#

gh3_build#

gh3_extract#

EGI variant#

gh3_aggregate#

EGI variant#

gh3_rasterize#

Ancillary Data Tools#

gh3_from_img#

gh3_from_polygon#

Utility Tools#

gh3_list_resolutions#

gh3_read_schema#

Common Flags#

Remote Storage Credentials#

`gh3_download`#

`gh3_build`#

`gh3_extract`#

`gh3_aggregate`#

`gh3_rasterize`#

`gh3_from_img`#

`gh3_from_polygon`#

`gh3_list_resolutions`#

`gh3_read_schema`#