CLI reference
usdata
Discover, fetch, and track provenance of U.S. public scientific data.
Usage:
Options:
--version: Show version.--install-completion: Install completion for the current shell.--show-completion: Show completion for the current shell, to copy it or customize the installation.--help: Show this message and exit.
Commands:
cite: Print how to cite a dataset, or the inputs...datasets: List the curated dataset registry, filtered.search: Search the curated dataset registry.info: Show details for one dataset.inspect: Show what a fetched file holds: its...fetch: Resolve a query against one dataset and...messages: List the GRIB2 messages each file of a...pull: Fetch every source in a manifest and write...verify: Check cached files, or with --listing...doctor: Report the environment, reader extras,...cache: Inspect and prune the local file cache.
usdata cite
Print how to cite a dataset, or the inputs a manifest's lockfile pins.
Usage:
Arguments:
target: Dataset id, e.g. noaa:ghcn-daily, or a manifest path. [required]
Options:
--format <text|bibtex>: Rendering of the citations. [default: text]--json: Emit a JSON array of citation records and nothing else.--help: Show this message and exit.
usdata datasets
List the curated dataset registry, filtered.
Usage:
Options:
--provider <str>: Restrict to one provider, e.g. noaa.--domain <str>: Restrict to one domain, e.g. weather-radar.--format <str>: Delivered format, matched case-insensitively, e.g. csv.--reader <str>: Reader extra that opens the files (pandas, radar, netcdf, grib), or none.--capability <str>: Server-side capability the dataset declares (spatial_subset, place_subset, temporal_subset, variable_subset, partial_fetch).--status <str>: Support status to include: available, planned, all. [default: available]--json: Emit a JSON array of dataset records and nothing else.--help: Show this message and exit.
usdata search
Search the curated dataset registry.
Usage:
Arguments:
text: Free-text keywords.
Options:
--provider <str>: Restrict to one provider, e.g. noaa.--location, --state <str>: State, 'County, ST', or quoted FIPS code.--start <str>: ISO date or datetime.--end <str>: ISO date or datetime; a date alone runs to the end of that UTC day.--planned: Include planned datasets that have no adapter yet.--domain <str>: Restrict to one domain, e.g. weather-radar.--format <str>: Delivered format, matched case-insensitively, e.g. csv.--reader <str>: Reader extra that opens the files (pandas, radar, netcdf, grib), or none.--capability <str>: Server-side capability the dataset declares (spatial_subset, place_subset, temporal_subset, variable_subset, partial_fetch).--status <str>: Support status to include: available, planned, all. Supersedes --planned.--json: Emit a JSON array of dataset records and nothing else.--help: Show this message and exit.
usdata info
Show details for one dataset.
Usage:
Arguments:
dataset_id: Dataset id, e.g. noaa:nexrad-level2 [required]
Options:
--help: Show this message and exit.
usdata inspect
Show what a fetched file holds: its provenance, its format, and that format's detail.
Usage:
Arguments:
target: Cached file path, or a dataset and asset id as 'noaa:hrrr/<asset id>'. [required]
Options:
--cache-dir <path>: Override the cache directory.--json: Emit the summary as a JSON object and nothing else.--help: Show this message and exit.
usdata fetch
Resolve a query against one dataset and download the matching assets.
Usage:
Arguments:
dataset_id: Dataset id, e.g. noaa:ghcn-daily [required]
Options:
--location, --state <str>: State, 'County, ST', or quoted FIPS code.--bbox <str>: west,south,east,north in degrees.--lat <float>--lon <float>--radius-km <float>: Radius around --lat/--lon. [default: 50.0]--start <str>: ISO date or datetime.--end <str>: ISO date or datetime; a date alone runs to the end of that UTC day.--vars <str>: Comma-separated variable names.-p, --param <str>: Provider-specific key=value, repeatable.--cache-dir <path>: Override the cache directory.--force / --no-force: Re-download even if cached. [default: no-force]--no-progress / --no-no-progress: Disable terminal progress. [default: no-no-progress]--dry-run / --no-dry-run: List matching assets without downloading. [default: no-dry-run]--json: Emit a JSON array of records and nothing else on stdout.--help: Show this message and exit.
usdata messages
List the GRIB2 messages each file of a query holds, spelled as the messages param takes them.
One tab-separated line per field: asset id, message number, bytes, and the selector that names exactly that field. Only the index sidecars are read.
Usage:
Arguments:
dataset_id: Dataset id, e.g. noaa:hrrr [required]
Options:
--start <str>: ISO date or datetime.--end <str>: ISO date or datetime; a date alone runs to the end of that UTC day.-p, --param <str>: Provider-specific key=value, repeatable.--json: Emit a JSON array of listings and nothing else on stdout.--help: Show this message and exit.
usdata pull
Fetch every source in a manifest and write (or restore from) its lockfile.
Usage:
Arguments:
manifest: [required]
Options:
--cache-dir <path>: Override the cache directory.--force / --no-force: Ignore an existing lockfile: re-resolve every source and rewrite it. [default: no-force]--update <str>: Asset or dataset id whose pin should follow current upstream bytes; repeatable.--no-progress: Disable terminal progress.-q, --quiet: Print only the summary line, not one line per asset.--dry-run / --no-dry-run: List what every source would fetch, and its size, without downloading. [default: no-dry-run]--json: With --dry-run, emit the plan as JSON on stdout.--help: Show this message and exit.
usdata verify
Check cached files, or with --listing today's source listings, against the lockfile.
Exit 1 on any drift.
Usage:
Arguments:
manifest: [required]
Options:
--cache-dir <path>: Override the cache directory.--listing: Instead of the cache, compare the lockfile with what each source lists today; downloads nothing, but asks every source.--json: With --listing, emit the comparison as JSON on stdout.--help: Show this message and exit.
usdata doctor
Report the environment, reader extras, cache, and endpoints. Fixes nothing.
Usage:
Options:
--network: Also probe one upstream host per endpoint family.--json: Emit the report as a JSON object and nothing else.--help: Show this message and exit.
usdata cache
Inspect and prune the local file cache.
Usage:
Options:
--help: Show this message and exit.
Commands:
path: Print the cache directory, whether or not...list: List cached files with their size and when...size: Print how much room the cached data files...prune: Remove cached files by age or dataset,...
usdata cache path
Print the cache directory, whether or not it exists yet.
Usage:
Options:
--help: Show this message and exit.
usdata cache list
List cached files with their size and when they were retrieved.
Usage:
Options:
--dataset <str>: Restrict to one dataset id, e.g. noaa:ghcn-daily.--json: Emit a JSON array of cache records and nothing else.--help: Show this message and exit.
usdata cache size
Print how much room the cached data files take.
Usage:
Options:
--help: Show this message and exit.
usdata cache prune
Remove cached files by age or dataset, keeping what a lockfile here pins.
Usage:
Options:
--older-than <str>: Remove files at least this old: 30d, 12h, or P30D.--dataset <str>: Restrict to one dataset id, e.g. noaa:ghcn-daily.--dry-run: List what would be removed and remove nothing.--include-pinned: Also remove files a lockfile here pins.--help: Show this message and exit.