CLI reference

The full snowtool command tree, generated from the Click definitions.

snowtool

Usage:

snowtool [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
--version	boolean	Show the version and exit.	False
--color	choice (auto | always | never)	Colorize output (auto: only on a TTY; NO_COLOR is honored).	auto
--quiet, -q	boolean	Suppress progress bars and status messages (stderr); data output is unaffected.	False
--help	boolean	Show this message and exit.	False

api

Read-API server commands.

Usage:

snowtool api [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

serve

Run the server. Options here configure the app (each sets its env var); uvicorn options are accepted and forwarded — see --help-server.

Usage:

snowtool api serve [OPTIONS]

Options:

Name	Type	Description	Default
--check	boolean	Validate settings and that the app imports, then exit (no server).	False
--help-server	boolean	Show uvicorn's own options (all are accepted and forwarded), then exit.	False
-C, --config	text	Snowdb config file or its directory.	Sentinel.UNSET
--snowtool-tiff-cache-size	integer	Max open async-tiff handles kept in the read-path LRU cache.	16384
--snowtool-max-zone-cells	integer	Cap on a crossed zonal-stats query product size (output rows).	10000
--help	boolean	Show this message and exit.	False

dataset

Dataset management commands.

Usage:

snowtool dataset [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

activate

Make registered dataset NAME visible to readers (query CLI + API).

Activation only toggles reader visibility: the dataset was already fully manageable by name (ingest, generate-zones, diagnostics) while inactive, and stays so either way. Idempotent.

Usage:

snowtool dataset activate [OPTIONS] NAME

Options:

Name	Type	Description	Default
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

create

Create dataset NAME: stage its artifacts and register it (inactive).

Staging writes the directory skeleton, the area raster, the dataset config (data/NAME/dataset.json), an AOI raster of every indexed pourpoint's basin on the new grid, and each pourpoint's coverage of that grid -- never zone layers. Zone-layer generation is a separate explicit operation: dataset generate-zones NAME ..., which shares one source read across every named dataset (so create several datasets first, then generate their zone layers together). The dataset is registered inactive: it exists (manageable by name -- ingest, generate-zones, diagnostics) but stays invisible to readers (query/API) until dataset activate NAME flips it live. The dataset's definition comes from --template (a built-in). Converge-by-default, like ingest: a re-create leaves current artifacts untouched (an AOI raster rebuilds only when its provenance tag reads stale) and never touches an existing registration (its active state and link are preserved). To force-rebuild AOI rasters regardless, use pourpoint rasterize --all --rebuild -d NAME.

Usage:

snowtool dataset create [OPTIONS] NAME

Options:

Name	Type	Description	Default
--template	text	Stamp a built-in dataset template (e.g. snodas, swann-800m, instarr) as the new dataset NAME.	Sentinel.UNSET
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

dates

Ingested (or, with --missing, missing) dates for dataset NAME.

Without --missing, lists every ingested date, optionally filtered by --start/--end. With --missing, lists every date absent between --start (default: the dataset's first ingested date) and --end (default: today), inclusive.

Resolves any registered dataset -- active or not -- like dataset info.

Usage:

snowtool dataset dates [OPTIONS] NAME

Options:

Name	Type	Description	Default
--start	date	Only dates on/after this.	None
--end	date	Only dates on/before this.	None
--missing	boolean	List missing dates in the range instead of ingested ones.	False
--format	choice (table | json | csv)	Output format.	table
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

deactivate

Hide registered dataset NAME from readers (query CLI + API).

The dataset stays registered and fully manageable by name (ingest, generate-zones, diagnostics) -- only reader visibility changes. Idempotent.

Usage:

snowtool dataset deactivate [OPTIONS] NAME

Options:

Name	Type	Description	Default
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

generate-zones

(Re)generate zone layers for one or more datasets, sharing each source read.

Each NAME is a registered dataset name (active or not); a token containing a path separator or ending in .json is instead a dataset config path. Activation does not matter -- zone layers live under data/<name>/ independent of the root-config link's visibility flag, so you can generate them for freshly created (registered-inactive) datasets before any of them is activated. Every configured provider (terrain, land cover, ...) is generated unless --provider limits the selection; each provider's source is read once over the combined extent of all the named datasets and binned into every one -- so standing up several datasets that share a provider pays that provider's expensive read (terrain reprojects the whole DEM source to a 10 m work grid; land cover downloads the ~1.5 GB MRLC Annual NLCD national raster) a single time. --source PROVIDER PATH supplies a local file for a provider instead of its default source. Always rebuilds, overwriting existing layers.

Usage:

snowtool dataset generate-zones [OPTIONS] NAME...

Options:

Name	Type	Description	Default
--provider	text	Limit generation to these zone-layer providers (default: all).	Sentinel.UNSET
--source		Generate PROVIDER zone layers from a local PATH instead of the default source (repeatable).	Sentinel.UNSET
--workers	integer range (1 and above)	Terrain-generation worker threads (default: one per CPU; 1 = serial). Block reprojection is parallelized; the result is identical regardless.	None
--block-size	integer range (64 and above)	Terrain work-grid block edge in pixels (default 1024). Lower it to bound per-worker memory (~workers x block_size^2); no effect on the result.	None
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

info

Show a dataset's grid, variables, and on-disk artifacts.

Resolves any registered dataset -- an inactive one is still inspectable (its active field says whether readers serve it).

Usage:

snowtool dataset info [OPTIONS] NAME

Options:

Name	Type	Description	Default
--format	choice (table | json | csv)	Output format.	table
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

ingest

Ingest a single SOURCE into dataset NAME.

SOURCE is one source artifact per invocation, and its shape is the dataset's: a single file for snodas (a daily tar archive) and swann (a daily NetCDF) -- one file == one date -- or a directory of SPIRES .nc tiles for instarr. Always pass instarr the directory: a date's mosaic is built from ALL of its tiles in one ingest call (per-tile calls would each rebuild the date from a single tile, last write wins). Batch driving belongs to the shell -- e.g. ls /data/snodas/*.tar | xargs -n1 -P4 snowtool dataset ingest snodas -- and parallel runs are safe across distinct dates because each date commits via an atomic whole-directory swap.

NAME is a registered dataset name (active or not) or a dataset config path -- ingest is a management op, so reader visibility is irrelevant (the point of the register/activate split is populating a dataset before serving it). Converge-by-default: a date whose COGs already carry the same source hash is left untouched (reported up-to-date); a re-release under the same filename with different bytes rebuilds. --force rebuilds every date regardless.

Usage:

snowtool dataset ingest [OPTIONS] NAME SOURCE

Options:

Name	Type	Description	Default
--force	boolean	Rebuild dates even when the stored source hash already matches.	False
--format	choice (table | json | csv)	Output format.	table
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

list

List every registered dataset and whether readers serve it (active).

One row per dataset the root config registers, active or not -- for presence, date spans, and artifact counts, see snowtool status.

Usage:

snowtool dataset list [OPTIONS]

Options:

Name	Type	Description	Default
--format	choice (table | json | csv)	Output format.	table
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

register

Register dataset NAME from its config at CONFIG_PATH (writes the link).

The escape hatch for a dataset built out of tree (or otherwise out of band): dataset create already stages and registers, so register exists only to link an externally built config into the root config. Registration is inactive: the dataset becomes manageable by name (ingest, generate-zones, diagnostics) but invisible to readers until dataset activate NAME. The config is validated (it must parse and its ingester must resolve) before the link is written. Idempotent -- re-registering a name overwrites its link. Since register skips staging, pourpoint coverage for the new dataset is unknown until the next pourpoint reindex.

Usage:

snowtool dataset register [OPTIONS] NAME CONFIG_PATH

Options:

Name	Type	Description	Default
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

remove-date

Remove a single ingested DATE from dataset NAME.

NAME is a registered dataset name (active or not) or a dataset config path.

Usage:

snowtool dataset remove-date [OPTIONS] NAME DATE

Options:

Name	Type	Description	Default
--dry-run	boolean	Show what would be removed only.	False
--yes	boolean	Skip the confirmation prompt.	False
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

values

Per-variable min/max/mean (unit-scaled) and nodata % for one date.

Usage:

snowtool dataset values [OPTIONS] NAME

Options:

Name	Type	Description	Default
--date	date	Date to report (default: latest ingested).	None
--format	choice (table | json | csv)	Output format.	table
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

doctor

Run health checks; print findings and exit 1 if there are any.

Checks: grid, dates, files, pourpoints (default: all). Empty output ([] for json) means healthy. An explicit -d NAME always resolves from everything registered.

Examples: snowtool doctor snowtool doctor files pourpoints -d snodas --format json

Usage:

snowtool doctor [OPTIONS] [CHECK]...

Options:

Name	Type	Description	Default
--dataset, -d	text	Dataset to act on, active or not (repeatable; default: every registered dataset -- doctor narrows this to active unless --include-inactive).	Sentinel.UNSET
--include-inactive	boolean	Also check registered-but-inactive datasets (default: active only, so a half-built staged dataset does not fail the cron/CI gate).	False
--format	choice (table | json | csv)	Output format.	table
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

init

Create an empty snowdb at PATH (or the --config / env-var root).

Lays out the root config (snowdb_conf.json), pourpoints/, and data/. No datasets are registered: dataset create stages one (area raster + zone layers) and registers it inactive; dataset activate makes it live. Idempotent -- an existing root config is left untouched.

Usage:

snowtool init [OPTIONS] [PATH]

Options:

Name	Type	Description	Default
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

pourpoint

Global pourpoint management commands.

Usage:

snowtool pourpoint [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

dump

Copy a stored pourpoint's record geojson out to OUTPUT_DIR (round-trip).

Usage:

snowtool pourpoint dump [OPTIONS] TRIPLET

Options:

Name	Type	Description	Default
-o, --output-dir	directory	Directory to write the record geojson into (default: cwd).	.
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

import

Additively import a single pourpoint record into the snowdb from SRC.

SRC is one local file, or a single-file http(s) URL (e.g. a raw.githubusercontent.com link). For bulk ingest, use pourpoint sync (or loop this command, e.g. with xargs).

Imports a basin-bearing pourpoint, skips a point-only one, and reports an unparseable file (nonzero exit). Never removes a stored pourpoint.

Usage:

snowtool pourpoint import [OPTIONS] SRC

Options:

Name	Type	Description	Default
--dry-run	boolean	Classify sources without writing.	False
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

list

List stored pourpoints from the index (triplet, name, area, coverage).

Usage:

snowtool pourpoint list [OPTIONS]

Options:

Name	Type	Description	Default
--format	choice (table | json | csv)	Output format.	table
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

rasterize

Burn pourpoint basin(s) onto each dataset grid, building missing/stale rasters.

Provide a single TRIPLET or --all. By default only missing/stale rasters are (re)built; --rebuild forces all selected. Emits one row per (pourpoint, dataset) built or skipped; a built/skipped summary goes to stderr.

Usage:

snowtool pourpoint rasterize [OPTIONS] [TRIPLET]

Options:

Name	Type	Description	Default
--all	boolean	Rasterize every stored pourpoint.	False
--rebuild	boolean	Rebuild even rasters that are current.	False
--format	choice (table | json | csv)	Output format.	table
--dataset, -d	text	Dataset to act on, active or not (repeatable; default: every registered dataset -- doctor narrows this to active unless --include-inactive).	Sentinel.UNSET
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

reindex

Rebuild the index.geojson manifest from the stored records.

Usage:

snowtool pourpoint reindex [OPTIONS]

Options:

Name	Type	Description	Default
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

remove

Remove a stored pourpoint and its per-dataset rasters (cascade).

Usage:

snowtool pourpoint remove [OPTIONS] TRIPLET

Options:

Name	Type	Description	Default
--dry-run	boolean	Show what would be removed only.	False
--yes	boolean	Skip the confirmation prompt.	False
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

show

Show a stored pourpoint's details (from its record geojson).

Usage:

snowtool pourpoint show [OPTIONS] TRIPLET

Options:

Name	Type	Description	Default
--format	choice (table | json | csv)	Output format.	table
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

sync

Mirror SRC into the snowdb: import it, then prune pourpoints absent from it.

SRC is a local directory or a GitHub tree URL (https://github.com/<owner>/<repo>/tree/<branch>/<subdir>, the URL the browser shows for a folder) -- the *.geojson records under it are fetched into a temp dir and treated exactly like a local directory.

Any stored pourpoint whose triplet is not in SRC is dumped to --prune-to and removed (cascading to its per-dataset rasters). If a prune would happen and --prune-to is absent, the command errors before changing anything.

Usage:

snowtool pourpoint sync [OPTIONS] SRC

Options:

Name	Type	Description	Default
--prune-to	directory	Archive directory for pourpoints removed because they are absent from SRC.	None
--dry-run	boolean	Show the import + prune plan only.	False
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

stats

Zonal statistics for pourpoint TRIPLET over DATASET (whole-basin by default).

Examples: snowtool stats snodas 13120:CO:SNTL --dates 2024-01-01/2024-06-30 snowtool stats snodas 13120:CO:SNTL --dates 04-01 --years 2018..2024 \ --zone terrain.elevation --format json

Usage:

snowtool stats [OPTIONS] DATASET TRIPLET

Options:

Name	Type	Description	Default
--dates	text	OGC interval (2024-01-01/2024-06-30; .. for an open end), a single date, or MM-DD with --years. Default: every ingested date.	None
--years	text	Year span for a month-day --dates: 'YYYY' or 'YYYY..YYYY'.	None
--zone	text	Stratify by a zone layer (repeatable; default: whole basin). LAYER[:override], e.g. terrain.elevation:500 or landcover.forest_cover:40.	Sentinel.UNSET
--variable	text	Variable to report (repeatable; default: all of the dataset).	Sentinel.UNSET
--allow-partial	boolean	Permit a clipped result over an AOI the grid only partially covers.	False
--include-empty-zones	boolean	Include crossed zones no AOI pixel falls in (0 area, null stats). By default these are dropped; the output otherwise grows combinatorically with the number of --zone axes.	False
--format	choice (csv | json)	Output format (the zonal output is nested, so no table form).	csv
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False

status

Overview of every registered dataset: active flag, artifacts, date span.

Usage:

snowtool status [OPTIONS]

Options:

Name	Type	Description	Default
--format	choice (table | json | csv)	Output format.	table
--config, -C	path	Snowdb config file or its directory (defaults to the SNOWTOOL_SNOWDB_CONFIG env var).	None
--help	boolean	Show this message and exit.	False