Skip to content

Getting Started

Installation

Install from PyPI:

pip install cdsswarm

For YAML request file support:

pip install "cdsswarm[yaml]"

For development (tests, linting, type checking):

git clone https://github.com/bgiebl/cdsswarm.git
cd cdsswarm
pip install -e ".[dev]"

Shell Completion

Enable tab completion for bash:

echo 'eval "$(cdsswarm completion bash)"' >> ~/.bashrc

Or for zsh:

echo 'eval "$(cdsswarm completion zsh)"' >> ~/.zshrc

Restart your shell or run source ~/.bashrc (or ~/.zshrc) to activate.

Prerequisites

You need a valid CDS API configuration file at ~/.cdsapirc:

url: https://cds.climate.copernicus.eu/api
key: <your-personal-access-token>

See the CDS API documentation for setup instructions.

First Download

1. Create a request file

Save the following as requests.json:

[
  {
    "dataset": "reanalysis-era5-single-levels",
    "request": {
      "product_type": ["reanalysis"],
      "variable": ["2m_temperature"],
      "year": ["2024"],
      "month": ["01"],
      "day": ["01", "02", "03"],
      "time": ["12:00"],
      "data_format": "grib"
    },
    "target": "temperature_jan.grib"
  },
  {
    "dataset": "reanalysis-era5-single-levels",
    "request": {
      "product_type": ["reanalysis"],
      "variable": ["total_precipitation"],
      "year": ["2024"],
      "month": ["01"],
      "day": ["01", "02", "03"],
      "time": ["12:00"],
      "data_format": "grib"
    },
    "target": "precipitation_jan.grib"
  }
]

2. Run the download

cdsswarm requests.json --workers 4

If your terminal supports it, the interactive TUI will launch automatically. Otherwise cdsswarm falls back to script mode with plain-text output.

3. Check the results

Downloaded files appear in the current directory (or in --output-dir if specified). If a download is interrupted, just rerun the same command — cdsswarm resumes from where it left off.

What's Next