# Why is `entire auth token` a hidden command?

The answer is documented right in the code. Here's why `entire auth token` is hidden:

**It emits a live credential, so it's deliberately kept off the everyday command surface — it's a scripting escape hatch, not something you'd reach for interactively.**

From `cmd/entire/cli/auth.go:135-140`:

> Hidden: it emits a live credential, so it's a deliberate scripting escape hatch, not part of the everyday surface. It resolves the same bearer the API client would — `ENTIRE_TOKEN` verbatim when set, otherwise the active context's login JWT, refreshed if it's near expiry — and prints nothing but the token (errors and the not-logged-in hint go to stderr) so command substitution stays clean.

The rationale, unpacked:

1. **It prints a secret to stdout.** The whole point is to hand back the raw control-plane bearer so you can do things like:

```
1

curl -H "Authorization: Bearer $(entire auth token)" "$CORE/api/v1/clusters"
```

That's a power-user/scripting affordance. Surfacing it in `--help` and the noun-group listing would nudge ordinary users toward copy-pasting live credentials around, which isn't a workflow the CLI wants to advertise.

2. **It's an escape hatch, not a feature.** The everyday auth surface is `login` / `logout` / `status` / `contexts` / `use`. `token` exists purely for automation that needs to authenticate against the core API without re-deriving the keychain slot itself. Keeping it hidden keeps the visible surface focused on the interactive flows while leaving the scripting path fully functional.

3. **Its output is designed to be piped, not read.** Only the token goes to stdout; errors and the "not logged in" hint go to stderr — so `$(entire auth token)` stays clean in command substitution. That's another signal it's meant for scripts, not humans reading a terminal.

This matches how it's described in `CLAUDE.md` too — it's listed under `auth` as "the hidden `token` (prints the active control-plane bearer to stdout for scripting/curl; honors `ENTIRE_TOKEN`, else the refreshed active-context login JWT)."

Note that "hidden" here just means omitted from help/discovery — the command is fully functional if you know to type it. It's not deprecated (no deprecation hint), unlike the hidden _aliases_ which nudge you toward canonical forms.

---

## Entire Explain:

I traced `entire auth token` back to the session that introduced it (commit `2b58593b8`, checkpoint `c9e38d421945`). The code comment gives the _what_; the transcript gives the _why it exists at all_ — and it's more incidental than the comment suggests.

### Why it exists

It was **not** planned auth work. It was born mid-session as a convenience while building the `entire repo mirror create` onboarding wizard. That wizard needed a new `GET /api/v1/clusters` endpoint, and to inspect/test it the developer (paul) asked:

> "give me the curl command to list clusters too. might need to dump a jwt somehow."

The problem: **there was no way to get the bearer out.** The login JWT lives in the macOS keychain as `"<JWT>|<expiry>"`, keyed by the active context's `keychain_service` + `handle` from `contexts.json`. The only recipe was ugly:

```
1
2
3
4
5

CTX="${ENTIRE_CONFIG_DIR:-$HOME/.config/entire}/contexts.json"
CUR=$(jq -r .current_context "$CTX")
read -r CORE SVC HANDLE < <(jq -r --arg n "$CUR" '...' "$CTX")
JWT=$(security find-generic-password -s "$SVC" -a "$HANDLE" -w | sed 's/|[0-9]*$//')
curl -fsS "$CORE/api/v1/clusters" -H "Authorization: Bearer $JWT" | jq .
```

The agent then offered to "fold a hidden `entire auth token` (prints the active bearer to stdout) into this branch so curl-ing is a one-liner next time," the user said **yes**, and the whole multi-step recipe collapsed to:

```
1

curl -H "Authorization: Bearer $(entire auth token)" "$CORE/api/v1/clusters"
```

So the command's entire reason for existing is to replace that keychain-extraction dance with a one-liner for scripting/curl.

### Why hidden (the actual rationale)

Two reasons, both from the transcript, and they reinforce the code comment:

1. **It emits a live credential.** The final summary states it plainly: _"Hidden from help (emits a live credential)."_ Advertising a command whose whole job is to spit a valid bearer onto stdout would nudge ordinary users toward copy-pasting secrets around. It's a deliberate escape hatch, not everyday surface.

2. **It's a scripting affordance, not an interactive one.** Its output is designed to be _piped, not read_ — only the token goes to stdout; errors and the not-logged-in hint go to **stderr** specifically so `$(entire auth token)` stays clean in command substitution. That design only makes sense for automation, which is exactly the audience "hidden" targets.

### Non-obvious facts a reader would miss

- **It's not deprecated, just hidden.** Unlike the hidden _aliases_ (`resume` → `session resume`, etc.) which emit deprecation hints to steer you elsewhere, `token` is fully supported — it's hidden purely because surfacing a credential-printer is undesirable, not because it's on its way out.
- **It resolves the same bearer the API client uses** — `ENTIRE_TOKEN` verbatim when set, else the active context's login JWT, refreshed if near expiry. So it can never diverge from what an actual API call would send.
- **It intentionally never printed the developer's real JWT into the session.** The agent deliberately gave the keychain recipe but _didn't run_ `security ... -w`, to keep the live token out of the transcript — a nice illustration of the same "live credential" caution that made the command hidden.

### Sources

- Commit `2b58593b8` — "Add hidden `entire auth token` for scripting"
- Checkpoint `c9e38d421945` (session `b1f77cad…`) — the mirror-onboarding session; the `auth token` command was a fixup near the end (transcript lines ~944–1101), where the curl-token friction was raised, the hidden command was proposed and approved, and "emits a live credential" was given as the reason to hide it.