Skip to content

CLI

Generate configs

Create starter templates for both workflow and dataset:

deep-code generate-config                 # writes to current directory
deep-code generate-config -o ./configs    # custom output folder

Lint a dataset

Validate dataset metadata before publishing:

deep-code lint-dataset my-dataset.zarr

Checks that the dataset has all metadata required for a valid OSC STAC collection:

  • description attribute present in dataset.attrs — if missing, publishing falls back to "No description available."
  • gcmd_keyword_url attribute present on every data variable — if missing, publishing will prompt you to enter a URL for each affected variable interactively

Run this beforehand to spot and fix metadata gaps before they interrupt the publish flow.

Publish metadata

Publish dataset, workflow, or both (default is both) to the target environment:

deep-code publish dataset.yaml workflow.yaml                 # production (default)
deep-code publish dataset.yaml workflow.yaml -e staging      # staging
deep-code publish dataset.yaml -m dataset                    # dataset only
deep-code publish workflow.yaml -m workflow                  # workflow only
deep-code publish --dataset-config ./ds.yaml --workflow-config ./wf.yaml -m all

Options: - --environment/-e: production (default) | staging | testing - --mode/-m: all (default) | dataset | workflow - --dataset-config / --workflow-config: explicitly set paths and bypass auto-detection

How publishing works

  1. Reads your configs and builds dataset STAC collections plus variable catalogs.
  2. Links the dataset's data. By default the OSC collection links to the dataset's PRR collection, so generate and ingest the PRR collection before publishing to OSC. For datasets not in PRR, set stac_catalog_s3_root and deep-code writes and links a STAC catalog on S3 instead (see Data links).
  3. Builds workflow and experiment OGC API Records.
  4. Forks/clones the target metadata repo (production, staging, or testing), commits generated JSON, and opens a pull request on your behalf.

The pull request description includes a "Generated with deep-code" attribution note.

Generate a PRR collection

Generate a Project Results Repository (PRR) STAC collection as local files, ready to submit to the ESA EarthCODE PRR endpoint:

deep-code generate-prr-collection dataset.yaml            # writes to prr/<collection_id>
deep-code generate-prr-collection dataset.yaml -o ./prr   # custom output directory

This reuses the same dataset config as publish, but writes only local files and needs no GitHub credentials or S3 write access (it only reads the Zarr store). It produces a self-contained Collection → Item → Assets tree:

prr/
└── {collection_id}/
    └── collection.json            # STAC Collection (root)
    └── items
        └── {item_id_0}.json       # datacube Item (whole Zarr)
        └── {item_id_1}.json       # datacube Item (whole Zarr)
  • The Item carries the datacube extension (cube:dimensions / cube:variables extracted from the Zarr) plus zarr-data and zarr-consolidated-metadata assets.
  • The Collection carries the OSC, Scientific, Processing, Themes and CF extensions and the PRR-mandatory fields.
  • deep-code publish still publishes one dataset/item at a time; the multi-item generator support is exposed first through the lower-level API and the PRR helper.

The output conforms to the PRR collection specification when the PRR fields are set in the config. If any required field is missing, the command still runs but logs a warning listing what is needed for full conformance. See PRR collection fields. Before sending the collection JSON to the PRR team, you can validate the generated collection using the PRR STAC Collection Editor.

Options:

  • --output-dir/-o: directory to write the tree into. Defaults to prr.