CLI Commands
Complete reference for all CruisePlan command-line tools.
Commands follow the typical cruise planning workflow:
Setup — download bathymetry data once before using the tool
Pre-cruise planning — collect historical data, place stations, process configuration, generate schedule
Individual processing steps — fine-grained control over enrichment, validation, and mapping
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
gebco2023is not a choice here: there is no download for it. PlaceGEBCO_2023.ncin the bathymetry directory by hand to use--bathy-source gebco2023in 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 (
--latand--lonrequired): query PANGAEA and download matching datasetsDOI file mode: provide a
.txtfile 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.txtDOI 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 (fromcruiseplan 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:pngkml(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.yamlPNG map:
{name}_map.pngKML 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 (fromcruiseplan 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:htmllatexcsvnetcdfpng(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 forforecastandlist){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:pngkml(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 bycruiseplan 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-indexand--start-timeboth provided): rolling workplan for the next N hours, re-anchored to a new start timeStatic mode (neither provided): full-schedule document (
--format texor--format waypointsonly)
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 bycruiseplan schedule
Forecast mode options:
--start-index N: Row index fromcruiseplan 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-positionif 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-timein 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 as65.0 -30.0); changes the times in every format
Anchoring rule:
--start-timewithout 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, labelledLT (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-indexstarts 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_minutesis 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 XputsXlater than anchoring onX, by the transit time.With
--current-positionthe given position wins,--start-timeis 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
--durationhours, 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_minutesis 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,.kmlor.pngnext 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-levelcruiseplan -Vonly)
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.