# 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`](https://docs.mapbox.com/ja/cli/reference/history/). `MAPBOX_HISTORY=0` or `=1` overrides it for a session. |
| `log` | `off` | Diagnostic logs, shown by [`mapbox history show`](https://docs.mapbox.com/ja/cli/reference/history/). `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`](https://docs.mapbox.com/ja/cli/reference/doctor/) shows where the update-check and telemetry switches stand, environment variables included.

-   [`mapbox config get`](#mapbox-config-get)
-   [`mapbox config set`](#mapbox-config-set)
-   [`mapbox config list`](#mapbox-config-list)
-   [`mapbox config unset`](#mapbox-config-unset)

## 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](https://github.com/mapbox/mapbox-cli#privacy) 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:**

```sh
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:**

```sh
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:**

```sh
mapbox config list
```

```console
$ 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:**

```sh
mapbox config unset update-check
```