Commands Reference#

All commands require two flags:

• --data-path: Path to data directory
• --project: ESGF project name

Global Flags#

These persistent flags are available on every command:

--run-id is not global — it’s available on mapgen, stage, prepare, config, publish, unpublish, and cleanup, but not on freeze, or unfreeze (see each command below).

Output Directory Structure#

Each run’s files live under <output-dir>/<run-id>/. If --run-id is omitted, a timestamp (e.g. 20260918_143203) is generated and printed/used for that run; publish and unpublish fall back to the most recently created run-id under <output-dir> when --run-id is omitted.

<output-dir>/
└── <run-id>/
    ├── jobs/        # created by mapgen/prepare (SLURM .out/.err files)
    ├── logs/        # created by mapgen/stage/prepare (command logs)
    ├── mapfiles/    # written later by the mapgen SLURM job itself
    └── config/      # created only when publish runs
        └── <timestamp>/

--output-dir must match between prepare/mapgen/stage and the later publish/unpublish for the same dataset — otherwise the run-id auto-detection (or an explicit --run-id) won’t find the files created earlier.

Commands#

prepare#

Launch the mapgen and stage steps together.

./leapp prepare --data-path /path/to/data --project cmip6plus --run-id myrun1 --output-dir /path/to/output

This command:

1. Stages data to S3 directly (SSH+rclone or local rclone — not a SLURM job)
2. Launches mapgen as a SLURM job

config#

Generate the ESGF publishing config (esg.yaml) without publishing. Useful for inspecting or editing the config before running publish.

./leapp config --data-path /path/to/data --project cmip6plus --run-id myrun1 --output-dir /path/to/output

The file is written to <output-dir>/<run-id>/config/<timestamp>/esg_<project>_<run-id>.yaml.

publish#

Publish mapfiles to ESGF index node.

./leapp publish --data-path /path/to/data --project cmip6plus --run-id myrun1 --max-parallel 4 --output-dir /path/to/output

Pass the path printed by leapp config as --esg-config to publish using that exact file instead of regenerating it.

unpublish#

Remove published datasets from the ESGF index node.

./leapp unpublish --data-path /path/to/data --project cmip6plus --run-id myrun1

This command runs locally (not as a SLURM job) and executes immediately. Use with caution as it removes published datasets from the ESGF index.

If --run-id is not specified, the most recent run will be used.

Use cases:

• Cleaning up test publications
• Reverting incorrectly published datasets
• Unpublishing datasets before republishing with corrections

mapgen#

Generate ESGF mapfiles and checksums for the dataset.

./leapp mapgen --data-path /path/to/data --project cmip6plus --run-id myrun1 --output-dir /path/to/output

stage#

Stage data to S3 for ESGF publication. Runs directly (via SSH to a configured stage_host, or local rclone if not configured) — this is not a SLURM job.

./leapp stage --data-path /path/to/data --project cmip6plus --run-id myrun1 --output-dir /path/to/output

The stage operation is idempotent and can be safely retried.

cleanup#

Clean up old configuration files and directories.

./leapp cleanup --data-path /path/to/data --project cmip6plus --run-id myrun1

freeze#

Change ownership to restricted group with appropriate permissions.

./leapp freeze --data-path /path/to/data --group restricted_group --recursive

unfreeze#

Reset ownership to normal group with appropriate permissions.

./leapp unfreeze --data-path /path/to/data --group normal_group --recursive

version#

Print version, commit, and build time information.

./leapp version
# or
./leapp --version