Mapbox CLI
This section is the command reference for the Mapbox CLI (mapbox):
every command group, the commands inside it, and their flags. For an
introduction to the CLI, installing it, and how it behaves, see the
Mapbox CLI guide.
Shared parameters
The command groups that call a Mapbox API — Accounts, Directions, Feedback, Fonts, Geocoder, Isochrone, Map Match, Matrix, Places, Search, Sprites, Static, Styles, Tilesets, and Usage — all take:
| Parameter | Description |
|---|---|
--username/-u | Fills the {username} path placeholder. Falls back to MAPBOX_USERNAME, then to the signed-in user — so you can omit it once you're signed in. |
--token/-t | Access token. Falls back to MAPBOX_ACCESS_TOKEN, then stored credentials. |
--profile <name> | Which stored credentials to use. |
--id <value> | On a command that returns a list, print only the row with that id or name. |
Each command group's own reference page lists only what's specific to it. Alphabetically, the command groups are:
Accounts
Access tokens and the scopes an account can grant them.
Agent Skills
Installs the Mapbox Agent Skills — hand-written guidance for coding agents on building with Mapbox. A different thing from Generate Skills below.
Authentication
Signs the CLI in to your Mapbox account and manages the token every other
command uses: login, logout, refresh, and whoami.
Commands
Finds the command for a task by what it does, or lists every command with its summary. A local lookup: no request and no token.
Completion
Prints a shell completion script on stdout, for bash, zsh, fish, or PowerShell.
Config
Gets or sets CLI settings that persist across shells and sessions: the update check, command history, diagnostic logs, and telemetry.
Directions
Routes between two or more waypoints, from the Directions API.
Doctor
Shows the token, proxies, and settings the next command would use. The first thing to run when a command behaves unexpectedly.
Feedback
Reports wrong or missing map data to Mapbox, and lists what was reported.
Fonts
The font faces map styles render text with.
Generate Skills
Writes the CLI's built-in command surface out as an Agent Skill, for a coding agent to read. A different thing from Agent Skills above.
Geocoder
Converts between place names and coordinates, forward, reverse, and in batches.
History
Lists and shows recent command runs.
Isochrone
The areas reachable from a point within a given time or distance.
Map Match
Snaps a GPS trace to the road network.
Matrix
Travel times and distances between every pair of points.
MCP
Adds the Mapbox MCP servers to a coding agent: Claude Code, Codex, Visual Studio Code, or Cursor.
Places
Full detail for a place, by its Search Box result ID.
Report
Sends feedback about this CLI to Mapbox.
Search
Text search, reverse lookup, category search, and the category list, from the Search Box API.
Sprites
The sprite sheet a style draws its icons from, and the individual icons in it.
Static
A rendered map image or raster tile from a style.
Styles
Map styles and their drafts.
Tilesets
Tiles by tileset ID — raster and vector — plus Tilequery, what vector features exist at or near a given point.
Tilesets-cli alias
Forwards everything verbatim to the separately installed Tilesets CLI — a different program from the Tilesets commands above.
Uninstall
Removes the mapbox binary. Stored credentials and a separately
installed tilesets binary survive.
Usage
Reports account or token usage by product, by day.
Workflow (beta)
Installs and runs workflows: named, multi-step recipes of mapbox
commands and scripts. Beta, so it may change or be removed in any release.
Global options
Global options — --output/-o,
--schema, --yes/-y, --quiet/-q, --timeout, --use-login,
--no-color, and --debug — apply across every command, not only the API
ones above. Every command that changes something also takes --dry-run,
which prints the request instead of sending it.