Skip to main content

CLI Reference

The chartmanager command-line tool provides convenient access to NOAA chart operations.

Installation​

go install github.com/beetlebugorg/chartmanager/cmd/chartmanager@latest

Quick Start​

Search for charts:

chartmanager query --lon=-122.4194 --lat=37.7749

Download charts:

chartmanager download --min-lon=-122.5 --max-lon=-122.4 --min-lat=37.7 --max-lat=37.8 --zoom=16

See what's cached:

chartmanager cache list

The query command searches the catalog without downloading. The download command fetches actual chart files.

Commands​

version​

Display version information:

chartmanager version

Output:

chartmanager
Version:   dev
Commit:    8e9969d
Built:     2025-10-17T00:26:06Z
Go:        go1.25.1
Platform:  darwin/arm64

Shows version, git commit hash, build date, Go version, and platform.

query​

Query the catalog for charts without downloading them. Results shown in formatted table.

Example 1: Query by point (grouped output for large results)

chartmanager query --lon=-122.4194 --lat=37.7749

Output:

📍 Charts for Region
   Bounds: (-122.5996, 37.5947) to (-122.2392, 37.9551)

Found 27 charts covering 6.5 MB

Berthing (27 charts, 6.5 MB)
  ├─ US1WC01M  0.6 MB  (-137.4999, 31.9999) → (-116.5001, 38.4000)
  ├─ US1WC07M  0.2 MB  (-180.0000, 18.7500) → (-116.3333, 38.4000)
  ├─ US2WC05M  0.6 MB  (-126.1667, 31.5000) → (-116.2500, 38.0833)
  └─ ... 24 more


💡 Tip: Use --verbose (-v) to see all charts, or add --zoom or --band to filter

Results with more than 15 charts are automatically grouped by usage band. Use --verbose or -v to see the full table.

Example 2: Query by bounding box

chartmanager query --min-lon=-122.5 --max-lon=-122.4 --min-lat=37.7 --max-lat=37.8

Output:

📍 Charts for Region
   Bounds: (-122.5000, 37.7000) to (-122.4000, 37.8000)

Found 12 charts covering 5.0 MB

╭────────┬─────┬──────┬────────┬───────────────────────────────────────────╮
│Chart   │Scale│Size  │Band    │Coverage                                   │
├────────┼─────┼──────┼────────┼───────────────────────────────────────────┤
│US1WC01M│N/A  │0.6 MB│Berthing│(-137.4999, 31.9999) → (-116.5001, 38.4000)│
│US3CA14M│N/A  │0.8 MB│Berthing│(-124.5844, 37.5338) → (-122.2178, 39.0500)│
│US5CA12M│N/A  │0.2 MB│Berthing│(-122.7011, 37.6999) → (-122.4844, 37.9915)│
│US5CA13M│N/A  │0.9 MB│Berthing│(-122.4844, 37.7056) → (-122.2011, 37.8566)│
... (8 more charts)
╰────────┴─────┴──────┴────────┴───────────────────────────────────────────╯

Example 3: Filter by usage band

chartmanager query --lon=-122.4194 --lat=37.7749 --band=berthing

Shows only berthing-scale charts (same format as above)

Example 4: Filter by zoom level

chartmanager query --lon=-122.4194 --lat=37.7749 --zoom=18

Output:

📍 Charts for Region
   Bounds: (-122.5996, 37.5947) to (-122.2392, 37.9551)

Found 0 charts covering 0.0 MB

No berthing charts at zoom 18 (requires specific harbor-scale charts)

Example 5: Verbose output (show all charts)

chartmanager query --lon=-122.4194 --lat=37.7749 --verbose
# or use short flag: -v

Output:

📍 Charts for Region
   Bounds: (-122.5996, 37.5947) to (-122.2392, 37.9551)

Found 27 charts covering 6.5 MB

╭────────┬─────┬──────┬────────┬───────────────────────────────────────────╮
│Chart   │Scale│Size  │Band    │Coverage                                   │
├────────┼─────┼──────┼────────┼───────────────────────────────────────────┤
│US1WC01M│N/A  │0.6 MB│Berthing│(-137.4999, 31.9999) → (-116.5001, 38.4000)│
│US3CA14M│N/A  │0.8 MB│Berthing│(-124.5844, 37.5338) → (-122.2178, 39.0500)│
│US5CA12M│N/A  │0.2 MB│Berthing│(-122.7011, 37.6999) → (-122.4844, 37.9915)│
│US5CA13M│N/A  │0.9 MB│Berthing│(-122.4844, 37.7056) → (-122.2011, 37.8566)│
... (all 27 charts shown in table)
╰────────┴─────┴──────┴────────┴───────────────────────────────────────────╯

