WIP: Record one cli.command telemetry event per run

CHANGELOG.md

@@ -19,6 +19,22 @@ that may never merge. They are not releases and are not listed here.
 
 ## Unreleased
 
+- Command history, on by default: each run appends one line to
+  `~/.mapbox/history/<date>.jsonl`, kept 30 days and at most 10 MB, with its command path, exit
+  code, error code, duration and request ids — never an argument value. It
+  stays on your machine. `mapbox history list` and `mapbox history show`
+  read it back. Turn it off with `mapbox config set history off` or
+  `MAPBOX_HISTORY=0`. A script sees no change on stdout, stderr or the exit
+  code; it does find a `~/.mapbox/history` directory it didn't before, and
+  `mapbox config list` now reports a second key, `history`.
+
+- Each run records one `cli.command` telemetry event, appended to
+  `~/.mapbox/.telemetry/<date>.jsonl` and kept for 7 days. Nothing is sent
+  anywhere by default. It never touches stdout, the exit code or how long a
+  command takes, so a script sees no difference; a CI job does find a
+  `.mapbox/.telemetry` directory it didn't before. `MAPBOX_CLI_NO_TELEMETRY=1`
+  turns it off.
+
 - `MAPBOX_CLI_EXTRA_QUERY` appends raw query parameters to every request, in
   the same `k1=v1&k2=v2` shape as a URL's own query string — for an API
   parameter this CLI's specs don't declare a flag for.

README.md

