Skip to main content
For the complete documentation index, see llms.txt.

Mapbox CLI

  • check
    A unified, agent-first interface to the Mapbox developer platform
  • check
    Built for coding agents, just as scriptable for people
  • check
    Human-readable output at a terminal, JSON everywhere else
InstallgithubContribute on GitHub

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 (authentication, Accounts, Fonts, Geocoding, Search, Sprites, Static, Styles, and Tilesets) without leaving the shell.

The Mapbox CLI is in public beta

Some commands may change before general availability. Public beta features don't carry the same support commitments as generally available features.

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 — no sudo, no admin rights required. Run mapbox --help once it's on your PATH.

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.

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​

When a newer release exists, mapbox says so once a day, on stderr, at a terminal:

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

This is the only request the CLI makes that you didn't ask for, so it's kept narrow: it 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. MAPBOX_NO_UPDATE_CHECK=1 turns it off, and so does MAPBOX_CLI_NO_TELEMETRY=1 below.

Privacy​

Mapbox collects telemetry from this CLI, on by default, to understand adoption and improve reliability, performance, and developer experience. It's added to the User-Agent every request already carries: your OS and architecture, whether you're running in CI, which coding agent you're running in (if any), whether stdin/stdout are attached to a terminal, and — for an API command — which command group ran (for example styles or geocoder), never the specific operation or its arguments. Every request also carries the IP address it's sent from, which isn't retained alongside telemetry.

It never includes AI prompts, code completion output, source code, project or directory names, command arguments, or non-Mapbox API keys or credentials. Only Mapbox sees it — never third parties, aside from the cloud storage and hosting providers that keep the infrastructure running.

MAPBOX_CLI_NO_TELEMETRY=1 turns it off, and silences update notices above too, 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.

Was this page helpful?