💡 Tip: Use 'chartmanager download --min-lon=... --zoom=12' to download these charts

Verbose mode shows the full table regardless of result count

Usage Bands:

  • overview - 1:3,000,000 and smaller
  • general - 1:500,000 to 1:3,000,000
  • coastal - 1:150,000 to 1:500,000
  • approach - 1:50,000 to 1:150,000
  • harbor - 1:25,000 to 1:50,000
  • berthing - Larger than 1:25,000

Zoom to Band Mapping:

  • 1-6: Overview charts (1:3M)
  • 7-9: General charts (1:500K)
  • 10-12: Coastal charts (1:150K)
  • 13-15: Approach charts (1:50K)
  • 16-18: Harbor charts (1:25K)
  • 19+: Berthing charts (1:5K)

download​

Download charts by name or viewport:

# Download by name
chartmanager download US5CA13M

# Download multiple charts
chartmanager download US5CA12M US5CA13M

# Download by viewport
chartmanager download --min-lon=-122.5 --max-lon=-122.4 \
  --min-lat=37.7 --max-lat=37.8 --zoom=16

Example output:

📥 Downloading Charts
   Viewport: (-122.5000, 37.7000) to (-122.4000, 37.8000)
   Zoom: 16

  ⠙ US5CA13M downloading...
  ✓ US5CA13M downloaded
  ⠙ US5CA12M downloading...
  ✓ US5CA12M downloaded
✓ US5CA13M.000  0.9 MB  5,466 features
✓ US5CA12M.000  0.2 MB  1,123 features

📊 Summary
   Charts downloaded: 2
   Total size: 1.1 MB
   Cache location: ~/.cache/chartmanager/charts

Shows animated spinner while downloading each chart

Charts are downloaded to ~/.cache/chartmanager/charts/ and cached for future use.

cache list​

List cached charts organized by geographic region:

chartmanager cache list

Example output:

📦 Cached Charts
   Location: ~/.cache/chartmanager/charts

Pacific (28 charts, 15.4 MB)
├─ US1WC01M.000     Ed. 52   0.8 MB  792 features
├─ US3CA14M.000     Ed. 38   1.5 MB  2,617 features
├─ US3CA52M.000     Ed. 31   1.4 MB  1,978 features
├─ US4CA11M.000     Ed. 39   1.0 MB  1,977 features
├─ US5CA12M.000     Ed. 31   0.5 MB  1,123 features
├─ US5CA13M.000     Ed. 95   2.7 MB  5,466 features
├─ US5CA16M.000     Ed. 45   0.7 MB  1,196 features
├─ US5CA21M.000     Ed. 61   0.5 MB  1,006 features
└─ ... (20 more)

Atlantic (35 charts, 37.9 MB)
├─ US3MD01M.000     Ed. 42   1.2 MB  2,134 features
├─ US4MD40M.000     Ed. 58   2.8 MB  4,073 features
└─ ... (33 more)

Total: 63 charts, 53.4 MB

Shows:

  • Charts grouped by geographic region with tree-style formatting
  • Chart edition number, file size, and feature count
  • Regional subtotals
  • Total disk cache usage

cache clear​

Clear the chart cache.

Example 1: Clear charts only (recommended)

chartmanager cache clear --charts-only

Output:

✓ Cleared chart cache
  Files removed: 63
  Space freed: 53.4 MB

Catalog preserved

The --charts-only flag preserves the catalog (~90MB) so you can quickly query and download charts again later without re-downloading the catalog.

Example 2: Clear everything (including catalog)

chartmanager cache clear

This removes both charts and the catalog file. You'll need to re-download the catalog (~90MB) on next use.

stats​

Display chart manager statistics:

chartmanager stats

Example output:

Chart Manager Statistics



📁 Catalog
   Location: ~/.cache/chartmanager/ENCProdCat_19115.xml
   Charts available: 6,498
   Catalog size: 45.7 MB
   Last updated: 1 hours ago

💾 Cache
   Location: ~/.cache/chartmanager/charts
   Charts cached: 63
   Disk usage: 53.4 MB

Shows:

  • Total charts available in NOAA catalog
  • Catalog file size and last update time
  • Number of charts cached on disk
  • Total disk cache usage
  • File paths for catalog and cache

Common CLI Tasks​

The CLI is primarily a chart management utility - it helps you explore the NOAA catalog and pre-download charts. It doesn't render charts or extract navigation data (use the Go library for that).

