go-cds

Unofficial Go client for the Copernicus Climate Data Store API, modeled after the Python cdsapi client.

Features

• Reads config from CDSAPI_URL, CDSAPI_KEY, or ~/.cdsapirc
• Uses the same basic request flow as cdsapi.retrieve(...)
• Polls queued and running tasks until completion
• Supports resumable downloads for interrupted transfers
• Exposes task update, delete, status, remote, service, and workflow helpers
• Supports TOML or JSON driven download jobs and a ready-to-run CLI

Install

As a library:

go get github.com/skyviewor/go-cds

As a CLI:

go install github.com/skyviewor/go-cds/cmd/go-cds@latest

From source:

git clone https://github.com/skyviewor/go-cds.git
cd go-cds
make build
./bin/go-cds -config ./example.download.toml

Install AI Skill

This project can install bundled AI Skill definitions for Codex and Claude Code.

Global install:

go-cds install-skill codex --mode global
go-cds install-skill claudecode --mode global

From a local checkout:

go run ./cmd/go-cds install-skill codex --mode global
go run ./cmd/go-cds install-skill claudecode --mode global

Project-local install:

go-cds install-skill codex --mode local
go-cds install-skill claudecode --mode local

Reinstall and overwrite an older copy:

go-cds install-skill codex --mode global --force

--mode local installs into the current project directory. --mode global installs into the user's home-directory assistant path such as ~/.agents/skills/... or ~/.claude/skills/....

Configure

Create ~/.cdsapirc:

url: https://cds.climate.copernicus.eu/api
key: <PERSONAL-ACCESS-TOKEN>

Or set:

export CDSAPI_URL=https://cds.climate.copernicus.eu/api
export CDSAPI_KEY=<PERSONAL-ACCESS-TOKEN>

The client also accepts the older UID:APIKEY format and will automatically choose the right authentication mode.

Usage

Use the SDK when you want to embed CDS downloads into a Go program.

package main

import (
	"context"
	"log"

	cds "github.com/skyviewor/go-cds"
)

func main() {
	client, err := cds.NewClient()
	if err != nil {
		log.Fatal(err)
	}

	result, err := client.Retrieve(context.Background(), "reanalysis-era5-pressure-levels", map[string]any{
		"variable":        []string{"temperature"},
		"pressure_level":  []string{"1000"},
		"product_type":    []string{"reanalysis"},
		"year":            []string{"2017"},
		"month":           []string{"12"},
		"day":             []string{"01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31"},
		"time":            []string{"12:00"},
		"data_format":     "grib",
		"download_format": "unarchived",
	})
	if err != nil {
		log.Fatal(err)
	}

	if _, err := result.Download(context.Background(), "download.grib"); err != nil {
		log.Fatal(err)
	}
}

Config File + CLI

Use the CLI when you want to run downloads from a config file without writing Go code.

For new configs, prefer the current CDS request fields such as year / month / day and data_format. Legacy cdsapi-style fields like date and format are still accepted and converted internally when possible.

Example config: example.download.toml JSON example: example.download.json

dataset = "reanalysis-era5-pressure-levels"
target = "download.grib"

[client]
timeout_seconds = 60
retry_max = 10
sleep_max_seconds = 30

[request]
variable = ["temperature"]
pressure_level = ["1000"]
product_type = ["reanalysis"]
year = ["2017"]
month = ["12"]
day = ["01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31"]
time = ["12:00"]
data_format = "grib"
download_format = "unarchived"

Run it with:

go-cds -config ./example.download.toml

Or with JSON:

go-cds -config ./example.download.json

If you are working from a local checkout, you can also build a binary:

go build -o go-cds ./cmd/go-cds
./go-cds -config ./example.download.toml

Or use make:

make build
./bin/go-cds -config ./example.download.toml

Common targets:

make test
make fmt
make run CONFIG=./example.download.json
make install
make install-skill-codex-global
make install-skill-claude-global

make install defaults to /usr/local/bin. You can override that:

make install PREFIX=~/bin

Resume Demo

To see resumable download behavior locally without hitting CDS, run:

make demo-resume

This starts a local mock HTTP server that:

• sends only the first 10 bytes on the first download attempt
• closes the connection intentionally
• expects the client to retry with Range: bytes=10-

If resume is working, the logs will include a line like resuming download at byte 10.

Library-side, you can load and execute the same config directly:

job, err := cds.LoadJobConfig("example.download.toml")
if err != nil {
	log.Fatal(err)
}

_, err = cds.RunJob(context.Background(), job)
if err != nil {
	log.Fatal(err)
}

Notes

• This version supports both CDS Personal Access Tokens and the older UID:APIKEY format.
• The published module path is github.com/skyviewor/go-cds.