Fix what an agent — and a Windows user — hits when using this CLI

[mattpodwysocki]

From a real session: someone pointed a coding agent at this CLI and it stumbled five times. Three of the five were the CLI behaving exactly as designed and saying so clearly — I reproduced each against the released 0.2.1 binary before touching anything. These are the two that weren't.

The skill we ship for agents recommended auth login

Its Authentication section listed the three token sources in precedence order with no comment on which an agent can use. So an agent with no token reads option 3 — "credentials stored by mapbox auth login" — and tries it. That command opens a browser and waits for a person.

We wrote a skill for agents that walks them into the one command agents cannot run.

It now says so on the entry itself, and adds a line after the list: have MAPBOX_ACCESS_TOKEN set, ask the person you're working for if it's missing, and don't reach for auth login when a command reports no token.

The error auth login gives was already right and is unchanged:

{"code":"interactive_required",
 "message":"`mapbox auth login` needs a browser and someone to use it, and this run has no terminal on stdin or stderr.",
 "fix":"Set MAPBOX_ACCESS_TOKEN for a script or a CI job."}

Reaching it at all is the waste.

A blocked config directory now says when it holds a credential

A plain file at ~/.mapbox is what older Mapbox tooling left, and it's a one-line access token — src/auth.rs already anticipated this case by name. The message named the file and gave the mv, which is the right fix, but nothing told the reader whether they were moving junk or a working token. The honest reading of "move it aside" is that something is being thrown away.

When the file looks like a token, it now adds that it still works and how to keep using it:

export MAPBOX_ACCESS_TOKEN="$(cat ~/.mapbox.bak)"

Naming .bak matters — that's the file as it exists after the mv directly above it — and a test holds it, because two steps that contradict each other are worse than one.

The detection is deliberately shallow: a bounded read, a pk./sk./tk. prefix, no whitespace, and any read error answers "no". It runs while reporting a different problem and must not replace it.

The token is never printed. That's the assertion worth having, since an error message reaches every terminal and log that the file's 0600 permissions were keeping it out of. Verified by planting an actual leak and watching the test fail:

test auth::tests::a_legacy_token_file_says_the_token_is_not_lost ... FAILED
  the token itself must never be printed: …

(My first attempt at that check ran cargo test --lib on a binary crate, which errors rather than running anything — it proved nothing until I noticed and redid it.)

What I deliberately didn't change

• mapbox agent-skills uninstall <NAME> already removes project-local skills by default and is documented in references/agent-skills.md, which we ship. The reported failure was the agent's harness denying rm, not us.
• The curl | sh denial is a distribution problem, not a bug — filed separately.
• MCP connection cleanup isn't this CLI.

598 tests, fmt and clippy clean.

[zmofei]

I don’t think moving the user’s files is a good idea. Could we change where we store our credentials instead? For example, if ~/.mapbox already exists and isn’t a directory, we could use ~/.mapbox-cli/.

[mattpodwysocki]

Good challenge, and I agree with the principle — a CLI shouldn't make you rearrange your home directory before it works. Two things make me want to keep the current shape, though, and the first one is that it mostly already does what you're asking.

The file doesn't block anything today

I checked each path with MAPBOX_ACCESS_TOKEN cleared, so nothing was quietly working via the environment:

# legacy ~/.mapbox present, no env token
$ mapbox styles list -u someone
Warning: … is a file, not a directory, so no stored credentials can be read. Move it aside: mv …
{"code":"http_401", …}            ← the command ran

$ mapbox auth whoami
{"code":"not_authenticated","message":"No Mapbox token available.", …}

# legacy ~/.mapbox present, with an env token
$ mapbox auth whoami
{"source":"environment","usage":"pk", …}     ← works

So the file degrades to "there are no stored credentials", the same as a fresh machine. Commands run. It's only auth login and auth logout that refuse, because those are the two that genuinely need the directory to exist.

Worth being precise about the other half too: we never move anything. The message prints a command; whether to run it is the reader's call. Nothing on disk is touched by us.

And the fallback has a trap I'd rather not ship

If the store's location depends on whether ~/.mapbox is a file, then the location can change under the user without them doing anything to the CLI:

1. ~/.mapbox is a legacy file → we store credentials in ~/.mapbox-cli/
2. They log in. Works.
3. Later they tidy up and delete the stray ~/.mapbox file
4. Next command → ~/.mapbox is now free, so we use it → they appear logged out, with their real credentials stranded in ~/.mapbox-cli/

That's a hard one to diagnose from the outside, and the trigger is an action that looks completely unrelated. It also means two documented locations rather than one, which the README and any support conversation then has to hedge on.

MAPBOX_CONFIG_DIR already covers the deliberate version of this — someone who wants the store elsewhere can say so, explicitly and permanently, and a container usually does.

If the friction is still the objection

The change in this PR doesn't add the friction; it adds a sentence to a message that already existed. Before it, the advice was "move this file aside" with no indication of whether you were discarding junk or a working credential — and it is usually a working credential, which is exactly why it's worth saying.

If you'd still rather the legacy file didn't require any action at all, the version I'd argue for is reading it as a token source — treat a one-line pk./sk./tk. file at ~/.mapbox the way we treat MAPBOX_ACCESS_TOKEN, so the old token just works and only auth login ever needs the directory. That keeps one store location, and it removes the request rather than relocating around it.

Happy to do that as a follow-up if you like it. I'd rather not put the second location in, though — that one I think we'd regret.

[zmofei]

@mattpodwysocki thanks for the reply! The idea I'd like to follow here: when the program can solve a problem itself, it should, instead of asking the user to.

On that idea: automatically fall back to ~/.mapbox-cli when ~/.mapbox is blocked, instead of asking for a manual mv.

To your point about reliability: agreed, we should not trust the legacy file's content as a token. It's leftover state, not something the user gave us on purpose like MAPBOX_ACCESS_TOKEN.

To close the trap you described: prefer whichever directory already has a valid store, not whichever path happens to be free. So deleting the stray ~/.mapbox file later won't strand credentials in ~/.mapbox-cli — the CLI keeps using it. If both are valid, ~/.mapbox wins.

This is a real change to how the credential directory is resolved, so it should be its own PR, not ride on this one. Filed #30 to track it. Approving this PR — it's unaffected.