A terminal map viewer and journey planner for GPX, FIT, TCX and KML files, with a JSON CLI and local MCP server. Mapbox adds basemaps, place search and road routing; local files and straight-line journeys work offline.
Getting started · Usage · Agent usage · Themes · Other terminal maps
mapbox-tui_0.1.0_2026-10-15-2x-silent-10mb.mp4
The demo shows place search, activity playback with an elevation profile, theme switching, journey planning and copying a command to reopen the journey.
- Activity inspection and playback. Inspect recorded points and distances, view elevation profiles and replay tracks at different speeds. Playback uses recorded timing where available and labelled estimates otherwise.
- Multiple files. Load activities and planned routes together, select or hide individual items, and compare elevation profiles on a shared distance axis.
- Journey planning. Pick stops on the map and reorder waypoints. Straight-line plans work offline; Mapbox provides place search and walking, cycling and driving routes.
- Favourite places. Save commonly used locations locally, then find, rename or remove them. Reuse saved places offline in quick search or as journey stops. See favourites controls.
- Shareable journey commands. Copy stops, travel mode and imported file paths into a command to reopen the plan. Road routes recalculate; preferences aren't included.
- Saved workspaces. Manually save and reopen files, journeys and unfinished drafts. Search, sort, rename, duplicate or delete saves. Original import files required; no autosave or automatic session/crash recovery.
- Remembered preferences. Keep theme, ASCII, animation, elevation and last centre/zoom across launches. Safe start bypasses saved preferences; Start clean empties the working workspace without deleting saves.
- CLI and MCP. Get JSON summaries, inspect points by distance and render ANSI-free text maps. The local MCP server keeps loaded files, selection and visibility in its own workspace.
- Remote control through CLI and MCP. Let an agent control a running map: move the camera, edit journeys, manage imports, set playback speed and themes, or save and open workspaces. Discover viewers by session name or UUID. See remote access.
- Offline file support. Import GPX, FIT, TCX and KML files, view elevation and replay recordings without an account. Connected features include Mapbox basemaps, search, road routing and an optional traffic overlay in the viewer.
- Rendering and controls. Braille and ASCII rendering, full keyboard and mouse navigation, map rotation, six built-in colour palettes and custom themes.
For prebuilt Linux x86-64 binaries, see GitHub Releases and the installation instructions. Until the first release is published, build from source below.
You'll need Go 1.27.1 or newer (see go.mod). The Linux/macOS example below uses Make; see Platforms for a Windows build.
git clone https://github.com/adamcbrewer/mapbox-tui.git
cd mapbox-tui
make build && ./bin/mapbox-tui fixtures/country-ride.gpx --no-providerThat opens an activity without any Mapbox account setup. Swap in your own
file, or run ./bin/mapbox-tui to explore without one. Press ? for controls
and q to quit.
On Linux x86-64, make install puts the binary in ~/.local/bin.
For basemaps, place search and road routing, connect Mapbox.
Before authenticating, review billing risks and set up
usage alerts. Monitoring usage and charges is your responsibility.
Using it yourself? See Usage for keyboard shortcuts, CLI commands and saved workspaces.
Using an agent? See Agent usage for MCP setup, live viewer control and example prompts.
You'll need a Mapbox account for online maps, place search and road routing. Mapbox offers product-specific free allowances. See the signup guide and the billing guidance below.
You can either sign up directly through the Mapbox Console or during a Mapbox MCP server connection.
Choose hidden public API token entry or browser login:
./bin/mapbox-tui auth login
./bin/mapbox-tui auth statusPublic tokens created in the Mapbox Console need no CLI. Browser login requires the
optional official Mapbox CLI, which owns
the shared OAuth credentials and refresh. Entered tokens are saved privately in the
Mapbox TUI config directory. MAPBOX_ACCESS_TOKEN overrides either method.
The viewer, CLI and MCP reuse the selected method and your saved billing-risk acknowledgement. CLI login and in-app login present the same confirmation before enabling online features.
You can also supply a public token through MAPBOX_ACCESS_TOKEN for scripts. --no-provider disables the basemap, even having authed;
local file inspection and manual journey planning work without Mapbox.
For a server or other machine without a browser, see remote authentication options.
Mapbox requests use your account and may incur charges. See the Mapbox notes for configuration, usage, caching and attribution.
Mapbox TUI aims to support personal use within Mapbox's free allowances, but free use is not guaranteed. Online features, background refreshes and bugs can make billable requests. Use online features at your own discretion: you are responsible for monitoring your account and any charges. The app does not enforce a spending cap.
Check the current pricing for each product and set up usage alerts before continuing online. Alerts send notifications; they do not stop requests or charges. Maps and traffic, search sessions, geocoding and routing can use separate allowances, and some products may have no free allowance.
Mapbox settings shows current-month usage for products used by this app, with a Usage details view and a link to your account usage. These are account-wide figures for the named saved-login account, including other applications. An environment token used for maps may belong to a different account. Statistics can be delayed or unavailable; they are not an invoice or a remaining free allowance.
Choose Continue offline in the confirmation, or Go offline in Mapbox settings, to disable online maps, traffic, place lookup and routing. Coordinates, local favourites and imported files remain usable. This choice persists until you choose Go online or successfully sign in again. Failed or cancelled login keeps your previous offline choice. An authenticated account still makes one account-usage check at viewer startup, including in offline mode.
See Mapbox billing and usage guidance for recommendations, statistics limitations and unattended CLI/MCP setup.
There are some other great TUI projects out there which I drew inspiration from, but feature support and active development made me decide to take a fresh approach. The main idea is Mapbox TUI would bring activity files, journey planning and CLI/MCP inspection together, using the features of Mapbox's ecosystem to drive a Google Maps sort of experience.
| Feature | Mapbox TUI | MapSCII | ttymap | TerminalMap |
|---|---|---|---|---|
| Interactive terminal map | ✓ | ✓ | ✓ | ✓ |
| Braille rendering | ✓ | ✓ | ✓ | ✓ |
| Keyboard and mouse navigation | ✓ | ✓ | ✓ | ✓ |
| GPX, FIT, TCX and KML imports | ✓ | - | - | - |
| Activity elevation profiles | ✓ | - | - | - |
| Estimated elevation along planned routes | (proposed) | - | - | - |
| Recorded activity playback | ✓ | - | - | - |
| Visual comparison of imported routes | ✓ | - | - | - |
| Choose colours for individual imported activities | (proposed) | - | - | - |
| Journey planning with waypoints | ✓ | - | - | - |
| Saved favourite places / bookmarks | ✓ (offline reuse) | - | Saved views via bookmark plugin | - |
| Walking, cycling and driving routes | Mapbox | - | - | - |
| Copy a command to recreate a journey | ✓ | - | - | - |
| Save and reopen workspaces | ✓ (manual; original imports required) | - | - | - |
| Automatically save UI preferences and last camera view | ✓ | - | - | - |
| Automatic session/crash recovery | Deferred | - | - | - |
| Headless map rendering | ANSI-free text via CLI/MCP | - | ANSI snapshots via CLI | ANSI frames via Rust SDK |
| JSON activity summaries and point inspection | ✓ | - | - | - |
| Local MCP server with a session workspace | ✓ | - | - | - |
| Remote access to a running viewer through CLI and MCP | ✓ | - | - | - |
| Lua plugins and scripted scenes | - | - | ✓ | - |
| Embeddable map SDK | - | - | - | Rust SDK |
| Multiple independent map views | - | - | - | Via SDK |
| Custom vector tile servers | - | ✓ | - | ✓ |
| Offline activity file inspection | ✓ | - | - | - |
| Offline basemaps | - | Local vector tiles / MBTiles | MBTiles/PMTiles proposed | Bundled zoom 0 and 1 tiles |
| Persistent disk tile cache | (in-memory only) | ✓ | ✓ | ✓ |
This is just a comparison of documented workflows, checked 14 October 2026, not a feature audit.
Favourites and persistence/recovery rows checked 20 October 2026, including ttymap's
configuration
and bookmark implementation.
- means unsupported or not documented. Named view bookmarks aren't full workspace
saves or automatic last-view restoration. Other rows retain their check dates above.
Choose Colour theme from the Ctrl-K command palette to preview a palette,
or start with --theme synthwave. Click a screenshot to see it at full size.
See Terminal themes for all six built-in palettes and custom themes. New ones can easily be added.
Catppuccin
|
Synthwave
|
Paper
|
Noir
|
The Go binary cross-compiles for Linux, macOS and Windows on x86-64 and ARM64. CI runs the tests and terminal interaction checks on Linux. Native macOS and Windows runtime behaviour has not yet been verified.
The viewer needs an interactive terminal with ANSI/VT support. The optional Mapbox CLI publishes binaries for all three platforms. Imported files work without it.
On Windows, build and run directly with Go from the repository root in PowerShell:
go build -trimpath -o bin/mapbox-tui.exe ./go
.\bin\mapbox-tui.exe fixtures/example.gpx --no-providermake install and make package currently require Linux x86-64. On macOS and
Windows, build from source and put the binary on your PATH yourself.
The development watcher, terminal interaction checks and shell-based auth test helpers need a Unix-like environment. The viewer's Copy journey to clipboard command uses POSIX shell quoting; adapt copied commands for PowerShell or Command Prompt.
Contributions are welcome, especially docs improvements, bug reports and feature requests. Try the setup or MCP examples and send a small PR for anything unclear, outdated or missing.
Open an issue to report a bug or suggest a feature. Include steps to reproduce the bug or explain what you'd like to do. See Contributing for more details.
You'll also need Python 3.11 or newer. Use make dev to rebuild on changes and
make check to run the offline checks. See development notes for the
local workflow and terminal prerequisites.