Unhide entire auth token CLI Command · Entire

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.

  1. 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.

  2. 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

Sources