CLI Commands

Complete reference for all CruisePlan command-line tools.

Commands follow the typical cruise planning workflow:

  1. Setup — download bathymetry data once before using the tool

  2. Pre-cruise planning — collect historical data, place stations, process configuration, generate schedule

  3. Individual processing steps — fine-grained control over enrichment, validation, and mapping

  4. At sea — generate rolling workplans from a live schedule

—

Setup

cruiseplan bathymetry

Download a bathymetry dataset. Run this once before using any command that draws maps or looks up water depths.

Without the file for the chosen --bathy-source, commands still run: each depth lookup returns the fill value -9999.0 and a warning names the missing file and the command that fetches it. No other dataset is substituted. Maps are drawn without bathymetry. The enriched YAML records the source and the number of filled depths under bathymetry_provenance.

cruiseplan bathymetry [-h] [--citation] [-o OUTPUT_DIR]
                      [--bathy-source SOURCE] [--verbose]

Options:

  • --bathy-source SOURCE: Dataset to download. Choices:

    • etopo2022 — ETOPO 2022, 60 arc-second resolution (~500 MB)

    • gebco2025 — GEBCO 2025, 15 arc-second resolution (~7.5 GB) (default)

    • msm142, msm142_jj, msm142_dt — local regional files; not downloaded, only checked for in the output directory

    gebco2023 is not a choice here: there is no download for it. Place GEBCO_2023.nc in the bathymetry directory by hand to use --bathy-source gebco2023 in the other commands.

  • -o, --output-dir DIR: Save location (default: data/bathymetry)

  • --citation: Print the data citation for the chosen source; does not download

Examples:

# Download default GEBCO 2025 data
cruiseplan bathymetry

# Download the smaller ETOPO 2022 dataset
cruiseplan bathymetry --bathy-source etopo2022

# Show citation without downloading
cruiseplan bathymetry --bathy-source gebco2025 --citation

—

Pre-cruise Planning

cruiseplan pangaea

Search PANGAEA for historical station data in a geographic area, or process an existing list of PANGAEA DOIs. Useful for finding prior cruise tracks in your study region before planning new stations.

Two modes of operation:

  • Search mode (--lat and --lon required): query PANGAEA and download matching datasets

  • DOI file mode: provide a .txt file of DOIs to download directly

cruiseplan pangaea [-h] [--lat MIN MAX] [--lon MIN MAX] [--limit N]
                   [-o OUTPUT_DIR] [--output NAME]
                   [--rate-limit RATE] [--merge-campaigns] [--verbose]
                   query_or_file

Arguments:

  • query_or_file: Search query string (e.g. "CTD North Atlantic") or path to a .txt DOI file

Options:

  • --lat MIN MAX: Latitude bounds in decimal degrees N (required for search mode)

  • --lon MIN MAX: Longitude bounds in decimal degrees E (required for search mode)

  • --limit N: Maximum search results (default: 10; recommended maximum: 100)

  • -o, --output-dir DIR: Output directory (default: data)

  • --output NAME: Base filename for outputs, without extension

  • --rate-limit RATE: PANGAEA API requests per second (default: 1.0)

  • --merge-campaigns: Combine datasets from the same campaign name (always on; the flag currently has no effect and merging cannot be disabled from the CLI)

Outputs: {name}_dois.txt (search mode) and {name}_stations.pkl

Examples:

# Search for CTD profiles in the subpolar North Atlantic
cruiseplan pangaea "CTD" --lat 50 65 --lon -40 -10 --output north_atlantic

# Process an existing DOI list
cruiseplan pangaea my_dois.txt --output processed

cruiseplan stations

Interactive station placement tool. Opens a matplotlib map window where you can place point stations, draw line transects, and define area operations. Saves the result as a YAML cruise configuration file: stations.yaml by default, {config}_stations_edited.yaml when editing CONFIG_FILE, or {pangaea}_stations.yaml when -p is given.

Optionally loads a PANGAEA .pkl file to show historical stations as background context.

cruiseplan stations [-h] [-p PANGAEA_FILE]
                    [--lat MIN MAX] [--lon MIN MAX] [--overwrite]
                    [-o OUTPUT_DIR]
                    [--bathy-source SOURCE] [--bathy-dir DIR]
                    [--bathy-stride N] [--bathy-contours DEPTH [DEPTH ...]]
                    [--max-depth METRES] [--verbose]
                    [CONFIG_FILE]

