Skip to content

Command line

stacs verify   --config stacs.toml --out-dir verify_report/   # changes nothing
stacs register --config stacs.toml --mode drift               # what the API lacks or serves stale
stacs register --config stacs.toml --mode all --dryrun
stacs register --config stacs.toml --mode ids --ids-file ids.txt
stacs audit    --config stacs.toml --dir build/items/ --expect 120
stacs validate --dir build/items/

# Repositories that register their own build output directly -- collection first:
stacs load collection --config stacs.toml build/items/collection.json
find build/items -name '*.json' ! -name collection.json \
  | stacs load items --config stacs.toml

load checks every item against the declared collection and asset rules before sending, and refuses an id that appears twice; it exits 1 if there was nothing to load.

--dryrun writes nothing, and it still reaches the host, and for register the API too. register asks the API for one item of the collection, and both commands run ssh <host> true, so a dryrun that passes means they answered, and one that cannot reach them exits 1. It then stops: all and ids before fetching any item body, drift after comparing every body with the API but before the asset audit, load after its checks. None of them runs the script on the host, so the env file, pypgstac and the database check are first exercised by a real load. When verify reports the collection same, stacs load collection with a downloaded copy of the published collection.json is the smallest real load: it upserts the body the database already holds.

verify exits 1 on any drift and writes missing.txt, changed.txt, orphaned.txt and collection_state.txt to --out-dir, and queryables_missing.txt and queryables_changed.txt when queryables are declared. register refuses before writing wherever it can: a collection id that does not match the published collection.json, an item link duplicated or pointing at a body that names another id, a body that could not be fetched, an item that fails the audit, an unreachable host.

ids mode checks only the ids it registered. If collection.json changed, run verify after it: pgstac serves items hydrated against their collection, so a collection change can change how untouched items read back. all, and a drift whose collection changed, re-compare the whole catalogue after writing for that reason.

What it assumes

  • The STAC API is stac-fastapi on pgstac, or speaks its paging dialect: POST /search with collections, ids, limit and fields, the continuation token in the next link's body.
  • Items are linked from collection.json with rel: item, and an item's id is its file name without .json, with %20 read as a space. Child catalogues are refused, not skipped.
  • The STAC host has bash and a pypgstac that can reach the database.
  • Where queryables are declared, the API has the filter extension enabled. A 404 for an existing collection's queryables is reported as the extension missing, never as "none served".