Copernicus Marine Service - CLI

A command-line tool for downloading and converting Copernicus Marine Service datasets to GeoTIFF format. This tool simplifies access to oceanographic data including currents, waves, wind, and scalar parameters.

Table of Content

• Features
• Installation
• Configuration
• Usage
• Commands Overview
• Examples
• Architecture
• Development
• License

Features

• Download Copernicus Marine Service datasets in NetCDF format
• Convert ocean parameters to GeoTIFF format with spatial interpolation
• Generate specialized GeoTIFFs for:
  • Ocean currents (speed and direction)
  • Wave parameters (height and direction)
  • Wind data (speed and direction)
  • Scalar parameters (temperature, salinity, etc.)
• Configurable spatial resolution and bounding boxes
• Command-line interface for automation and scripting

Installation

Requires: Python >=3.12

End User Installation

Install via pip:

pip install cms-cli

Or using uv (recommended):

uv pip install cms-cli

Configuration

Before using the CLI, you need to configure your Copernicus Marine Service credentials.

Usage as library

Create a .env file in the root directory of your project with the following content:

CMS_USER
CMS_PASSWORD

Or set them as environment variables:

export CMS_USER="your_username"
export CMS_PASSWORD="your_password"

Development Installation

1. Copy the .env.example file to .env:

   cp .env.example .env
   

2. Edit .env and add your credentials:

   nano .env  # Or use any text editor
   

You can obtain credentials by registering at the Copernicus Marine Service.

Usage

After installation, run the CLI using:

cms-cli --help

Development Installation

For contributing or development:

git clone https://github.com/EomapCompany/cms-cli
cd cms-cli

# Install with all development dependencies
uv sync --all-groups

Run tests:

uv run pytest tests/ -v

Commands Overview

Command	Description
download-netcdf	Download original dataset with multiple parameters in NetCDF format
create-scalar-geotiffs	Download dataset and create GeoTIFFs for scalar parameters (e.g., temperature, salinity)
create-current-geotiffs	Download dataset and create current GeoTIFFs (speed and direction)
create-wave-geotiffs	Download dataset and create wave GeoTIFFs (height and direction)
create-wind-geotiffs	Download dataset and create wind GeoTIFFs (speed and direction)

Examples

Download NetCDF data

cms-cli download-netcdf \
  --dataset-id cmems_mod_glo_phy_my_0.083deg_P1D-m \
  --variables thetao \
  --start-date 2024-01-01 \
  --end-date 2024-01-31 \
  --output-dir ./data

Create scalar GeoTIFFs

cms-cli create-scalar-geotiffs \
  --dataset-id cmems_mod_glo_phy_my_0.083deg_P1D-m \
  --variable thetao \
  --start-date 2024-01-01 \
  --end-date 2024-01-31 \
  --resolution 1000 \
  --output-dir ./output

Create current GeoTIFFs with bounding box

cms-cli create-current-geotiffs \
  --dataset-id cmems_mod_glo_phy_my_0.083deg_P1D-m \
  --u-variable uo \
  --v-variable vo \
  --start-date 2024-01-01 \
  --end-date 2024-01-31 \
  --bbox -10 35 5 45 \
  --resolution 1000 \
  --output-dir ./currents

Architecture

C4 diagrams live in docs/architecture:

• Container diagram (level 2) – the cms-cli tool (this repo's only deployable unit), the EOMAP repos that import it as a library (eoapp-cms-rastless, navico-product), and the third-party services it calls (Copernicus Marine Service, a public water-polygon dataset).

cms-cli is a Python package/CLI, not a running service: it logs into Copernicus Marine Service, downloads NetCDF ocean data for an AOI and date range, and converts it into GeoTIFFs, optionally upscaling resolution against a water mask fetched from a public dataset. It is published to PyPI and both installed directly by operators and imported as a library by other EOMAP repos.

Development

Running Tests

uv run pytest tests/ -v

Code Quality

This project uses ruff for linting and formatting:

uv run ruff check .
uv run ruff format .

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0) - see the LICENCE.md file for details.

Copyright (c) 2025 EOMAP

Acknowledgments

This tool uses the Copernicus Marine Service API to access ocean data.