Arguments:

  • CONFIG_FILE: Existing YAML file to load and edit (optional; omit to start fresh)

Options:

  • -p, --pangaea-file FILE: PANGAEA stations pickle file (from cruiseplan pangaea)

  • --lat MIN MAX: Initial map latitude extent in decimal degrees N (default: 45 70)

  • --lon MIN MAX: Initial map longitude extent in decimal degrees E (default: -65 -5)

  • --overwrite: Overwrite the output file without prompting

  • -o, --output-dir DIR: Output directory (default: data)

  • --bathy-source SOURCE, --bathy-dir DIR: Bathymetry dataset and directory (defaults: gebco2025, data/bathymetry)

  • --bathy-contours DEPTH [DEPTH ...]: Contour depths in metres; replaces defaults

  • --bathy-stride N: Bathymetry downsampling factor; higher is faster (default: 10)

  • --max-depth METRES: Depth ceiling for colour scale (useful for shelf seas)

Interactive controls:

  • n: Navigation mode (pan/zoom, no placement)

  • p (or w): Place point stations

  • l (or s): Draw line transects

  • a: Define area operations; press a again to close the current area

  • u: Undo last operation

  • r: Remove an item by clicking it

  • y: Save to YAML (the window stays open)

  • Escape: Exit without saving

Examples:

# New cruise, North Atlantic region
cruiseplan stations --lat 58 65 --lon -35 -15 -o data/

# Edit an existing configuration
cruiseplan stations data/MSM142_draft.yaml

# With PANGAEA historical context
cruiseplan stations --lat 58 65 --lon -35 -15 \
    -p data/north_atlantic_stations.pkl

cruiseplan run

Full pipeline in one step: enrich, validate, map, and schedule. Equivalent to running cruiseplan process followed by cruiseplan schedule, but enrichment runs once and the enriched YAML is passed directly to the scheduler.

cruiseplan run [-h] [-o OUTPUT_DIR] [--leg LEG]
               [--bathy-source SOURCE]
               [--bathy-dir BATHY_DIR] [--bathy-stride N]
               [--bathy-contours DEPTH [DEPTH ...]]
               [--max-depth METRES] [--lat MIN MAX] [--lon MIN MAX]
               [--figsize WIDTH HEIGHT]
               [--no-ports] [--no-title] [--no-labels] [--no-legend]
               [--eez] [--verbose]
               CONFIG_FILE

Positional arguments:

  • CONFIG_FILE: Raw YAML cruise configuration file

Output options:

  • -o, --output-dir: Output directory for all files (default: data)

  • --leg: Generate schedule for a specific leg only

Bathymetry options (same as cruiseplan process):

  • --bathy-source: Dataset for depths and PNG maps: etopo2022, gebco2023, gebco2025, msm142, msm142_jj, msm142_dt (default: gebco2025)

  • --bathy-dir: Directory containing bathymetry files (default: data/bathymetry)

  • --bathy-stride: Downsampling factor — 1 = full resolution, higher = faster (default: 10)

  • --bathy-contours DEPTH [DEPTH ...]: Contour depths in metres; replaces defaults

  • --max-depth METRES: Maximum depth for colour scale

Map display options (applied to both process and schedule maps):

  • --lat MIN MAX, --lon MIN MAX: Map extent bounds

  • --figsize WIDTH HEIGHT: Figure size in inches

  • --no-ports: Exclude port markers

  • --no-title: Omit title

  • --no-labels: Omit station name labels

  • --no-legend: Omit legend

  • --eez: Overlay EEZ boundaries (visualization only; data downloaded on first use)

Examples:

cruiseplan run cruise.yaml
cruiseplan run cruise.yaml -o results/ --eez
cruiseplan run cruise.yaml --leg leg1 --bathy-source gebco2025

cruiseplan process

Unified configuration processing pipeline: enrichment + validation + map generation in one command. This is the main pre-cruise processing step. Run it after cruiseplan stations to add water depths, check the configuration for errors, and produce a preview map.

