Command line¶
The canvodpy command runs canVODpy from the command line. This page
lists every command and option, and canvodpy COMMAND --help prints the same
text in the terminal. For a walk through a first run, see
Retrieve VOD.
Process GNSS observations into VOD and inspect the stores.
Usage:
$ canvodpy [OPTIONS] COMMAND [ARGS]...
Options:
--version: Show canvodpy's version and exit.--install-completion: Install completion for the current shell.--show-completion: Show completion for the current shell, to copy it or customize the installation.--help-all: Show every command with its options, and exit. One command with descriptions: canvodpy COMMAND --help; all of them: https://canvodpy.eu/api/cli/--help: Show this message and exit.
Commands:
run: Process GNSS observations into Icechunk...vod: Compute VOD for a range of days from the...vod-reconcile: List the dates that have observations but...doctor: Report canvodpy's version, its...dashboard: Launch the marimo performance dashboard...config: Create, check, show, and edit...store: Inspect the Icechunk stores of the sites...stac: Write the STAC catalog of every store...
canvodpy run¶
Process GNSS observations into Icechunk stores and compute VOD.
Exits with 0 when every receiver-day is written or skipped, 3 when the run finished but a receiver-day failed (the log says why), and 1 when the run stopped.
Usage:
$ canvodpy run [OPTIONS]
Options:
--site <str>: Site name, as defined under sites: in canvod-settings.yaml, for example ExampleSite. One site per run: for several sites, run canvodpy once per site, for example in a shell loop. [required]--start <str>: Start date in YYYYDOY format, for example 2025001. Needed unless --update-to-latest is given.--end <str>: End date in YYYYDOY format, for example 2025007. If omitted, processes up to today.--update-to-latest: Process the days from the last stored day up to the latest day with files, instead of --start and --end. Starts on the earliest last stored day among the receivers with new files (after that day, or on it but not stored yet), so a retired receiver doesn't hold it back.--no-vod / --vod: Skip the VOD calculation: only write the observations to the GNSS store. [default: vod]--label <str>: Free-text label of the run, stored in the run history, for example to group the repetitions of a benchmark.--dry-run / --no-dry-run: Preview processing plan without executing. [default: no-dry-run]--workers <int>: Number of worker processes. Default: from the resource settings in canvod-settings.yaml.-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --config <str>: Settings file whose values replace those of canvod-settings.yaml.--ephemeris-source <final|broadcast>: Where the satellite orbits and clocks come from: final uses the SP3 and CLK products of an analysis center, broadcast uses the SatVisibility blocks of the SBF files. Default: from canvod-settings.yaml.--vod-calculator <tau_omega>: VOD calculator to use. [default: tau_omega]--write-catalog: After the run, write the latest STAC catalog of every store under the data root, ascanvodpy stac writedoes.--dashboard: Start the marimo performance dashboard next to this run, in a process of its own. Its startup messages go to a log file, not to this terminal.--dashboard-host <str>: Host for --dashboard to bind to. [default: 127.0.0.1]--dashboard-port <int>: Port for --dashboard to bind to. Default: a free port that the operating system picks.--dashboard-stop-at-end: Stop the dashboard of --dashboard when the run ends. Default: it stays up to show the finished run until you shut it down with its button.--help: Show this message and exit.
canvodpy vod¶
Compute VOD for a range of days from the GNSS store of a site, one day per worker. Days stored from the same GNSS files are skipped; days without data are listed.
Usage:
$ canvodpy vod [OPTIONS]
Options:
--site <str>: Site name, as defined under sites: in canvod-settings.yaml [required]--analysis <str>: VOD analysis name, as defined in site.vod_analyses [required]--start <str>: First day in YYYYDOY format, for example 2025001. Default: the first day of the GNSS store.--end <str>: Last day in YYYYDOY format, for example 2025007. Default: the last day of the GNSS store.--calculator <tau_omega>: VOD calculator to use. [default: tau_omega]-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
canvodpy vod-reconcile¶
List the dates that have observations but no VOD, and compute it with --execute.
Usage:
$ canvodpy vod-reconcile [OPTIONS]
Options:
--site <str>: Site name, as defined under sites: in canvod-settings.yaml [required]--analysis <str>: VOD analysis name, as defined in site.vod_analyses [required]--calculator <tau_omega>: VOD calculator to use. [default: tau_omega]--execute: Compute the VOD of the dates found. Without this flag, the command only reports them.-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
canvodpy doctor¶
Report canvodpy's version, its environment, and its configuration directory.
Usage:
$ canvodpy doctor [OPTIONS]
Options:
-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
canvodpy dashboard¶
Launch the marimo performance dashboard for the pipeline's logs.
Usage:
$ canvodpy dashboard [OPTIONS]
Options:
--logs-dir <str>: Log folder of the runs to show. Default: processing.logging.log_dir in canvod-settings.yaml.--edit / --run: Open in marimo's editor instead of the read-only app view. [default: run]--host <str>: Host to bind to. Default: the marimo default, 127.0.0.1.-p, --port <int>: Port to bind to. Default: a port that marimo picks.--help: Show this message and exit.
canvodpy config¶
Create, check, show, and edit canvod-settings.yaml.
Usage:
$ canvodpy config [OPTIONS] COMMAND [ARGS]...
Options:
--config <path>: Settings file whose values replace those of canvod-settings.yaml.--help: Show this message and exit.
Commands:
init: Create canvod-settings.yaml from its...validate: Validate the configuration and the...show: Show the settings that canvodpy uses.edit: Open canvod-settings.yaml in $EDITOR.explain: Print what a setting of...
canvodpy config init¶
Create canvod-settings.yaml from its template, or from a store.
The file goes into the configuration directory that --config-dir sets. Create a naming recipe for each receiver with just naming-init SITE NAME.
With --from-store STORE, the file is written from the store's content settings (a folder or an s3:// URL): the settings that shape its data stay as they are, and the machine values are asked (or left as TODO with --no-interactive).
Usage:
$ canvodpy config init [OPTIONS]
Options:
-c, --config-dir <path>: Configuration directory, holding canvod-settings.yaml and recipes/. Default: $CANVOD_CONFIG_DIR, else config/ of the canvodpy checkout, else ~/.config/canvodpy.-f, --force: Overwrite existing files (no effect with --from-store)-i, --interactive: Walk through setup with a guided Q&A instead of hand-editing YAML--from-store <str>: Write the settings of a store from its content settings: a local dir or an s3://bucket/prefix URL--no-interactive: With --from-store: keep the machine-value placeholders (TODO) instead of asking--help: Show this message and exit.
canvodpy config validate¶
Validate the configuration and the receiver data it points to.
It finds the data files the same way as canvodpy run, so every error
it reports would stop a run or make its results wrong. A settings file
written from a store (:meth:init) that still has placeholder values is
listed, and the command exits with code 1.
Usage:
$ canvodpy config validate [OPTIONS]
Options:
-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --config <path>: Settings file whose values replace those of canvod-settings.yaml.--site <str>: Check the data of this site only. Repeat for several sites. Default: all sites.--check-sampling / --no-check-sampling: Read the first file of the first and the last day of each receiver and compare the sampling interval of its data with the one in its canonical name. [default: check-sampling]--help: Show this message and exit.
canvodpy config show¶
Show the settings that canvodpy uses.
Usage:
$ canvodpy config show [OPTIONS]
Options:
-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / -s, --section processing|sites|sids: Show this section only. Default: all sections.--help: Show this message and exit.
canvodpy config edit¶
Open canvod-settings.yaml in $EDITOR.
Usage:
$ canvodpy config edit [OPTIONS]
Options:
-c, --config-dir <path>: Configuration directory, holding canvod-settings.yaml and recipes/. Default: $CANVOD_CONFIG_DIR, else config/ of the canvodpy checkout, else ~/.config/canvodpy.--help: Show this message and exit.
canvodpy config explain¶
Print what a setting of canvod-settings.yaml means.
Prints the setting's description, type, limits and default, and a link to its entry in the settings reference. Name a site, receiver or VOD analysis as in your file: sites.my_site.receivers.reference_01.directory.
Usage:
$ canvodpy config explain [OPTIONS] {setting}
Arguments:
setting: The setting's path in canvod-settings.yaml, or the end of it (for example gnss_store.epoch). [required]
Options:
--help: Show this message and exit.
canvodpy store¶
Inspect the Icechunk stores of the sites and maintain them.
Usage:
$ canvodpy store [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
list: List every configured site's GNSS and VOD...info: Show branches, groups, and stats for one...log: Show the commit history as a graph, or the...maintain: Expire old snapshots of one site's store...maintain-due: Run only the store maintenance that's due,...migrate-metadata: Move a store written before repository...migrate-layout: Move a store written by appending files to...amend: Change the description of a site's store,...migrate: Move a site's stores from canVODpy 0.x to...
canvodpy store list¶
List every configured site's GNSS and VOD store paths and status.
Usage:
$ canvodpy store list [OPTIONS]
Options:
-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
canvodpy store info¶
Show branches, groups, and stats for one site's store.
Usage:
$ canvodpy store info [OPTIONS] {site}
Arguments:
site: Site name, as defined under sites: in canvod-settings.yaml [required]
Options:
--store gnss|vod: Store to open. [default: gnss]--branch <str>: Branch to inspect [default: main]--group <str>: Show the full content of one group: its dataset and its metadata table.-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
canvodpy store log¶
Show the commit history as a graph, or the store operations with --ops.
Usage:
$ canvodpy store log [OPTIONS] [site]
Arguments:
site: Site name, as defined under sites: in canvod-settings.yaml. Omit when using --path.
Options:
--store gnss|vod: Store of the site to open. Default: gnss. Not with --path.--path STORE: Open the store at this local path or s3://bucket/prefix instead of a site's store, for example a copy. Needs no settings file.--branch <str>: Show the history of this branch only. Default: all branches.--ops: Show the operations on the store instead of the commit graph.--limit <int>: Number of operations that --ops shows. [default: 50]--svg FILE: Write the commit graph to this SVG file instead of printing it.--plain: Draw the commit graph without colors, for a file or a CI log.-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
canvodpy store maintain¶
Expire old snapshots of one site's store and collect garbage.
Without --execute, this is a dry run: it reports what garbage collection would delete and how many snapshots of the main branch are older than the cutoff, and changes nothing. With --execute, it asks for confirmation, expires the old snapshots and, unless you pass --no-gc, collects garbage.
Don't run it while a canvodpy run writes to the same store.
On a store on S3, maintenance is a dry run only: a store there may be
written by several machines, so --execute is refused (exit 1) and
only the report is printed.
Usage:
$ canvodpy store maintain [OPTIONS] {site}
Arguments:
site: Site name, as defined under sites: in canvod-settings.yaml [required]
Options:
--store gnss|vod: Store to open. [default: gnss]--expire-days <int>: Keep the snapshots of this many past days. Use weeks to months, not hours. [default: 90]--gc / --no-gc: Run garbage collection [default: gc]--execute: Expire snapshots and collect garbage, after you confirm. Without this flag the command only reports and changes nothing.-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
canvodpy store maintain-due¶
Run only the store maintenance that's due, without prompting.
Use this command, not maintain, in scheduled jobs such as cron: it never asks for confirmation, and it exits with status 0 when nothing is due. It reads processing.storage.maintenance in canvod-settings.yaml and does nothing unless both of these hold:
- maintenance.enabled or maintenance.manifests_enabled is true. Both are false by default. Before you set them, run canvodpy store maintain SITE, which is a dry run, on your store and check its report.
- No canvodpy run is active on this computer.
maintenance.enabled allows snapshot expiry and garbage collection. Expiry is due when the last one ran more than maintenance.expire_interval_days ago, or never ran. Garbage collection is due maintenance.gc_delay_days after an expiry, once per expiry. maintenance.manifests_enabled allows manifest compaction, which is due when the store holds at least maintenance.manifest_count_threshold manifest files.
While maintenance.dry_run_until_confirmed is true, the default, a store that's due is only reported, not changed. Set it to false once the reports look right.
On a store on S3, maintenance is a dry run only: a store there may be written by several machines, so a due store is always reported, never changed, and this command still exits 0 (a cron job does not fail overnight).
Usage:
$ canvodpy store maintain-due [OPTIONS] [site]
Arguments:
site: Site name. Omit when using --all-sites.
Options:
--all-sites: Run for every site in canvod-settings.yaml.--store gnss|vod|both: Store to maintain. [default: both]-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
canvodpy store migrate-metadata¶
Move a store written before repository metadata to the current form.
Writes the store's description into its repository metadata, gives it a new store id, made of the site name in lowercase and the store kind, and a UUID, and keeps the old id in the migration record. Snapshots from before stay readable.
The migrated store must pass the standards checks: fields the store lacks, such as its description, are given with --set, otherwise the migration is refused and lists them. In a VOD store, the attributes of VOD are replaced with the current ones: older versions copied the attributes of SNR and theta to VOD, among them the valid range of theta. A VOD store also lists each VOD analysis it holds a group of, with its receivers from the settings. The migration record keeps who migrated the store, the initials set in processing.metadata.initials.
Fields the store lacks and the settings hold are taken from them: the site's store_description, the publisher and license, the site's latitude and longitude. A value given with --set wins.
canVODpy 0.x stored epochs without recording their time scale. The epochs of groups read from RINEX files are GPS time and are recorded as such; a VOD store's, when its site's GNSS store holds RINEX epochs only. A group read from SBF or NMEA files holds UTC epochs: the command stops, and the store is rebuilt from the raw files.
A GNSS or VOD store also gets its content settings (ADR 0019), also when it was moved to repository metadata before: the settings that shape its data, taken from the settings recorded in its first commit. A setting that commit does not record is not guessed: the command stops and lists it, to be given with --set by its key in canvod-settings.yaml. A setting the data show (the preprocessing, store_delta_snr, store_radial_diff, store_radial_distance) is read from the data: canVODpy 0.x recorded settings its runs didn't follow.
Usage:
$ canvodpy store migrate-metadata [OPTIONS] {site}
Arguments:
site: Site name, as defined under sites: in canvod-settings.yaml [required]
Options:
--store gnss|vod: Store to migrate. [default: gnss]--naming-authority <str>: Your institution's domain in reverse order, for example org.middle-earth. Default: the store's own, if it is a reverse DNS name; otherwise processing.metadata.naming_authority in the settings.--set field.path=value: A field or content setting the store lacks, for example identity.description=Beech forest site, or sites.my_site.receivers.reference_01.paired_canopies=[canopy_01]. Repeat for more.--yes: Migrate without asking.-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
canvodpy store migrate-layout¶
Move a store written by appending files to day blocks (ADR 0016).
Runs write day blocks only, so a store whose groups were written by
appending has to be moved first. Each such group is written again, day
by day: every day gets a block of slots at its cadence, the finest step
between its epochs. An epoch stored more than once keeps the entry
written last. The groups keep their attributes, log books and other
metadata, and get the chunks of the settings
(processing.icechunk.chunk_strategies).
Shows what it will do and asks first. Everything goes into one commit; snapshots from before stay readable. A store written before repository metadata is moved with canvodpy store migrate SITE.
Usage:
$ canvodpy store migrate-layout [OPTIONS] {site}
Arguments:
site: Site name, as defined under sites: in canvod-settings.yaml [required]
Options:
--store gnss|vod: Store to move. [default: gnss]--yes: Move without asking.-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
canvodpy store amend¶
Change the description of a site's store, with a reason.
Fixed fields (the store id, UUID, store type, source format, naming authority and creation date) never change. Each changed field is recorded with its old and new value, the reason, who and when, and a new commit carries the new description. Who is the initials set in processing.metadata.initials.
Usage:
$ canvodpy store amend [OPTIONS] {site}
Arguments:
site: Site name, as defined under sites: in canvod-settings.yaml [required]
Options:
--store gnss|vod: Store to amend. [default: gnss]--set field.path=value: New value of a field, for example identity.title=Rosalia GNSS observations. Repeat for more fields.--add-receiver name: Add a receiver of the site's settings to the store, so runs may write it.--add-vod-analysis name: Add a VOD analysis of the site's settings to the VOD store.--update-recipe name: Record a receiver's naming recipe of the settings and its sha256 in the GNSS store, after the recipe changed on purpose.--from <path>: YAML file with the keys reason, set (field paths and values), and the lists add_receivers, add_vod_analyses and update_recipes.--reason <str>: Why the fields change; recorded with each one.--yes: Amend without asking.-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
canvodpy store migrate¶
Move a site's stores from canVODpy 0.x to the current form, in one go.
- Folders: a store's folder is named by its kind (gnss, vod), with an optional suffix (vod-recompute). The GNSS store's old folder rinex is moved to gnss; any other folder whose name is not a kind is moved to the name given with --rename. The store id is taken from the new folder name.
- The GNSS store, then the VOD store: their metadata (migrate-metadata), and their groups to day blocks (migrate-layout).
- A GNSS store made with CLK files loses its clock variable and records fetch_clock: false; since v1.0.0 runs read no CLK files by default, and VOD doesn't use the clock. The VOD store records the GNSS store's new content-settings hash.
Shows the plan and asks once. Each step that is done already is skipped, so the command can run again after a step failed; migrate-metadata and migrate-layout rerun single steps. Snapshots from before stay readable in the store's history. Stores on S3 need no migration: canVODpy writes stores to S3 since v1.0.0 only.
Usage:
$ canvodpy store migrate [OPTIONS] {site}
Arguments:
site: Site name, as defined under sites: in canvod-settings.yaml [required]
Options:
--rename OLD=NEW: The new name of a store folder whose name is not its kind, for example vod_2024=vod-2024. rinex is moved to gnss without it. Repeat for more.--naming-authority <str>: As for migrate-metadata: your institution's domain in reverse order.--gnss-set field.path=value: A field or content setting the GNSS store lacks (migrate-metadata --set). Repeat for more.--vod-set field.path=value: A field or content setting the VOD store lacks (migrate-metadata --set). Repeat for more.--yes: Migrate without asking.-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
canvodpy stac¶
Write the STAC catalog of every store under the data root, or a release.
Usage:
$ canvodpy stac [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
write: Write the latest catalog of every store...release: Publish a release: tag every store under...
canvodpy stac write¶
Write the latest catalog of every store under the data root.
If a store cannot be described, nothing is written: the command lists every such store with its reason and exits with code 1.
Usage:
$ canvodpy stac write [OPTIONS]
Options:
--root <path>: Data root to catalog. Default: storage.stores_root_dir in the settings.-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
canvodpy stac release¶
Publish a release: tag every store under the data root and write its catalog.
TAG becomes an Icechunk tag on the current main of every store, and releases/TAG/ gets the catalog of that tag, each asset pinned to the tag and its snapshot. A release catalog is never changed afterwards. Nothing is tagged if a store cannot be described or already has the tag; if every store has the tag but the catalog is missing, only the catalog is written.
Usage:
$ canvodpy stac release [OPTIONS] {tag}
Arguments:
tag: Release tag, for example v2026.1; no '/'. [required]
Options:
--root <path>: Data root to catalog. Default: storage.stores_root_dir in the settings.-c, --config-dir <path|url>: Configuration directory, holding canvod-settings.yaml and recipes/, or the URL of a settings file in a GitHub repository, fetched by each run (https://raw.githubusercontent.com// / --help: Show this message and exit.
In the terminal¶
canvodpy --help-all lists every command with its options on one screen;
canvodpy COMMAND --help describes one command.
canvodpy without a command, canvodpy --version and canvodpy run
start with the canVODpy logo, the website, the version, the support
address, the author and the licence. The logo is shown only in an
interactive terminal at least 81 columns wide, never when the output
goes to a file, a pipe or a cron job. To turn it off, for example to
save the second it takes at the start of a run, set
CANVODPY_NO_BANNER=1.
The colours of the help, the messages and the progress bars follow the
terminal's background, dark or light. canVODpy asks the terminal for it,
which most current terminals answer, and otherwise reads COLORFGBG or
takes dark. If it picks the wrong one, set CANVODPY_TERMINAL_THEME=dark
or CANVODPY_TERMINAL_THEME=light. The colours avoid red and keep apart
with red-green colour blindness, and every status comes with its symbol:
✓ done, ⚠️ needs attention, ❌ failed. NO_COLOR=1 turns the colours
off. Log lines written to a file or a pipe carry no colour codes.
After canvodpy --install-completion, the command prints how to load
the completion in the open terminal (for example exec zsh), so you
don't need to open a new one.