Docs

NTHMAP CLI

Command-line access to every NTHMAP dataset. Installable with pip, scriptable in bash, pipe-friendly JSON output.

The NTHMAP CLI is a single-file Python tool that wraps the REST API. It works on macOS, Linux, and Windows, requires only Python 3.9+, and runs off a Bearer API key.

Install

One-line install

curl -sSL https://nthmap.com/cli/install.sh | bash

This downloads nthmap to ~/.local/bin/nthmap and makes it executable.

Manual install

# Download the single file
curl -sSLo ~/.local/bin/nthmap https://nthmap.com/cli/nthmap.py
chmod +x ~/.local/bin/nthmap

# Make sure ~/.local/bin is on your PATH
export PATH="$HOME/.local/bin:$PATH"

From PyPI (coming soon)

pip install nthmap-cli

Verify

$ nthmap --version
nthmap 0.1.0

$ nthmap --help

Authenticate

Set your API key via environment variable:

export NTHMAP_API_KEY=ntm_live_...

Or persist it in ~/.nthmaprc:

nthmap auth login
# Paste your API key when prompted

~/.nthmaprc is a simple INI file:

[default]
api_key = ntm_live_...
base_url = https://nthmap.com

You can have multiple profiles:

nthmap --profile prod vessels list
nthmap --profile staging vessels list

Command overview

nthmap <command> [subcommand] [options]

Commands:
  auth        login, logout, status, keys
  vessels     list, get, track
  infra       list, get
  events      list
  chokepoints list
  prices      list, history
  flows       get
  draw        analyze
  ai          query, context, flow
  views       list, save, delete
  prompts     list, save, run, delete
  version

Vessels

# List crude tankers in the Persian Gulf, loaded ≥80%
nthmap vessels list \
  --bbox 54,25,58,28 \
  --types "Crude Tanker" \
  --min-load 80

# Just the MMSI and name columns (default is a pretty table)
nthmap vessels list --fields mmsi,name,load_pct

# Raw JSON (pipe into jq)
nthmap vessels list --format json | jq '.[].est_cargo_mt'

# CSV output
nthmap vessels list --format csv > vessels.csv

# Get a specific vessel
nthmap vessels get 311000001

# 24-hour track (Pro)
nthmap vessels track 311000001

Infrastructure

# All LNG terminals
nthmap infra list --types lng_terminal

# All ports + refineries in Western Europe
nthmap infra list --bbox -10,36,20,58 --types port,oil_refinery

# Single asset
nthmap infra get 14

Events (Pro)

# Active hurricanes + earthquakes
nthmap events list --types hurricane,earthquake --active

# Only severe or extreme severity
nthmap events list --severity Severe,Extreme

Chokepoints (Pro)

# All 8 chokepoints with live vessel count
nthmap chokepoints list

# Just status summary
nthmap chokepoints list --fields name,status,vessels_count,avg_speed_kt

Prices

nthmap prices list                   # all latest
nthmap prices history CLUSD --days 7 # WTI last 7 days

Region analysis — the draw tool

This is the CLI equivalent of drawing a polygon on the map:

# Persian Gulf snapshot
nthmap draw analyze \
  --bbox 54,25,58.5,27.5 \
  --format json

# From a GeoJSON file
nthmap draw analyze --file persian-gulf.geojson

Returns vessel count, commodity breakdown, estimated cargo, events inside, and infrastructure inside — same shape as the web app's draw panel.

AI (Pro)

# Natural-language vessel query
nthmap ai query "crude tankers near Hormuz over 90% loaded"

# Vessel trading context
nthmap ai context 311000001

# Regional flow analysis
nthmap ai flow --bbox 54,25,58.5,27.5

Saved views & prompts

# List your saved views
nthmap views list

# Run a saved view (flies the map? no — just re-fetches data with its filters)
nthmap views run "Persian Gulf Watch"

# Run a saved prompt
nthmap prompts run "Hormuz tankers"

Output formats

Every command accepts --format:

table (default) — pretty ASCII table, columns auto-sized
json — raw JSON, pipeable to jq
csv — comma-separated values
tsv — tab-separated values
yaml — YAML output

And --fields to select columns for table/csv/tsv:

nthmap vessels list --fields mmsi,name,vessel_type_str,load_pct

Automation recipes

Cron: email me when Hormuz gets congested

#!/bin/bash
STATUS=$(nthmap chokepoints list --format json | \
  jq -r '.[] | select(.name == "Strait of Hormuz") | .status')
if [ "$STATUS" != "Normal" ]; then
  echo "Hormuz is now $STATUS" | mail -s "NTHMAP alert" me@example.com
fi

Slack alert on new events in a bbox

#!/bin/bash
COUNT=$(nthmap events list --bbox 10,10,60,45 --format json | jq length)
if [ "$COUNT" -gt "$LAST_COUNT" ]; then
  curl -X POST $SLACK_WEBHOOK -d "{\"text\":\"$((COUNT - LAST_COUNT)) new events in region\"}"
  echo $COUNT > /tmp/nthmap-event-count
fi

Daily cargo flow report

nthmap flows get --region Europe --commodity "Crude Oil" --format json > \
  reports/europe-crude-$(date +%Y%m%d).json

Troubleshooting

"No API key configured"

Set NTHMAP_API_KEY or run nthmap auth login.

"Pro tier required"

You're on the free tier. The events, chokepoints, draw, AI, and prompts commands are Pro features.

Debug mode

nthmap -v vessels list          # prints the underlying HTTP request
nthmap -vv vessels list         # adds response headers and timing

Network/SSL errors

nthmap --no-verify vessels list   # skip TLS verification (testing only!)
nthmap --base-url http://localhost:5000 vessels list   # hit a local dev server

Source

The CLI is a single file — no dependencies beyond the Python stdlib. View or customize it:

vim $(which nthmap)

Or grab the latest version from the NTHMAP GitHub.