cruiseplan process [-h] [--no-enrich] [--no-validate] [--no-map]
                   [--no-depths] [--no-coords] [--no-sections]
                   [--no-depth-check] [--tolerance TOLERANCE]
                   [-o OUTPUT_DIR] [--output OUTPUT]
                   [--format FORMAT [FORMAT ...]]
                   [--bathy-source SOURCE] [--bathy-dir DIR]
                   [--bathy-stride N]
                   [--bathy-contours DEPTH [DEPTH ...]]
                   [--max-depth METRES]
                   [--lat MIN MAX] [--lon MIN MAX]
                   [--figsize WIDTH HEIGHT]
                   [--no-ports] [--no-title] [--no-labels] [--no-legend]
                   [--eez]
                   [--verbose] [--quiet]
                   CONFIG_FILE

Arguments:

  • CONFIG_FILE: Input YAML cruise configuration file

Pipeline control:

  • --no-enrich: Skip enrichment step

  • --no-validate: Skip validation step

  • --no-map: Skip map generation step

Enrichment options (used when --no-enrich is not set):

  • --no-depths: Skip adding bathymetry depths to stations

  • --no-coords: Skip adding formatted coordinate fields

  • --no-sections: Skip expanding CTD sections into individual stations

Validation options:

  • --no-depth-check: Skip checking whether existing depths match bathymetry

  • --tolerance TOLERANCE: Acceptable depth discrepancy in percent (default: 10.0)

Output options:

  • -o, --output-dir DIR: Output directory (default: data)

  • --output NAME: Base filename for all outputs (default: derived from cruise name)

  • --format FORMAT [FORMAT ...]: Map formats to generate: png kml (space-separated; omit to generate all)

  • --quiet, -q: Reduce console output

Bathymetry options:

  • --bathy-source SOURCE, --bathy-dir DIR: Dataset and directory used for depths and maps (defaults: gebco2025, data/bathymetry)

  • --bathy-stride N: Downsampling factor for map bathymetry (default: 10)

Map display options:

  • --figsize WIDTH HEIGHT: Figure size in inches (default: 10 8.1)

  • --lat MIN MAX, --lon MIN MAX: Map extent in decimal degrees

  • --max-depth METRES: Depth ceiling for bathymetry colour scale

  • --bathy-contours DEPTH [DEPTH ...]: Contour depths in metres

  • --no-ports, --no-title, --no-labels, --no-legend: Suppress map elements

  • --eez: Overlay EEZ boundaries on PNG map (visualization only; data downloaded on first use)

What it produces:

  • Enriched YAML: {name}_enriched.yaml

  • PNG map: {name}_map.png

  • KML file: {name}_catalog.kml

Examples:

# Full processing pipeline (recommended first run)
cruiseplan process data/MSM142_stations.yaml

# Skip map generation (faster; useful for validation only)
cruiseplan process data/MSM142_stations.yaml --no-map

# Custom output directory and filename
cruiseplan process data/MSM142_stations.yaml -o results/ --output MSM142

# Generate only PNG, not KML; restrict map extent
cruiseplan process data/MSM142_stations.yaml --format png \
    --lat 58 68 --lon -35 -10

cruiseplan schedule

Generate a cruise schedule from an enriched YAML configuration. Produces a NetCDF schedule file (required for cruiseplan list and cruiseplan forecast) plus optional HTML, LaTeX, CSV, and PNG outputs.

Run cruiseplan process first to produce the enriched YAML input.

cruiseplan schedule [-h] [--leg LEG] [--derive-netcdf]
                    [-o OUTPUT_DIR] [--output OUTPUT]
                    [--format FORMAT [FORMAT ...]]
                    [--bathy-source SOURCE] [--bathy-dir DIR]
                    [--bathy-stride N]
                    [--bathy-contours DEPTH [DEPTH ...]]
                    [--max-depth METRES]
                    [--lat MIN MAX] [--lon MIN MAX]
                    [--figsize WIDTH HEIGHT]
                    [--no-ports] [--no-title] [--no-labels] [--no-legend]
                    [--eez]
                    [--verbose]
                    CONFIG_FILE

Arguments:

  • CONFIG_FILE: Enriched YAML cruise configuration file (from cruiseplan process)

Options:

  • --leg LEG: Process a single named leg only

  • --derive-netcdf: Also generate per-type NetCDF files (_points.nc, _lines.nc, _areas.nc)

  • -o, --output-dir DIR: Output directory (default: data)

  • --output NAME: Base filename (default: derived from cruise name in config)

  • --format FORMAT [FORMAT ...]: Outputs to generate: html latex csv netcdf png (space-separated; omit to generate all)

