Global options
These apply globally, across every command — not only the API ones.
The credential options --token/-t, --username/-u and --profile are
global too; Shared parameters covers
them, and Authentication the credentials
they fall back to.
--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 | Everything on stdout is JSON: one compact document per command |
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.
-o json at a terminal indents the document, since a person is reading it;
piped or redirected, it's one compact line.
--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. That is
every POST, PUT, PATCH and DELETE API operation, plus auth login,
auth logout, auth refresh and generate-skills. 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, agent-skills update/uninstall
when they'd change or remove a file, and
workflow uninstall:
$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.
One question only the typed flag answers: workflow install from a source
the CLI does not vouch for asks first, and MAPBOX_YES does not answer it.
See mapbox workflow.
--timeout
| Request | Budget |
|---|---|
A normal request (GET, or a typed --data body) | 60 seconds |
A --file upload, or a --data @<path> / @- body | 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.
--id
On a command that returns a list, --id <ID> prints only the row whose id
or name matches, instead of the whole table:
mapbox accounts list-tokens --id cmtoken00000000000000001a
On a paginated listing it searches only the page that came back, so a miss means "not on this page" rather than "does not exist"; the error names the flags that fetch the next page.
--quiet/-q
At a terminal, a run opens with a mapbox · v<version> line on stderr.
--quiet/-q (or MAPBOX_QUIET=1) hides it, along with the note printed
after a download and a workflow step's details. None of these reach a pipe
or a file to begin with.
--no-color
At a terminal, help, tables, labels and tips are in color. --no-color
turns that off, as the NO_COLOR environment variable does.
FORCE_COLOR=1 keeps color on into a pipe, for a pager such as less -R;
--no-color and NO_COLOR win over it.
--debug
Prints request URLs to stderr, for troubleshooting. MAPBOX_DEBUG=1 sets
the same thing for a whole shell.