docs(readme): document headless & CI authentication

13e379e→main· peyton-alt·3d ago·1 file·+39 added/-0 removed

ENTIRE_TOKEN_STORE=file, ENTIRE_TOKEN_STORE_PATH, and ENTIRE_TOKEN existed only as an internal package comment. Add a user-facing section covering the two supported paths (file-backed interactive login on keyring-less machines, env-token injection for CI/workload identity) and a troubleshooting callout quoting the error strings entire login actually emits.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

Sessions

01KXGTTNGCEACC83QZEJ5YAF0DView transcript

Changes

1

• MREADME.md+39

24 unmodified lines

...

## Headless & CI Authentication

By default `entire login` stores tokens in the OS keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager). Machines without a usable keyring — headless servers, containers, minimal VMs, CI runners — have two supported paths:

### Interactive login on a headless machine

Use the file-backed token store. The device-auth flow already works without a local browser (the CLI prints an approval URL you can open on any machine); only token storage needs the override:

```bash
ENTIRE_TOKEN_STORE=file entire login
```

Tokens are written with `0600` permissions to `tokens.json` in your Entire config directory (`~/.config/entire` by default). Override the location with `ENTIRE_TOKEN_STORE_PATH`. Set `ENTIRE_TOKEN_STORE=file` persistently (e.g. in your shell profile) so later commands read from the same store.

### Non-interactive automation (CI, workload identity)

Skip login and storage entirely by injecting a token per invocation:

```bash
ENTIRE_TOKEN=<login-or-sa-session-JWT> entire ...
```

`ENTIRE_TOKEN` bypasses stored credentials; the CLI derives the control-plane endpoint from the token itself. Nothing is written to disk. This is the right path for CI pipelines and service accounts.

> **Seeing `save login` / `failed to unlock correct collection` errors from `entire login`?** That's the OS keyring being unavailable — use one of the two paths above.

## Local Device Auth Testing

If you're working on the CLI device auth flow against a local `entire.io` checkout: