terrascope

terrascope is an interactive world map for the terminal. It renders countries, place names, live aircraft, city weather, radar/cloud overlays, earthquakes, and day/night bands with curses, Unicode Braille cells, and terminal colors.

The app is intentionally lightweight at install time. Large map data is downloaded into a user cache the first time it is needed, then reused on later runs.

Country names and abbreviations, plus airport names and locations, are bundled from Natural Earth so they are available offline without a first-run download.

Status

This project is early-stage software. The core map, tabs, keyboard/mouse navigation, live layers, and cache handling are implemented, but APIs and visual details may still change.

Requirements

• Python 3.10 or newer on macOS or Linux/Unix
• A UTF-8 terminal
• A terminal with 256-color or true-color support for the best appearance
• Network access for first-run map downloads and live data layers (optional)

Python dependencies are declared in pyproject.toml:

• numpy
• Pillow
• PyYAML

Installation

For normal use:

pipx install terrascope
terrascope

Package managers

Terrascope also includes recipes for Nix and Homebrew:

# Nix, from a Terrascope checkout
nix run ./packaging/nix

# Homebrew, after adding the tap
brew install a-shygun/terrascope/terrascope

PyPI publishing is automated for version tags. The Nix recipe lives in packaging/nix/, and the Homebrew formula lives in Formula/; update their version references when preparing a release.

For local development:

git clone https://github.com/a-shygun/terrascope.git
cd terrascope
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
terrascope

You can also run it from a checkout without installing the console script:

PYTHONPATH=src python3 -m terrascope

First Run and Cache

On first launch, terrascope downloads Natural Earth GeoJSON files into:

$XDG_CACHE_HOME/terrascope

If XDG_CACHE_HOME is not set, the default is:

~/.cache/terrascope

Useful cache commands:

terrascope --show-paths
terrascope --clear-cache
terrascope --offline

Common Options

terrascope --help                         # all options and defaults
terrascope --tab weather --offline        # open a tab using cached data only
terrascope --no-radar --no-airports       # disable optional overlays
terrascope --disable-layer night          # start with a layer disabled
terrascope --config ~/terrascope.yaml     # load additional settings
terrascope --set 'map.zoom.max=128'       # override one setting for this run
terrascope --show-paths                   # show cache and config locations
terrascope --clear-cache                  # remove cached downloads and API data
terrascope --dump-config                  # print effective settings
terrascope --list-keys                    # show active keyboard shortcuts

CLI flags override configuration for the current run. --set overrides flags; see terrascope --help for the full precedence order and every available option.

During first-run downloads the terminal UI shows a loading message before the map appears. Errors and background warnings are written to the log file shown by terrascope --show-paths, so stray output does not corrupt the curses screen.

Controls

Layer-specific keys:

Run this for the effective key list:

terrascope --list-keys

Tabs And Layers

• MAP: base world map with country, province/state, and city detail as zoom allows.
• TIME: day/night bands, sun information, moon information, and timezone selection.
• WEATHER: city weather, forecast panel, radar/cloud overlay, and USGS earthquakes.
• PLANES: OpenSky aircraft positions, trails, categories, and Natural Earth airport markers.

Configuration

Defaults live in:

~/.config/terrascope/default.yaml

On first launch, Terrascope copies the bundled defaults to this location and loads that user-owned copy. Existing files are kept across upgrades. If XDG_CONFIG_HOME is set, Terrascope uses $XDG_CONFIG_HOME/terrascope/default.yaml.

You can override settings without editing the package:

terrascope --config ~/terrascope.yaml
terrascope --set 'map.zoom.max=128'
terrascope --set 'map.land_color="#101018"'

Inspect the final merged config:

terrascope --dump-config

Important environment variables:

Project Layout

src/terrascope/
  __main__.py              python -m terrascope entry point
  assets/                  default configuration and bundled reference data
  core/
    app/                   app lifecycle, input, mouse, and rendering mixins
    ui/                    colors, layout, dialogs, and map drawing
    cli.py config.py       command-line and settings validation
    mapdata.py world.py    geographic data and map state
  layers/
    basemap/               country outlines, labels, and map detail
    daynight/              day/night rendering and astronomy calculations
    flights/               OpenSky API, cache, formatting, and aircraft layer
    weather/               weather, radar, forecast, and earthquake modules

The public console entry point is:

terrascope = "terrascope.__main__:run"

Data Sources

• Natural Earth: country and province/state outlines, populated places
• OpenSky Network: aircraft positions
• Open-Meteo: city weather and forecasts
• LibreWXR-compatible public endpoint: radar/cloud tiles
• USGS GeoJSON feeds: earthquakes
• NOAA/Meeus-style calculations in code: day/night and moon information

Bundled reference data is from Natural Earth 50m Cultural Vectors, which is public domain.

Each source has its own availability and rate-limit behavior. Use --offline when you want to run only from cached data.

Terrascope has no telemetry or analytics. When live layers are enabled, network requests go to the configured data providers. Weather requests include the coordinates of displayed cities; providers also receive your IP address and the Terrascope User-Agent. --offline disables live requests.

Development Checks

Basic syntax check:

python3 -m compileall -q src/terrascope

If dependencies are installed, a quick import smoke test is:

PYTHONPATH=src python3 -c "from terrascope.core.registry import build_layers; print([l.name for l in build_layers()])"

Releasing

Versioned tags build and publish the wheel and source distribution to PyPI. Update the separate Homebrew tap after PyPI confirms the release. See docs/RELEASING.md for the release and Git steps.

License

MIT. See LICENSE.