@@ -23,6 +23,7 @@ time from OpenAPI specs, so they always match the specs.
   - [`--schema`](#--schema)
   - [Confirmation and `--yes`](#confirmation-and---yes)
   - [Update notices](#update-notices)
+  - [Command history](#command-history)
  - [Privacy](#privacy)
 - [Uninstall](#uninstall)
 - [Contributing](#contributing)
@@ -204,6 +205,12 @@ Every request sends `User-Agent: mapbox-cli/<version>` and nothing else
 about you or your machine. `MAPBOX_CLI_NO_TELEMETRY=1` keeps even future markers
 out of that header.
 
+Each run also appends one event to `~/.mapbox/.telemetry/<date>.jsonl`
+(kept for 7 days): the command's name, its options (a value only when it
+comes from a fixed list, otherwise just its length or size), how it ended,
+and how long it took — never a token, a file path or free text you typed.
+It stays on this machine. `MAPBOX_CLI_NO_TELEMETRY=1` turns it off.
+
 ### Agent skills
 
 ```sh
@@ -438,6 +445,28 @@ between runs. A build that names no release channel never checks at all, and
 see [Config](docs/commands.md#config) — rather than just the session an
 environment variable happens to be set in.
 
+### Command history
+
+Each run appends one line to `~/.mapbox/history/<UTC date>.jsonl` (or under
+`$MAPBOX_CONFIG_DIR`), kept for 30 days and at most 10 MB, oldest dropped
+first: 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 files are readable only by
+you and never leave your machine.
+
+```sh
+mapbox history list             # the most recent runs, newest first
+mapbox history show             # everything recorded about the newest run
+mapbox history show be40d711    # or one run, by any prefix of its id
+```
+
+`--help`, `--version`, `completion`, `history` itself and runs under `sudo`
+are not recorded. `mapbox config set history off` turns history off for
+good, and `MAPBOX_HISTORY=0` for one shell; with it off, nothing is written
+and no directory is created, but what was already recorded stays until you
+delete `~/.mapbox/history`. `MAPBOX_CLI_NO_TELEMETRY` does not affect it.
+
 ### Privacy
 
 **YOUR PRIVACY - COLLECTION OF TELEMETRY**

docs/commands.md

@@ -64,6 +64,9 @@ nests, and is typed `mapbox styles draft get`.
 [config.set](#mapbox-config-set) · [config.list](#mapbox-config-list) ·
 [config.unset](#mapbox-config-unset)
 
+**[History](#history)** — [history.list](#mapbox-history-list) ·
+[history.show](#mapbox-history-show)
+
 **[Doctor](#doctor)** — [doctor](#mapbox-doctor)
 
 **[Usage](#usage)** — [usage](#mapbox-usage)
@@ -3194,10 +3197,14 @@ Removed /home/user/.local/bin/mapbox.
 ## Config
 
 Settings that persist across shells and sessions — `~/.mapbox/config.json`
-(or `$MAPBOX_CONFIG_DIR`), written the same way credentials are. One setting
-today, `update-check`, which mirrors `MAPBOX_NO_UPDATE_CHECK` (see [Update
-notices](../README.md#update-notices)) but stays off in every future shell
-rather than only the one the environment variable was set in.
+(or `$MAPBOX_CONFIG_DIR`), written the same way credentials are. Each is the
+persisted form of an environment variable that only lasts for the shell it
+was set in, and stays in every future shell instead.
+
+| Key | Default | What it controls |
+| --- | --- | --- |
+| `update-check` | `on` | The update notice; mirrors `MAPBOX_NO_UPDATE_CHECK` (see [Update notices](../README.md#update-notices)) |
+| `history` | `on` | [Command history](../README.md#command-history), read by `mapbox history`; `MAPBOX_HISTORY=0` or `=1` overrides it for a session |
 
 ### `mapbox config get`
 
@@ -3209,7 +3216,7 @@ than failing, the same forgiving read the update-check cache itself uses.
 
 | Parameter | Effect |
 | --- | --- |
-| `<key>` | Which setting to read. Only `update-check` exists today. |
+| `<key>` | Which setting to read: `update-check` or `history`. |
 
 #### Examples
 
@@ -3248,7 +3255,7 @@ without an environment variable.
 
 | Parameter | Effect |
 | --- | --- |
-| `<key>` | Which setting to change. Only `update-check` exists today. |
+| `<key>` | Which setting to change: `update-check` or `history`. |
 | `<value>` | `on` or `off`. |
 
 #### Examples
@@ -3305,6 +3312,7 @@ mapbox config list
 
 ```
 update-check	on
+history	on
 ```
 
 </td><td>
@@ -3314,6 +3322,10 @@ update-check	on
   {
     "key": "update-check",
     "value": true
+  },
+  {
+    "key": "history",
+    "value": true
   }
 ]
 ```
@@ -3332,7 +3344,7 @@ default, a key explicitly set to the old default value does not.
 
 | Parameter | Effect |
 | --- | --- |
-| `<key>` | Which setting to clear. Only `update-check` exists today. |
+| `<key>` | Which setting to clear: `update-check` or `history`. |
 
 #### Examples
 
@@ -3364,6 +3376,147 @@ update-check cleared, now on (default).
 
 ---
 
+## History
+
+The runs [command history](../README.md#command-history) recorded on this
+machine over the last 30 days, up to 10 MB: which command ran, how it ended, how long it
+took and the request ids support can look up. Argument values are never
+recorded, so a run shows as its command path — `mapbox search forward`,
+not what was searched for. History is on by default; with it off
+(`mapbox config set history off`), both commands find nothing and say why
+on stderr. Neither makes a request or needs a token, and neither is itself
+recorded — nor are `--help`, `--version`, `completion` or a run under
+`sudo`.
+
+### `mapbox history list`
+
+The most recent runs, newest first: a short id, when it ran (UTC), its exit
+code and its command path. `json` gives each run's full `id`, which
+`history show` also accepts shortened to any prefix that names one run.
+
+#### Parameters
+
+| Parameter | Effect |
+| --- | --- |
+| `--limit <n>` | How many runs to list. Defaults to `20`; `0` lists every recorded run. |
+
+#### Examples
+
+```sh
+mapbox history list
+
+mapbox history list --limit 0
+```
+
+#### Outputs
+
+<table>
+<tr><th width="50%"><code>text</code></th><th width="50%"><code>json</code></th></tr>
+<tr><td>
+
+```
+ID        TIME                      EXIT  COMMAND
+d05b3f4d  2026-09-28T11:20:03.095Z     2  mapbox styles
+be40d711  2026-09-28T11:20:03.045Z     1  mapbox styles list
+```
+
+</td><td>
+
+```json
+[
+  {
+    "command": [
+      "styles"
+    ],
+    "durationMs": 41,
+    "errorCode": "usage",
+    "exitCode": 2,
+    "id": "d05b3f4d-9947-4662-a037-3d00b68d1d6e",
+    "time": "2026-09-28T11:20:03.095Z"
+  },
+  {
+    "command": [
+      "styles",
+      "list"
+    ],
+    "durationMs": 157,
+    "errorCode": "http_401",
+    "exitCode": 1,
+    "id": "be40d711-3d62-4e9b-8dde-23535020b368",
+    "time": "2026-09-28T11:20:03.045Z"
+  }
+]
+```
+
+</td></tr>
+</table>
+
+### `mapbox history show`
+
+Everything recorded about one run: its command path, how it ended, its
+error code, how many requests it made and the ids of the last five. `json`
+gives the record as it was written. An id that names no run fails with
+`history_not_found`; a prefix shared by several fails with
+`history_ambiguous_id`; with nothing recorded yet, `show` with no id fails
+with `history_empty`.
+
+#### Parameters
+
+| Parameter | Effect |
+| --- | --- |
+| `[id]` | The run's id, or any prefix of it that names one run. The newest run when left out. |
+
+#### Examples
+
+```sh
+mapbox history show
+
+mapbox history show be40d711
+```
+
+#### Outputs
+
+<table>
+<tr><th width="50%"><code>text</code></th><th width="50%"><code>json</code></th></tr>
+<tr><td>
+
+```
+Run       be40d711-3d62-4e9b-8dde-23535020b368
+Time      2026-09-28T11:20:03.045Z (mapbox 0.3.0)
+Command   mapbox styles list
+Exit      1 after 157 ms
+Error     http_401
+Requests  1
+  request id 7ovbf8wEjg4S_uS-u8SNW0OHb64pCVgD5fThd2C2q9ZlE7bDY-s0yw==
+```
+
+</td><td>
+
+```json
+{
+  "command": [
+    "styles",
+    "list"
+  ],
+  "durationMs": 157,
+  "errorCode": "http_401",
+  "exitCode": 1,
+  "id": "be40d711-3d62-4e9b-8dde-23535020b368",
+  "invocation": "execute",
+  "requestCount": 1,
+  "requestIds": [
+    "7ovbf8wEjg4S_uS-u8SNW0OHb64pCVgD5fThd2C2q9ZlE7bDY-s0yw=="
+  ],
+  "time": "2026-09-28T11:20:03.045Z",
+  "version": "0.3.0"
+}
+```
+
+</td></tr>
+</table>
+
+---
+
 ## Doctor
 
 ### `mapbox doctor`

src/account_usage.rs

@@ -508,7 +508,7 @@ fn days_from_civil(y: i64, m: u32, d: u32) -> i64 {
 }
 
 /// The inverse of [`days_from_civil`].
-fn civil_from_days(z: i64) -> (i64, u32, u32) {
+pub(crate) fn civil_from_days(z: i64) -> (i64, u32, u32) {
     let z = z + 719468;
     let era = z.div_euclid(146097);
     let doe = z - era * 146097; // [0, 146096]