Map display options (same as cruiseplan process):

  • --bathy-source SOURCE, --bathy-dir DIR, --bathy-stride N: Bathymetry for the PNG map (defaults: gebco2025, data/bathymetry, 10)

  • --figsize WIDTH HEIGHT: Figure size in inches (default: 10 8.1)

  • --lat MIN MAX, --lon MIN MAX: Map extent

  • --max-depth METRES, --bathy-contours DEPTH [DEPTH ...]

  • --no-ports, --no-title, --no-labels, --no-legend

  • --eez: Overlay EEZ boundaries on PNG map

What it produces (all formats):

  • {name}_schedule.nc — NetCDF schedule (required for forecast and list)

  • {name}_schedule.html — Interactive HTML timeline

  • {name}_stations.tex — LaTeX station table

  • {name}_work_days.tex — LaTeX work-days-at-sea table

  • {name}_schedule.csv — Tabular schedule

  • {name}_schedule.png — PNG map with timeline

Examples:

# Generate all output formats
cruiseplan schedule data/MSM142_enriched.yaml

# Generate only the NetCDF and HTML
cruiseplan schedule data/MSM142_enriched.yaml --format netcdf html

# Single leg, custom output directory
cruiseplan schedule data/MSM142_enriched.yaml --leg leg_2 -o results/

—

Individual Processing Steps

These commands run individual steps of the cruiseplan process pipeline. Use them when you need finer control — for example, to re-validate after manually editing the YAML, or to regenerate the map without re-enriching.

cruiseplan enrich

Add computed fields to a cruise YAML: bathymetry depths, coordinate strings, and CTD section expansion. Does not validate or generate maps.

cruiseplan enrich [-h] [--add-depths] [--add-coords] [--expand-sections]
                  [-o OUTPUT_DIR]
                  [--bathy-source SOURCE] [--bathy-dir DIR] [--verbose]
                  CONFIG_FILE

Arguments:

  • CONFIG_FILE: Input YAML cruise configuration file

Options:

  • --add-depths: Look up water depths from bathymetry and add to each station

  • --add-coords: Add formatted coordinate fields (decimal minutes)

  • --expand-sections: Expand CTD section lines into individual station definitions

  • -o, --output-dir DIR: Output directory (default: data)

  • --bathy-source SOURCE: Bathymetry dataset (default: gebco2025)

  • --bathy-dir DIR: Local bathymetry data directory (default: data/bathymetry)

Example:

cruiseplan enrich data/MSM142_stations.yaml --add-depths --expand-sections

cruiseplan validate

Check a cruise YAML configuration for errors and inconsistencies. Read-only: does not modify any files.

cruiseplan validate [-h] [--no-depth-check] [--tolerance TOLERANCE]
                    [--bathy-source SOURCE] [--bathy-dir DIR]
                    [--warnings-only] [--verbose]
                    CONFIG_FILE

Arguments:

  • CONFIG_FILE: Input YAML cruise configuration file

Options:

  • --no-depth-check: Skip comparing existing depth values against bathymetry

  • --tolerance TOLERANCE: Maximum acceptable depth discrepancy in percent (default: 10.0)

  • --bathy-source SOURCE: Bathymetry dataset for depth checks (default: gebco2025)

  • --bathy-dir DIR: Local bathymetry data directory (default: data/bathymetry)

  • --warnings-only: Report warnings but exit with code 0

Example:

cruiseplan validate data/MSM142_enriched.yaml --tolerance 15.0

cruiseplan map

Generate a PNG map and/or KML file from a cruise YAML configuration.

cruiseplan map [-h] [--no-ports] [--no-title] [--no-labels] [--no-legend]
               [-o OUTPUT_DIR] [--output OUTPUT]
               [--format FORMAT [FORMAT ...]]
               [--bathy-source SOURCE] [--bathy-dir DIR] [--bathy-stride N]
               [--figsize WIDTH HEIGHT] [--show-plot]
               [--lat MIN MAX] [--lon MIN MAX]
               [--bathy-contours DEPTH [DEPTH ...]] [--max-depth METRES]
               [--eez]
               [--verbose]
               CONFIG_FILE

