CLI reference

The stac-catalog command has three subcommands. sync is just generate followed by load.

Command	What it does
generate	Read metadata (CSV or Google Sheets) and write STAC JSON to the output directory.
load	Upsert previously generated Collections and Items into pgSTAC.
sync	generate + load in one step.

Every command accepts --help for inline documentation.

stac-catalog generate

Generate STAC metadata from a source.

stac-catalog generate \
  --source csv \
  --input ./input \
  --output ./output

Option	Description
--config PATH	Path to the STAC YAML configuration file.
--source {csv,gsheet}	Override the configured metadata source.
--input PATH	Override the CSV input directory.
--output PATH	Override the output directory.
--titiler-url URL	Override the internal TiTiler URL used to call TiTiler.
--titiler-public-url URL	Override the public TiTiler URL written into STAC metadata.

stac-catalog load

Load generated STAC JSON into pgSTAC (upsert).

stac-catalog load --output ./output

Option	Description
--config PATH	Path to the STAC YAML configuration file.
--output PATH	Override the generated STAC output directory to load from.
--dsn DSN	Override the pgSTAC PostgreSQL connection string.
--prod	Run the load inside the production Docker network (see --prod).

load reads collections.json and items.ndjson from the output directory.

stac-catalog sync

Generate and then load, in one command.

stac-catalog sync \
  --source csv \
  --input ./input \
  --output ./output

Option	Description
--config PATH	Path to the STAC YAML configuration file.
--source {csv,gsheet}	Override the configured metadata source.
--input PATH	Override the CSV input directory.
--output PATH	Override the output directory.
--titiler-url URL	Override the internal TiTiler URL.
--titiler-public-url URL	Override the public TiTiler URL written into STAC metadata.
--dsn DSN	Override the pgSTAC PostgreSQL connection string.
--prod	Run the sync inside the production Docker network (see --prod).

--prod

--prod keeps PostgreSQL private on the Docker network for production. Instead of connecting from the host, the CLI runs the database-dependent step inside the generator container, where pgSTAC is reachable as db:5432.

# Load previously generated output in production
stac-catalog load --prod

# Generate + load CSV metadata in production
stac-catalog sync --prod --source csv

# Generate + load from a Google Sheet in production
stac-catalog sync --prod --source gsheet --config stac-config.yaml

Production uses the standard mounted paths, and the CLI sets them for you:

host              generator container
./input       →   /data/input
./output      →   /data/output

:::caution Constraints with --prod

• Do not pass --input, --output, or --dsn — the production mounts and the private database connection are used automatically.
• Google Sheets production sync requires --config; the CLI mounts the config file and the referenced credentials into the generator container automatically (credentials must be inside the config file's directory).
• --prod requires Docker to be available on the host. :::

Examples

# Generate only (no database needed)
stac-catalog generate --source csv --input ./input --output ./output

# Generate from a config file
stac-catalog generate --config stac-config.yaml

# Load generated output with an explicit DSN
stac-catalog load --output ./output --dsn postgresql://postgres:stac@localhost:5432/stac

# Full local pipeline
stac-catalog sync --source csv --input ./input --output ./output

# Production pipeline (private DB)
stac-catalog sync --prod --source csv

Exit codes

stac-catalog prints a clear error to stderr and exits non-zero on failure, pointing you to stac-catalog <command> --help. Pressing Ctrl+C during a run exits with code 130.