Exploring What Charts Exist​

See what charts cover San Francisco Bay:

chartmanager query --min-lon=-122.5 --max-lon=-122.4 --min-lat=37.7 --max-lat=37.8

Output:

📍 Charts for Region
   Bounds: (-122.5000, 37.7000) to (-122.4000, 37.8000)

Found 12 charts covering 5.0 MB

╭────────┬─────┬──────┬────────┬───────────────────────────────────────────╮
│Chart   │Scale│Size  │Band    │Coverage                                   │
├────────┼─────┼──────┼────────┼───────────────────────────────────────────┤
│US1WC01M│N/A  │0.6 MB│Berthing│(-137.4999, 31.9999) → (-116.5001, 38.4000)│
│US3CA14M│N/A  │0.8 MB│Berthing│(-124.5844, 37.5338) → (-122.2178, 39.0500)│
│US5CA12M│N/A  │0.2 MB│Berthing│(-122.7011, 37.6999) → (-122.4844, 37.9915)│
│US5CA13M│N/A  │0.9 MB│Berthing│(-122.4844, 37.7056) → (-122.2011, 37.8566)│
... (8 more charts)
╰────────┴─────┴──────┴────────┴───────────────────────────────────────────╯

The query command shows chart metadata without downloading anything - useful for exploring the catalog.

Downloading Charts for Development​

Pre-download charts for your Go application to use:

chartmanager download --min-lon=-122.5 --max-lon=-122.4 --min-lat=37.7 --max-lat=37.8 --zoom=16

Output:

📥 Downloading Charts
   Viewport: (-122.5000, 37.7000) to (-122.4000, 37.8000)
   Zoom: 16

  ⠙ US5CA13M downloading...
  ✓ US5CA13M downloaded
  ⠙ US5CA12M downloading...
  ✓ US5CA12M downloaded
✓ US5CA13M.000  0.9 MB  5,466 features
✓ US5CA12M.000  0.2 MB  1,123 features

📊 Summary
   Charts downloaded: 2
   Total size: 1.1 MB
   Cache location: ~/.cache/chartmanager/charts

Shows animated spinner (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏) while downloading each chart. This populates the cache that the Go library will use, avoiding downloads during development.

Checking What's Downloaded​

See which charts are cached locally:

chartmanager cache list

Output:

📦 Cached Charts
   Location: ~/.cache/chartmanager/charts

Pacific (28 charts, 15.4 MB)
├─ US1WC01M.000     Ed. 52   0.8 MB  792 features
├─ US3CA14M.000     Ed. 38   1.5 MB  2,617 features
├─ US5CA12M.000     Ed. 31   0.5 MB  1,123 features
├─ US5CA13M.000     Ed. 95   2.7 MB  5,466 features
└─ ... (24 more)

Total: 28 charts, 15.4 MB

Shows all cached charts grouped by region with sizes and feature counts.

Managing Cache Size​

Free up disk space:

# See current cache usage
chartmanager stats

Output:

Chart Manager Statistics



📁 Catalog
   Location: ~/.cache/chartmanager/ENCProdCat_19115.xml
   Charts available: 6,498
   Catalog size: 45.7 MB
   Last updated: 1 hours ago

💾 Cache
   Location: ~/.cache/chartmanager/charts
   Charts cached: 28
   Disk usage: 15.4 MB

Then clear if needed:

chartmanager cache clear --charts-only

Output:

✓ Cleared chart cache
  Files removed: 28
  Space freed: 15.4 MB

Catalog preserved

The catalog (~90MB) is preserved so you can quickly query and download charts again later.

Updating the Catalog​

Get the latest chart metadata from NOAA:

chartmanager --force-catalog-update query --lon=-122.4194 --lat=37.7749

The --force-catalog-update flag works with any command to force a fresh catalog download before executing the command. You'll see the normal query output after the catalog updates.

Global Options​

All commands support:

  • --help - Show command help
  • --force-catalog-update - Force re-download of NOAA catalog before running command
  • --cache-dir=PATH - Override default cache directory
  • --catalog-path=PATH - Override default catalog path

Configuration​

The CLI tool uses the same XDG-compliant cache directories as the library:

  • Catalog: ~/.cache/chartmanager/ENCProdCat_19115.xml
  • Charts: ~/.cache/chartmanager/charts/

Override via command-line flags:

chartmanager --cache-dir=/custom/path download US5MA22M

Exit Codes​

  • 0 - Success
  • 1 - Error (printed to stderr)