Config
mapbox config gets or sets settings that persist across shells and
sessions — written to ~/.mapbox/config.json (or $MAPBOX_CONFIG_DIR)
rather than in an environment variable, which only lasts for the shell you
set it in. Each setting is the persistent form of such a variable, and it
stays in every future shell.
| Key | Default | What it controls |
|---|---|---|
update-check | on | The once-a-day notice that a newer release exists. Mirrors MAPBOX_NO_UPDATE_CHECK. |
history | on | Command history, read by mapbox history. MAPBOX_HISTORY=0 or =1 overrides it for a session. |
log | off | Diagnostic logs, shown by mapbox history show. MAPBOX_LOG=1 or =0 overrides it for a session. Needs history on. |
telemetry | on | Usage telemetry, and the update notice along with it. Mirrors MAPBOX_CLI_NO_TELEMETRY. |
All four take on or off. mapbox doctor
shows where the update-check and telemetry switches stand,
environment variables included.
The settings
update-check
mapbox can't update itself, so when a newer release exists it says so once
a day, on stderr, and only at a terminal, so CI and piped runs never check.
The check is a GET for the release manifest with no token and nothing about
you beyond the CLI's version, made from a background process your command
never waits on. mapbox config set update-check off turns it off in every
shell; MAPBOX_NO_UPDATE_CHECK=1 turns it off for one. Turning telemetry
off silences it too.
history
Each run appends one line to ~/.mapbox/history/<UTC date>.jsonl (or under
$MAPBOX_CONFIG_DIR): which command ran (its command path, like
search forward), how it ended, how long it took and the request ids
support can look up. Argument values are never recorded: not what you
searched for, not a file path, not a token. The CLI keeps history for 30 days and
at most 10 MB, dropping the oldest first. It's readable only by you, and never leaves your
machine. --help, --version, completion, history itself and runs
under sudo are not recorded.
With history off, the CLI writes nothing and creates no directory, but
what it already recorded stays until you delete ~/.mapbox/history.
Neither telemetry opt-out affects it.
log
Off by default. When on, each run history records also gets a line of
detail in ~/.mapbox/logs/<UTC date>.jsonl: the command line, each
request's method, URL, status, request id and timing, which token was used
(where it came from, its type and account, never the token itself) and the
error message. Tokens are replaced with <redacted> wherever they appear,
and the files never leave your machine. The CLI keeps logs up to 30 days and
100 MB in total.
Logging needs history: with history off it never runs, and
mapbox config set log on fails with history_required.
telemetry
On by default. Telemetry records which command ran and the shape of its
options (never coordinates, file paths, free text or your access token), how
it ended and how long it took, the CLI version, OS and architecture, and
similar usage metrics; the update notice rides the same opt-out.
mapbox config set telemetry off turns it off in every shell;
MAPBOX_CLI_NO_TELEMETRY=1 turns it off for one. Turning it off doesn't
affect any other functionality. See the Privacy section of the
Mapbox CLI README for the
complete list of what is collected.
mapbox config get
Prints a setting's current value: on/off in text mode, true/false in JSON. Reading a setting that was never set reports its default rather than failing.
Parameters:
| Parameter | Description |
|---|---|
<key> | Which setting to read: update-check, history, log or telemetry. |
Examples:
mapbox config get update-check
mapbox config get history
mapbox config set
Persists a setting, so it survives across shells without an environment variable.
Parameters:
| Parameter | Description |
|---|---|
<key> | Which setting to change: update-check, history, log or telemetry. |
<value> | on or off. |
Examples:
mapbox config set update-check off
mapbox config set telemetry off
mapbox config set log on
mapbox config list
Lists every setting and its current value — get answers one key at a time, this answers every key in one call, falling back to each one's default the same way get does.
Examples:
mapbox config list
$mapbox config list
update-check on
history on
log off
telemetry on
mapbox config unset
Clears a setting back to its default, rather than setting it to that default value explicitly. The difference matters the next time this CLI changes what a setting's default is: a cleared key picks up the new default, a key explicitly set to the old default value does not.
Parameters:
| Parameter | Description |
|---|---|
<key> | Which setting to reset: update-check, history, log or telemetry. |
Examples:
mapbox config unset update-check