Arguments:

  • CONFIG_FILE: YAML cruise configuration file

Options:

  • --format FORMAT [FORMAT ...]: Outputs to generate: png kml (space-separated; omit to generate all)

  • -o, --output-dir DIR: Output directory (default: data)

  • --output NAME: Base filename (default: derived from config filename)

  • --figsize WIDTH HEIGHT: Figure size in inches (default: 10 8.1)

  • --lat MIN MAX, --lon MIN MAX: Map extent in decimal degrees

  • --max-depth METRES: Depth ceiling for bathymetry colour scale

  • --bathy-contours DEPTH [DEPTH ...]: Contour depths in metres; replaces defaults

  • --bathy-stride N: Bathymetry downsampling factor; higher is faster (default: 5)

  • --no-ports, --no-title, --no-labels, --no-legend: Suppress map elements

  • --eez: Overlay EEZ boundaries on PNG map (visualization only; data downloaded on first use)

  • --show-plot: Display the figure interactively instead of saving to file

Examples:

# Generate both PNG and KML (default)
cruiseplan map data/MSM142_enriched.yaml

# PNG only, custom extent and contours
cruiseplan map data/MSM142_enriched.yaml --format png \
    --lat 58 68 --lon -35 -10 --bathy-contours 500 1000 2000 3000

# Large figure for printing
cruiseplan map data/MSM142_enriched.yaml --figsize 20 16 -o figures/

—

At Sea

These commands are used during the cruise once a NetCDF schedule has been generated with cruiseplan schedule. Run cruiseplan list to find activity indices, then cruiseplan forecast to generate a rolling workplan from the current ship position.

cruiseplan list

Print all activities in a schedule with their indices. Use the index values as --start-index input to cruiseplan forecast.

cruiseplan list SCHEDULE_FILE

Arguments:

  • SCHEDULE_FILE: NetCDF schedule file produced by cruiseplan schedule

Output: Table of index, time offset from start, category, duration (hours, from the file’s duration in minutes), water depth, operation depth, distance (nm), and name.

Example:

cruiseplan list data/MSM142_schedule.nc

cruiseplan forecast

Generate a rolling station plan from a NetCDF schedule, starting from a given operation at a new wall-clock time (see the anchoring rule below). Useful for updating the workplan at sea as the ship’s position changes.

Two modes of operation:

  • Forecast mode (--start-index and --start-time both provided): rolling workplan for the next N hours, re-anchored to a new start time

  • Static mode (neither provided): full-schedule document (--format tex or --format waypoints only)

cruiseplan forecast [-h] [--start-index N] [--start-time DATETIME]
                    [--duration HOURS] [--transit-speed KNOTS]
                    [--current-position LAT,LON]
                    [--format {text,tex,waypoints,kml,png}]
                    [-o OUTPUT_DIR] [--output FILENAME]
                    [--logo PATH] [--number TEXT] [--title TEXT]
                    [--bathy-source SOURCE] [--bathy-dir DIR]
                    [--bathy-stride N]
                    [--figsize WIDTH HEIGHT]
                    [--max-depth METRES]
                    [--bathy-contours DEPTH [DEPTH ...]]
                    [--no-title] [--no-labels] [--no-legend]
                    [--lat MIN MAX] [--lon MIN MAX]
                    [--verbose]
                    SCHEDULE_FILE

Arguments:

  • SCHEDULE_FILE: NetCDF schedule file produced by cruiseplan schedule

Forecast mode options:

  • --start-index N: Row index from cruiseplan list (0-based) of the operation to anchor on; required together with --start-time

  • --start-time DATETIME: Start time of the anchored operation, or of the ship at --current-position if given; ISO format (e.g. "2026-08-30T14:00:00" or "2026-08-30 14:00"); required together with --start-index

  • --duration HOURS: Forecast window in hours from --start-time (default: 24)

  • --transit-speed KNOTS: Ship speed printed in the text forecast header (default: 10 kt); transit times use the planned leg speed

  • --current-position LAT,LON: Ship position at --start-time in decimal degrees (e.g. -74.62,164.30, "-74.62 164.30" or --current-position=-74.62,164.30, or two values of any sign such as 65.0 -30.0); changes the times in every format

