Raster and satellite
--raster puts an image tile layer under the vector map, by provider name,
URL or PMTiles file:
mapterm --raster esri --at 38.8895,-77.0353 -z 15 # satellitemapterm --raster 'https://tile.openstreetmap.org/{z}/{x}/{y}.png'mapterm --raster gibs --date 2026-10-30 -z 6 # NASA daily imagerymapterm --raster mall.pmtiles # your own imagery, offlinemapterm --raster-list # providers and the keys they need⢸ ⡇ ⢸ Reflecting Pool Rainbow Pool⢸ ⡇ ⢸ ⢸ 15th Street Southwest ⣸ ⡸⢄⡀ ⢸ ⢀⠔⠊⡇⢇ Jefferson Drive Southwest⡒⠒⠒⠒⡖⠒⠒ 17th Street Southwest⠒⠒⠢⠤⡀ ⢀⠔⠁ ⢸⠤⢤⡀ ⠈⠒⠒⠉ ⠠⣀ ⢀⠤⠒⠉ ⣠⣊⣀⣀⣀⣀⣣⣀ ⢠⠃ ⠑⡄ ⢰⠁ ⢸ ⡇ ⡀ ⠉⠒⠤⢤⠃ ⣀⠤⠔⠊⠉⠁ ⠈⠉⠉⠑⠓⢤⣄⣀⣀⣀⣠⣃⣀⣀⡀ ⡀ ⣀⡠⠤⢺⣒⣒⣒⣒⣤⢄⣀⡀ ⢸ ⢇ ⠘⡄ ⢲⢀⠤⠤⢤ ⡇⡇ ⣇⣀⣀⣀⡀ ⢀⣸⠔⠉ ⠈⢢⠉⠑⠒⠤⢄⣀⠉⠓⠒⠤⠤⠤⠤⠤⠤⠤⠓⠊⠉⡠⠔⠊⢹ ⠉⠒⠪⠭⡻⡒⠒⠚⠒⠒⠒⠓⠒⠚⠚⠒⠒⠚⠒⠓⠓ ⢠⠃ ⣀⠤⠊⠁⢸ ⡇ ⠉⠑⠒⠤⣀ ⣀⣀⠤⠊ ⢸ ⡇⡇ ⣀ ⢠ ⣀⡀ ⣙⣍⣉⣉⣉⣉⣉⣉⠉⠒⠒⠒⠒⠚⠒⠒⠒⢶⠒⠒⠒⠢⠤⠤⠤⠤⠤⠤⠤⠔⠒⠒⠊⠉ ⣀⣀⣈⣢⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀Independence Avenue Southwest ⢸ ⠸⠤⠤⠤⠤⠤⠤⠤⡇⡇ ⣿ ⢸ ⡇⡇ ⠱⡀ ⠉⠉⠉⠉⠉⠉⠉⠉⠑⢺⡖Independence Avenue Southwest Maine Avenue Southwest ⢸ ⡇⡇ ⣿ ⢸ ⢀ ⣧⠃ ⢣ ⢸⡇ ⠑⡄ ⠈⠒⢄ ⠈⢆ ⢸ ⡇⡇ ⣿ ⢸ ⢸ ⣿ ⠠⢇ ⢸ ⠈⠢⡀ ⠱⡀⠈⢆ ⢸⠉⠉⠉⠉⠉⠉⠉⠉ ⡇⡇ ⡏ ⠈⢹ ⢸ ⢹ ⠈⡆ ⢸ ⢱ ⠱⡀⠸⡀ ⢸ ⠉⠉⠉⠉⠉⡍⡟⡗⠒⠒⠓⠒⠒⠚⠒⠒⠚⠒⠒⠚⡖⠒⠒ ⠙⡄ ⢸ ⢇ ⠱⡀⢣ ⢸ ⢐⣒⣒US 1 ⡇ ⢱ ⢸ ⠳⣀ ⠱⡀⢇ ⢸ ⡇⡇⡇ ⡇ ⡸ ⡇ ⠑⠢⠤⠤⢄⣀⣀⡀ ⢣⠈⢆ ⢸ ⡇⡇⣿ ⢠ ⡄ ⡇ ⢀⢀⠔⠁ ⡇ ⠈⠑⠋⠣⡈⢢ ⣸⠤⡤⠤⠤⠤⠤⠤⠤⠧⡇⣿⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉ ⠱⡀ ⢀⠜⠢⡀ ⠈⢢⠑⣏⡆⠣⠤⠤⠤⠤⠤ ⡇⣿ ⠈⠢⣄ ⡠⠔⢪⠁ ⠈⠢⡀ ⠉⠣⡫⢆ ⡰⠩⡉⠑⡄⣿⢸ ⡠⠒⠒⢢⡠⣤⣶ ⠘⢕⢄ ⢀⠜ ⠑⠢⡀⡠⠜⠁ ⠈⠲⣕⢄⢇ ⡇ ⡸⣿⡎ ⢀ ⠰⣁⡠⠴⠒⡯⠛⠉ ⠙⣄⠎⠁ ⠈⠁ ⠑⡝⣗⡻⣅ ⡿⢸⡧⠤⠤⠴⣒⣥⠶⠊⠉⠓⠤⠤⠔⠁ ⠈⠢⡀ Tidal Basin ⠘⣼⠈⢒⢵⡧⡇⠑⢄⣠⠞⠊ Ohio Drive Southwest ⢀⡠⠤⠖⠒⠒⠒⠒⠒⠒⠒⠢⠤⠤⢄⣀⡀ ⣿⡰⠁⡜⡜⡾⣵⡮⣑⠢⣀ ⠑⢄ ⢀⠤⠒⠉⠁ Ohio Drive Southwest⣲⢵⣢⣤⢄⣀⡼⣱ ⠑⢄ ⡠⠒⠁ ⠈⢱Maine Avenue Southwest⠶ ⠑⢄ ⢀⠜ ⡰⡝⢀⢎⢿⣿⡎ ⠉⠉⠈⠑⠪⠭⣒⡬⢍⣉⠑ ⠑⢄ ⢠⠊ ⢀⣀⣀⡀ ⢀⡮⠊⢀⢎⣾⢯⠊⠈⠢⡀ ⠈⠑⠒⣭ ⠑⢄ ⡰⠁ ⢀⠔⠉⠁ ⠈⠑⠤⡀ ⢀⢴⠁⡇⢀⢎⢎⢮⠃ ⠈⠑⢄ ⢀⡴ ⠑⢄⡀ ⡰⠁ ⢠⠃ ⠹⡀ ⡼⠒US 1⢮⠃⢀⡠⡄ ⠑⢄ ⡰⠋⢀ ⠈⠢⡀ ⡜ ⡜ ⡇ ⡜ ⡰⡩⢣⡳⢅⠜⠧⠒⠉ ⠑⢄ ⡠⢊⡠⠊⢁ ⠈⠑⢄ ⡠⠊ ⢸ ⢀⠇ ⡸ ⡰⡱⣡⠏⢈⠮⣑⢄⡀ ⠑⢄⢀⠤⢊⠔⡡⠔⠊⠁ ⠑⠢⡀ ⢀⠔⠁ ⠑⢄ West Basin Drive Southwest⡀ ⢀I-395
Real images or cell colors
Section titled “Real images or cell colors”On terminals with the kitty graphics protocol (Ghostty, kitty, WezTerm, and through herdr), tiles are real images underneath the text. Vector lines, labels, markers and inspect draw on top. Each tile is sent to the terminal once; panning and zooming only move it.
Elsewhere, each cell gets the average color of the imagery under it. That is what the snapshot above shows.
MAPTERM_GRAPHICS=kitty or MAPTERM_GRAPHICS=cells overrides the guess.
Providers
Section titled “Providers”| Name | Imagery | Key |
|---|---|---|
osm |
OpenStreetMap standard map (light use only) | none |
esri |
Esri World Imagery, global satellite | none |
usgs |
USGS National Map imagery, US only, public domain | none |
eox |
Sentinel-2 cloudless 2024, global, ~10 m (CC BY-NC-SA) | none |
gibs |
NASA GIBS daily satellite imagery, ~250 m (--date, default yesterday) |
none |
esri-light, esri-dark |
Esri Gray Canvas, quiet backgrounds for overlays | none |
vantor |
Vantor (Maxar) Vivid basemap | VANTOR_API_KEY |
planet |
Planet basemaps (your subscription’s mosaics) | PL_API_KEY + a mosaic |
mapbox |
Mapbox Satellite, Retina tiles | MAPBOX_ACCESS_TOKEN |
maptiler |
MapTiler Satellite | MAPTILER_KEY |
More detail per provider is in the raster providers reference.
API keys
Section titled “API keys”Keys never go on the command line. mapterm reads them from the provider’s environment variable or from a command:
mapterm --raster vantor --raster-key-cmd 'pass show vantor/api-key'Keys are only added to requests (Vantor’s as the maxar-api-key header) and
are blanked out of error messages. Keyed providers don’t cache tiles on disk
unless you pass --raster-cache, since commercial licenses often limit storing
them.
Custom URLs
Section titled “Custom URLs”- Use
{z},{x}and{y}in any order. For TMS services (rows counted from the bottom) use{-y}or add--tms. - Put
{key}where an API key goes; it’s filled fromMAPTERM_RASTER_KEYor--raster-key-cmd. --raster-header 'Name: {key}'adds a request header. Write the key as{key}rather than the key itself, so it stays out ofpsand your shell history.--raster-param NAME=VALUEfills any other{NAME}in the URL.--raster-attribution TEXTcredits the imagery in the status bar. Esri, USGS, OpenStreetMap and EOX are credited automatically.
Planet mosaics
Section titled “Planet mosaics”Planet serves each customer’s named mosaics. List the ones your key can use, then pick one:
mapterm --raster-list-mosaicsmapterm --raster planet --raster-param mosaic=NAME # or set PLANET_MOSAICPlanet only accepts the key in the tile URL; mapterm still never prints it.
Your own imagery
Section titled “Your own imagery”--raster also takes a PMTiles archive of PNG, JPEG or WebP tiles, as a file or
an https:// URL read with range requests: one file of your own imagery that
works offline.
The vector overlay
Section titled “The vector overlay”Press v to cycle the vector map on top of the imagery: lines and labels,
labels only, off. Area fills are always off over a raster layer.
Memory and caching
Section titled “Memory and caching”- mapterm keeps at most 48 MiB of decoded images in the terminal, freeing
off-screen tiles first, so the terminal never evicts one that’s showing.
herdr allows 64 MiB per pane.
MAPTERM_KITTY_BUDGET_MBchanges the budget. - Tiles are fetched at most two at a time and cached on disk for 30 days.
- mapterm picks the raster zoom so each image pixel covers about two screen pixels, the Retina norm, which keeps the number of tiles down.
Respect each tile server’s usage policy. OpenStreetMap’s own tile servers allow only light use, with attribution.