Add mapbox auth profiles: list every stored credential profile

CHANGELOG.md

@@ -23,6 +23,12 @@ that may never merge. They are not releases and are not listed here.
   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.
 
+- `mapbox auth profiles` — lists every credential profile stored on disk,
+  not just the one `--profile` would select. Read-only, like `whoami`, and
+  answers a different question than it does: `whoami` reports which token
+  the *next* command will use, this reports what's stored at all, for
+  someone who has forgotten which named profiles they've logged into.
+
 - `mapbox doctor` — a read-only snapshot of what the next command would
   see: which token wins and its state, which proxy variables are in effect,
   and where the update-check and telemetry switches currently stand.

README.md

@@ -145,6 +145,7 @@ mapbox auth login     # opens a browser (OAuth/PKCE)
 mapbox auth logout    # removes stored credentials
 mapbox auth refresh   # force-refreshes the access token
 mapbox auth whoami    # reports which token the next command will use
+mapbox auth profiles  # lists every stored profile, not just one
 ```
 
 Credentials live in `~/.mapbox` as plain JSON with locked-down file
@@ -160,6 +161,7 @@ wants.
 ```sh
 mapbox auth login --profile android_app
 mapbox --profile android_app styles list
+mapbox auth profiles              # which profiles are actually stored
 ```
 
 ### API Related

docs/commands.md

@@ -1,6 +1,6 @@
 # Implemented commands
 
-Every command the CLI ships: four auth commands, 33 API operations across 10
+Every command the CLI ships: five auth commands, 33 API operations across 10
 command groups, the tilesets-cli proxy, `completion` and `generate-skills`. Each is
 shown in both of its renderings. Which one you get is decided by `--output`, whose default
 (`auto`) reads stdout: a terminal gets the left column, a pipe or redirect
@@ -45,7 +45,7 @@ nests, and is typed `mapbox styles draft get`.
 
 **[Auth](#auth)** — [auth.login](#mapbox-auth-login) ·
 [auth.logout](#mapbox-auth-logout) · [auth.refresh](#mapbox-auth-refresh) ·
-[auth.whoami](#mapbox-auth-whoami)
+[auth.whoami](#mapbox-auth-whoami) · [auth.profiles](#mapbox-auth-profiles)
 
 **[Agent skills](#agent-skills)** —
 [agent-skills.list](#mapbox-agent-skills-list) ·
@@ -119,15 +119,17 @@ Then [Errors](#errors) — the shape a failure takes in each mode.
 Credentials live in `~/.mapbox`, one file per profile — or in whatever
 directory `MAPBOX_CONFIG_DIR` names, when it is set.
 
-All four commands take:
+All five commands take:
 
 | Parameter | Effect |
 | --- | --- |
 | `--profile <name>` | Which credential file to act on. Default `default`. |
 | `--output`, `-o` | `auto` \| `text` \| `json`. |
 
 `login`, `logout` and `refresh` take `--dry-run` as well. `whoami` does not,
-for the reason its own section gives.
+for the reason its own section gives. `profiles` takes `--profile` too, in
+the sense that it parses — but doesn't honor it, since that command's whole
+point is every stored profile at once; see its own section for why.
 
 ### `mapbox auth login`
 
@@ -348,6 +350,86 @@ Docs: https://docs.mapbox.com/api/accounts/tokens/
 </td></tr>
 </table>
 
+### `mapbox auth profiles`
+
+Lists every profile with credentials stored on disk — not just the one
+`--profile` would select. `whoami` answers which token the *next* command
+will use; this answers what is stored at all, for someone who has forgotten
+which named profiles they have logged into.
+
+Read-only, like `whoami`: it reads the stored credentials without
+refreshing, so listing profiles cannot spend a single-use refresh token —
+and it reads each one through a path that never creates or hardens the
+config directory, so listing what exists is never the reason a directory
+starts to exist or its permissions change. Unlike `whoami`, it never
+resolves `--token` or the environment — a typed flag or
+`MAPBOX_ACCESS_TOKEN` would outrank every stored profile for the *next*
+command, but neither has anything to do with what is on disk.
+
+**`--profile` from [the table above](#what-every-api-command-takes) is the
+one exception on this page: this command does not honor it.** That table's
+`--profile <name>` selects which single stored profile a command reads —
+the opposite of this command's whole point, which is every one of them at
+once. Typing it anyway parses (it is declared globally) but changes
+nothing, so it is warned about on stderr rather than silently ignored.
+
+An expired token reads as `expired`, not with the "check this machine's
+clock" phrasing `whoami` uses for a token about to be used right now — a
+stored profile may have been sitting untouched for weeks, where that
+clock-skew guess would be wrong far more often than right.
+
+#### Parameters
+
+None. There is no `--dry-run`: the command only reads the store.
+
+#### Examples
+
+```sh
+mapbox auth profiles
+
+# --profile is warned about, not honored — see above
+mapbox auth profiles --profile work
+```
+
+#### Outputs
+
+<table>
+<tr><th width="50%">Terminal — <code>-o text</code></th><th width="50%">Agent — <code>-o json</code></th></tr>
+<tr><td>
+
+```
+default  user       expires in 58 minutes
+work     work-user
+```
+
+</td><td>
+
+```json
+[{"account":"user","expires_at":1790172530,"profile":"default"},{"account":"work-user","expires_at":null,"profile":"work"}]
+```
+
+</td></tr>
+</table>
+
+With nothing stored:
+
+<table>
+<tr><th width="50%">Terminal — <code>-o text</code></th><th width="50%">Agent — <code>-o json</code></th></tr>
+<tr><td>
+
+```
+No stored profiles. Run `mapbox auth login` to create one.
+```
+
+</td><td>
+
+```json
+[]
+```
+
+</td></tr>
+</table>
+
 ---
 
 ## API command groups