Global options
These apply globally, across every command — not only the API ones.
--output/-o
--output/-o (or MAPBOX_OUTPUT) picks the shape:
| Value | Result |
|---|---|
auto (default) | text at a terminal, json when piped |
text | Pretty-printed, readable |
json | One compact document |
Errors always go to stderr and never appear in stdout. Under json they're
one flat object: code, message, and — where there's advice —
fix/next_actions/docs.
--schema
mapbox <command> --schema describes a command as JSON instead of running
it — its arguments, their types, and the request it would make. Needs no
token.
mapbox styles get --schema # one command
mapbox --schema # the whole CLI
--dry-run
Every mutating built-in command takes --dry-run: it prints the request
instead of sending it, validating --data/--file along the way. This
does not apply to tilesets-cli, which proxies to a separately installed
program with its own flags.
$mapbox styles delete zz-clitest-style --dry-run
Dry run — nothing was sent.
DELETE https://api.mapbox.com/styles/v1/you/zz-clitest-style?access_token=<redacted>
It goes after the operation name (mapbox styles delete ID --dry-run), not
before. A read-only command refuses it.
--yes/-y
Destructive commands ask for confirmation, and only at a terminal — a
DELETE command, mapbox uninstall, and agent-skills update/uninstall
when they'd change or remove a file:
$mapbox styles delete my-style
About to DELETE https://api.mapbox.com/styles/v1/me/my-style
Continue? [y/N] n
--yes/-y/MAPBOX_YES=1 skips the question — for CI, or a script run at a
terminal on purpose. It does not apply to auth login, which always needs a
person.
--timeout
| Request | Budget |
|---|---|
A normal request (GET, or a --data body) | 60 seconds |
A --file upload | 15 minutes |
--timeout <SECONDS> overrides either; MAPBOX_TIMEOUT sets it for a whole
shell.
--use-login
Ignores MAPBOX_ACCESS_TOKEN in the environment and uses the credentials
stored by mapbox auth login
instead. It's the flag to reach for when a token left in a shell profile is
shadowing a login for a different account. A --token typed on the
command line still outranks it.
--debug
Prints request URLs to stderr, for troubleshooting. MAPBOX_DEBUG=1 sets
the same thing for a whole shell.