Mapbox CLI

The Mapbox CLI (mapbox) is a unified, agent-first command-line interface for interacting with Mapbox products directly from your terminal or within AI-assisted agentic coding workflows. It gives developers — and the agents they work with — a scriptable, composable interface to the Mapbox developer platform (styles, sprites, fonts and tilesets; search and geocoding; directions, matrix, isochrone and map matching; and your account's tokens and usage) without leaving the shell.

Install

macOS/Linux:


curl -fsSL https://cli.mapbox.com/install.sh | sh

Windows:


irm https://cli.mapbox.com/install.ps1 | iex

The install script detects your platform, downloads the matching build, checks its SHA-256 checksum, and installs mapbox into ~/.local/bin — no sudo, no admin rights required. Run it again to update. Run mapbox --help once it's on your PATH.

On macOS or Linux you can also use Homebrew, which installs shell completions too and updates with brew upgrade mapbox:


brew install mapbox/tap/mapbox

Builds are published for macOS (Apple silicon and Intel), Linux (aarch64 and x86_64), and Windows (x86_64 and native aarch64).

Pin a version

MAPBOX_CLI_VERSION installs a specific version instead of the newest, with or without the leading v, so the version mapbox --version prints can be pasted straight in:


curl -fsSL https://cli.mapbox.com/install.sh | MAPBOX_CLI_VERSION=1.1.1 sh


$env:MAPBOX_CLI_VERSION = '1.1.1'; irm https://cli.mapbox.com/install.ps1 | iex

What the installer asks

Both scripts put the install directory on your PATH: install.sh adds a line to your shell profile, install.ps1 edits the user PATH. Set MAPBOX_NO_MODIFY_PATH=1 to skip that, or MAPBOX_INSTALL_DIR to choose where the binary lands.

If the script finds a coding agent, it asks once whether to set up this CLI's own skill (mapbox generate-skills) and the Mapbox Agent Skills for it. It then asks separately whether to add the Mapbox MCP servers to your coding agents (mapbox mcp install --global). With no terminal to ask on, such as in CI or a container, the answer to both is no. MAPBOX_CLI_NO_AGENT_SETUP=1 skips both questions.

On macOS and Linux, install.sh also offers to install the Tilesets CLI. MAPBOX_INSTALL_TILESETS=yes or no answers that in advance. To install without being asked anything:


curl -fsSL https://cli.mapbox.com/install.sh | MAPBOX_CLI_NO_AGENT_SETUP=1 MAPBOX_INSTALL_TILESETS=no sh

To remove the CLI, run mapbox uninstall, or brew uninstall mapbox if you installed it with Homebrew.

Set up with a coding agent

Paste the prompt below into your coding agent, such as Claude Code or Cursor. It will install the Mapbox CLI, guide you through sign-in, and explore the available commands so you can start using them together.


Set up the Mapbox CLI for me.

1. Install the CLI: run `curl -fsSL https://cli.mapbox.com/install.sh | sh`
   (macOS/Linux) or `irm https://cli.mapbox.com/install.ps1 | iex`
   (Windows).
2. Teach yourself the command surface: run `mapbox generate-skills`,
   which writes an Agent Skill (https://code.claude.com/docs/en/skills)
   describing every command group into the working directory (or
   `--dir <path>`) — read what it writes before using the CLI.

Once that's done, let me know it's ready. Remind me I can sign in any
time with `mapbox auth login`, which opens a browser to complete it.

Step 2 is what step 1 doesn't give an agent on its own: --help and --schema are always there once mapbox is installed, but an agent that has never seen this CLI has no reason to go looking for them. generate-skills puts the whole surface — every command, its flags, and worked examples — in front of it as one file it will read.

Running commands

The CLI exposes everything as a command:


mapbox <command-group> <command> [args] [flags]

For example, retrieve a style:


mapbox styles get <STYLE_ID> --username <USERNAME>

Create a style:


mapbox styles create \
  --username <USERNAME> \
  --data '{"name": "My Style", "version": 8}'

See the Mapbox CLI reference for every command group and command, the shared parameters API commands take, and Global options — flags that apply across the whole CLI.

Find a command


mapbox commands search upload a font   # the commands that match a task, best first
mapbox commands list                   # every command with its summary

Both are local keyword searches over the CLI's own commands: no model, no request, and no token. Agents get the same matches as JSON, and mapbox --schema describes every command, its arguments, and the request it makes as one JSON document. See Commands.

Diagnostics and settings


mapbox doctor                        # the token, proxies and settings the next command would use
mapbox config set update-check off   # a setting that persists across shells
mapbox history list                  # recent runs, newest first
mapbox report                        # send feedback about this CLI to Mapbox

mapbox doctor is the first thing to run when a command behaves unexpectedly. It makes no request unless you pass --verify. See Doctor, Config, History, and Report.

Output format

Most commands render two ways: a human-readable format at a terminal, or JSON when the output isn't a terminal — piped, redirected to a file, or run in CI — or when --output json is passed explicitly. See --output/-o in Global options for the full picture, including the text/json values and the MAPBOX_OUTPUT environment variable.

Update notices

mapbox can't update itself, so when a newer release exists it says so at most once a day, on stderr, at a terminal:


A newer mapbox is available: 1.2.0 (this is 1.1.1).
Update: curl -fsSL https://cli.mapbox.com/install.sh | sh
Silence this: MAPBOX_NO_UPDATE_CHECK=1

If you installed with Homebrew, run brew upgrade mapbox instead.

The check fetches the release channel's manifest — no token, no account, no command, nothing about you or your machine beyond User-Agent: mapbox-cli/<version> — from a detached background process that your command never waits on. It only runs when stderr is a terminal, so CI and piped runs never check and never print.

MAPBOX_NO_UPDATE_CHECK=1 turns it off for the shell it's set in, and mapbox config set update-check off turns it off in every shell. Turning telemetry off (below) silences it too.

Builds before 1.1.1 never showed this notice, so if you're on one of them, reinstall to get the latest.

Versioning and compatibility

Versions follow semantic versioning: a breaking change bumps the major version (1.4.2 → 2.0.0), a new feature the minor, and a fix the patch. Breaking means a command or flag removed, renamed, or given a new default; an exit code or stdout/stderr change; or a --schema field removed or repurposed. New commands, new API response fields, new --schema fields, and wording changes are not breaking.

Beta commands

A command marked beta, such as mapbox workflow, is outside this promise until the label is removed: it says so in its help and on every run, and it may change or be removed in any release.

Deprecated commands and endpoints print a warning before the request goes out, and are marked [deprecated] in --help and --schema.

Privacy

Mapbox collects telemetry from this CLI, on by default, to understand how it's used and to improve the reliability, performance, and developer experience of our command-line tools.

What is collected: installs; the service a Mapbox API command belongs to (for example styles or geocoder); the command that ran and the shape of its options (values only for flags, fixed choices, numbers, and language, country, or feature-type codes — never coordinates, file paths, or free text); the global options it used (such as --output, --dry-run, or whether a named profile was used); how it ended and how long it took; how many requests it made, with their HTTP status and sizes; the kind of token it used and the Mapbox account that token belongs to; the CLI's own public token that sends the event; a random identifier that is replaced every day; which run started this one when it ran inside another; the CLI version, how it was installed, the version it was updated from, and any newer one it offered; OS and architecture; whether stdin and stdout are attached to a terminal; an identifier for the AI coding agent running the command, if one is detected; and whether the command ran in CI. Every request necessarily carries an IP address, but Mapbox doesn't keep or analyze it with telemetry.
What is not collected: AI prompts, code completion output, source code, project file names, directory contents, non-Mapbox API keys, or credentials, including your Mapbox access token. Telemetry is always sent with the CLI's own public token, never yours.
Who has access: only Mapbox and its affiliates, plus the cloud storage and hosting providers needed to run the infrastructure.

To turn it off for the shell it's set in:


export MAPBOX_CLI_NO_TELEMETRY=1

or in every shell:


mapbox config set telemetry off

Either one also silences update notices above, since that check rides the same opt-out. See the Mapbox Privacy Policy for how this fits into data processing generally, and your rights over it.

Next steps

See the Mapbox CLI reference for every command group, each command's flags, and the global options that apply across them all, and the release notes for what changed in each version.

Was this page helpful?

Install​

Pin a version​

What the installer asks​

Set up with a coding agent​

Running commands​

Find a command​

Diagnostics and settings​

Output format​

Update notices​

Versioning and compatibility​

Privacy​

Next steps​