Anchoring rule:

  • --start-time without a zone is UTC. With the ship’s offset (2026-08-30T14:00-03:00) it is ship time, and the TeX table is printed in ship time, labelled LT (UTC-03:00). See Forecasts at sea for how to write the offset.

  • Indices are the rows of cruiseplan list (ports, transits, operations, buffers). The row at --start-index starts at --start-time.

  • An operation row: the ship is there, so the transit into it is not part of the forecast. Its own delay_start_minutes is replaced by the start time.

  • A transit row: the ship is starting that transit now, from where it begins; the operation it leads to starts when the planned transit ends. Anchoring on Transit to X puts X later than anchoring on X, by the transit time.

  • With --current-position the given position wins, --start-time is the time at that position, and a transit row is replaced by the operation it leads to. A transit from the position to that operation is added at the leg’s planned speed (not when the ship is within 0.05 nm of it), and the operation starts when it ends.

  • If no operation starts within --duration hours, the command stops with an error instead of writing an empty plan.

  • The text forecast (% Anchor = line) and the TeX plan (under the title) state the rule applied.

  • Every later row keeps its offset from the anchored row in the schedule, with the durations stored there: a positive delay_start_minutes is a “Waiting before” row, a negative one is in the shorter transit before the operation, so rows neither overlap nor leave gaps.

  • The TeX plan rounds times to 10 minutes. Re-anchoring with a time read off a printed plan can shift the new plan by up to 5 minutes; take the start time from the clock or from the text forecast instead.

Output options:

  • --format: text (default), tex, waypoints, kml, png

  • -o, --output-dir DIR: Output directory (default: current directory)

  • --output FILENAME: Output filename, relative to --output-dir (default: stdout for text and waypoints; {schedule}_forecast.tex, .kml or .png next to the schedule file for the other formats)

TeX output options (--format tex):

  • --logo PATH: Logo image file for the workplan header (PNG, JPG, or PDF)

  • --number TEXT: Workplan number (e.g. 28)

  • --title TEXT: Cruise name (e.g. MSM142)

PNG map options (--format png):

  • --lat MIN MAX, --lon MIN MAX: Map extent in decimal degrees

  • --max-depth METRES: Depth ceiling for bathymetry colour scale

  • --bathy-contours DEPTH [DEPTH ...]: Contour depths in metres

  • --no-title, --no-labels, --no-legend: Suppress map elements

  • --figsize WIDTH HEIGHT: Figure size in inches (default: 10 8.1)

  • --bathy-source SOURCE, --bathy-dir DIR: Bathymetry dataset and directory

  • --bathy-stride N: Downsampling factor (default: 10)

Examples:

# Step 1: find activity indices
cruiseplan list data/MSM142_schedule.nc

# Step 2: plain-text 24-hour forecast from activity 18
cruiseplan forecast data/MSM142_schedule.nc \
    --start-index 18 --start-time "2026-08-30T14:00:00"

# 36-hour forecast written to file
cruiseplan forecast data/MSM142_schedule.nc \
    --start-index 5 --start-time "2026-08-29T08:00:00" \
    --duration 36 --output forecast.txt

# Bridge waypoints from the current ship position (times include the
# transit from it to activity 2)
cruiseplan forecast data/MSM142_schedule.nc \
    --start-index 2 --start-time "2026-05-05 08:00" --duration 24 \
    --current-position 65.027,-31.370 \
    --format waypoints --output-dir route/ --output Stationsplan28.txt

# TeX workplan with logo
cruiseplan forecast data/MSM142_schedule.nc \
    --start-index 2 --start-time "2026-05-05 08:00" --duration 24 \
    --format tex --logo config/images/logo.png \
    --title "MSM142" --number "28" \
    --output-dir route/ --output Stationsplan28.tex

# Static full-schedule TeX table (no start params)
cruiseplan forecast data/MSM142_schedule.nc \
    --format tex --output station_plan.tex

—

Global Options

All commands support:

  • -h, --help: Show help message and exit

  • -V, --version: Show version and exit (top-level cruiseplan -V only)

Commands with --verbose / -v: bathymetry, enrich, forecast, map, pangaea, process, run, schedule, stations, validate

Exit Codes

  • 0: Success

  • 1: Error (configuration, validation, file I/O, network, etc.)

For worked examples see Workflows.