gpm-cli API

Command-line interface for GNSSommelier — configuration, product search, probe, and download commands.

Application

gnss CLI entry point — assembles all subcommands and exposes main().

gpm_cli.app.main()[source]

Launch the gnssommelier CLI application.

Return type:: None

Configuration

User configuration for gnssommelier.

Config files use TOML format. Resolution order (highest priority last):

Compiled defaults

User config (~/.config/gnssommelier/config.toml)

Project config (gnssommelier.toml in project_dir)

Environment variables (GNSS_*)

Usage:

from gpm_cli.config import ConfigLoader, ENV_VAR, USER_CONFIG_PATH

cfg = ConfigLoader.load()
client = GNSSClient.from_defaults(**cfg.to_client_kwargs())

gpm_cli.config.ConfigLoader: alias of UserConfig

class gpm_cli.config.UserConfig(base_dir=None, centers=None, max_connections=4, log_level='WARNING')[source]

Bases: object

Resolved configuration for gnssommelier.

Parameters:

base_dir (str | Path | None)
centers (list[str] | None)
max_connections (int)
log_level (str)

property client: _ClientView

classmethod defaults()[source]

Return a config object populated entirely from compiled defaults.

Return type:: UserConfig

classmethod load(project_dir=None)[source]

Load and resolve configuration from all sources.

Parameters:: project_dir (Path | None) – Directory to search for gnssommelier.toml.
Returns:: Resolved UserConfig.
Return type:: UserConfig

reset()[source]

Remove the user config file, reverting to defaults on next load.

Return type:: None

classmethod reset_user_config()[source]

Remove the user config file.

Return type:: None

save()[source]

Persist current settings to the user config file.

Return type:: None

set(key, value)[source]

Set a single key and persist to the user config file.

Parameters:

key (str)
value (Any)

Return type:

None

to_client_kwargs()[source]

Return kwargs for GNSSClient.from_defaults().

Return type:: dict[str, Any]

classmethod update_user_config(updates)[source]

Deep-merge updates into the user config file.

Parameters:: updates (dict[str, Any])
Return type:: None

Commands

gnssommelier config — manage persistent user configuration.

Subcommands

init Interactive first-run wizard. show Display all current settings. set Update a key in the user config file. reset Remove the user config file. validate Check directories, center IDs, and server reachability.

Config file

All settings are stored in TOML at:

~/.config/gnssommelier/config.toml

A project-local override can live in gnssommelier.toml (the project directory). Set GNSS_CONFIG=/path/to/file.toml for a one-shot override.

TOML schema example:

log_level = "WARNING"
base_dir = "~/gnss_data"
max_connections = 4
centers = ["COD", "ESA", "GFZ"]

gpm_cli.cmd_config.config_init()[source]

Interactive first-run setup wizard.

Return type:: None

gpm_cli.cmd_config.config_reset(yes=False)[source]

Remove the user config file, reverting all settings to compiled defaults.

Parameters:: yes (Annotated[bool, <typer.models.OptionInfo object at 0x7aefd72d9340>])
Return type:: None

gpm_cli.cmd_config.config_set(key, values)[source]

Set a configuration value in the user config file.

Examples:

gnssommelier config set base-dir ~/gnss_data
gnssommelier config set centers COD ESA GFZ
gnssommelier config set max-connections 6
gnssommelier config set log-level DEBUG

Parameters:

key (Annotated[str, <typer.models.ArgumentInfo object at 0x7aefd7102630>])
values (Annotated[list[str], <typer.models.ArgumentInfo object at 0x7aefd7101190>])

Return type:

None

gpm_cli.cmd_config.config_show()[source]

Display all current configuration values, grouped by section.

Return type:: None

gpm_cli.cmd_config.config_validate(workers=6, no_connectivity=False, output_json=None)[source]

Check configured directories, center IDs, and server reachability.

Uses the same ConnectionPoolFactory the library uses internally — no GNSSClient required, so this works even before base-dir is configured. Pass –no-connectivity to skip the live server checks.

Parameters:

workers (Annotated[int, <typer.models.OptionInfo object at 0x7aefd71ea630>])
no_connectivity (Annotated[bool, <typer.models.OptionInfo object at 0x7aefd71eaa20>])
output_json (Annotated[Path | None, <typer.models.OptionInfo object at 0x7aefd71e8200>])

Return type:

None

gnssommelier search — search for GNSS products across analysis centers.

Examples:

gnssommelier search ORBIT --date 2025-01-15
gnssommelier search ORBIT --date 2025-01-15 --where TTT=FIN --where AAA=COD
gnssommelier search ORBIT --date 2025-01-01 --to 2025-01-07
gnssommelier search ORBIT --date 2025-01-15 --sources COD ESA GFZ
gnssommelier search ORBIT --date 2025-01-15 --json results.json

gpm_cli.cmd_search.search(product, date, to=None, where=None, sources=None, output_json=None)[source]

Search for IGS products matching the given criteria.

Exit code 0 if at least one result is found, 1 if nothing matches.

Parameters:

product (Annotated[str, <typer.models.ArgumentInfo object at 0x7aefd71ea0c0>])
date (Annotated[str, <typer.models.OptionInfo object at 0x7aefd71eb890>])
to (Annotated[str | None, <typer.models.OptionInfo object at 0x7aefd70f07d0>])
where (Annotated[list[str] | None, <typer.models.OptionInfo object at 0x7aefd70f0d10>])
sources (Annotated[list[str] | None, <typer.models.OptionInfo object at 0x7aefd70f1460>])
output_json (Annotated[Path | None, <typer.models.OptionInfo object at 0x7aefd70f00b0>])

Return type:

None

gnssommelier probe — check server connectivity or product availability.

Examples:

# Connectivity mode (no --date, no --product)
gnssommelier probe
gnssommelier probe --center WUM --center COD

# Product search mode (--date and/or --product provided)
gnssommelier probe --date 2025-01-15
gnssommelier probe --date 2025-01-15 --product ORBIT --product CLOCK
gnssommelier probe --date 2025-01-15 --center GFZ --workers 4
gnssommelier probe --date 2025-01-15 --json results.json

Exit code: 0 if all checks pass, 1 if any fail.

Note: CDDIS requires FTPS credentials in ~/.netrc:

machine gdc.cddis.eosdis.nasa.gov login <user> password <pass>

class gpm_cli.cmd_probe.ConnResult(server, centers, status, elapsed=0.0, note='')[source]

Bases: object

Result of probing a single remote server.

Parameters:

server (Server)
centers (list[str])
status (ConnStatus)
elapsed (float)
note (str)

centers: list[str]

elapsed: float = 0.0

note: str = ''

server: Server

status: ConnStatus

class gpm_cli.cmd_probe.ConnStatus(*values)[source]

Bases: str, Enum

Outcome of a server connectivity probe.

AUTH_REQUIRED = 'AUTH REQUIRED'

CONNECTED = 'CONNECTED'

ERROR = 'ERROR'

UNREACHABLE = 'UNREACHABLE'

class gpm_cli.cmd_probe.ProbeResult(center_id, product_name, status, filename='', n_found=0, elapsed=0.0, error='')[source]

Bases: object

Result of probing a single (center, product) pair.

Parameters:

center_id (str)
product_name (str)
status (SearchStatus)
filename (str)
n_found (int)
elapsed (float)
error (str)

center_id: str

elapsed: float = 0.0

error: str = ''

filename: str = ''

n_found: int = 0

product_name: str

status: SearchStatus

class gpm_cli.cmd_probe.SearchStatus(*values)[source]

Bases: str, Enum

Outcome of a product availability probe.

ERROR = 'ERROR'

FOUND = 'FOUND'

NOT_FOUND = 'NOT FOUND'

SKIPPED = 'SKIPPED'

gpm_cli.cmd_probe.probe(date=None, center=None, product=None, workers=8, output_json=None)[source]

Probe server connectivity or product availability in the GNSS catalog.

[bold]Connectivity mode[/bold] (no –date, no –product)

Attempt a connection against every registered server and report CONNECTED / AUTH REQUIRED / UNREACHABLE for each hostname.

[bold]Product search mode[/bold] (–date and/or –product provided)

For every (center, product) pair run a live directory listing and assert at least one file is found for the given date.

Parameters:

date (Annotated[str | None, <typer.models.OptionInfo object at 0x7aefd6f54b60>])
center (Annotated[list[str] | None, <typer.models.OptionInfo object at 0x7aefd6f54b00>])
product (Annotated[list[str] | None, <typer.models.OptionInfo object at 0x7aefd6f54c50>])
workers (Annotated[int, <typer.models.OptionInfo object at 0x7aefd6f54d40>])
output_json (Annotated[Path | None, <typer.models.OptionInfo object at 0x7aefd6f54ef0>])

Return type:

None

gnssommelier download — download GNSS products to the configured base directory.

Examples:

gnssommelier download ORBIT --date 2025-01-15
gnssommelier download ORBIT CLOCK ERP --date 2025-01-15
gnssommelier download ORBIT --date 2025-01-15 --sources COD ESA
gnssommelier download ORBIT --date 2025-01-15 --dry-run
gnssommelier download ORBIT --date 2025-01-15 --where TTT=FIN

gpm_cli.cmd_download.download(products, date, where=None, sources=None, dry_run=False)[source]

Download GNSS products to base-dir.

Already-cached files are skipped automatically. Exit code 0 if all requested products were found and downloaded.

Parameters:

products (Annotated[list[str], <typer.models.ArgumentInfo object at 0x7aefd6f6ae40>])
date (Annotated[str, <typer.models.OptionInfo object at 0x7aefd6f6ac30>])
where (Annotated[list[str] | None, <typer.models.OptionInfo object at 0x7aefd6f6a9c0>])
sources (Annotated[list[str] | None, <typer.models.OptionInfo object at 0x7aefd6f6a870>])
dry_run (Annotated[bool, <typer.models.OptionInfo object at 0x7aefd6f68620>])

Return type:

None