entire login uses the device-code flow instead. It prints an approval URL and a code that you enter in a browser on any machine. Use --device to choose this flow explicitly.
A completed login is saved as a context: a named pairing of login server and identity, with its tokens in your operating system’s credential store. Logging in again as the same identity updates that context in place. Run
entire auth contexts to see them all.Machines with No OS Keyring
Tokens are stored in your operating system’s credential store: macOS Keychain, Linux Secret Service, or Windows Credential Manager. This also applies to device-code logins on headless machines, so no other setup is needed when a keyring is available. If the machine has no usable keyring,entire login fails with a save login error, often failed to unlock correct collection on Linux. In that case, use the file-backed token store:
0600 permissions to tokens.json in your Entire config directory (~/.config/entire, or $ENTIRE_CONFIG_DIR when set). Override the location with ENTIRE_TOKEN_STORE_PATH. Later commands must read from the same store, so either set ENTIRE_TOKEN_STORE=file in every environment that runs Entire, or select the file store once in config.json in your Entire config directory:
~/.config/entire/config.json
token_store accepts "file" or "keyring". When ENTIRE_TOKEN_STORE is set, even to an empty value, it takes precedence over config.json. If config.json can’t be read or parsed, or token_store has any other value, Entire reports an error naming the file when it reads or saves a login, even when ENTIRE_TOKEN_STORE is set. Fix or remove the file. Entire doesn’t fall back to the keyring.
Entire never switches to file storage automatically. Use the keyring when available, since the file stores your tokens in plain text.
CI and Automation
Where nobody is at a browser, such as a CI runner, a remote VM, or a cloud coding agent’s sandbox, pick the setup that matches whether the machine keeps its files between runs.Machines That Keep Their Files
On a self-hosted runner, a long-lived VM, or a container with a persistent home directory, log in once with the device-code flow:ENTIRE_TOKEN_STORE=file or set token_store in config.json. The login is then stored on disk, so keep the config directory on persistent storage, or set ENTIRE_TOKEN_STORE_PATH to a file on persistent storage.
Don’t copy a stored login to another machine. Each refresh replaces the stored refresh token and invalidates the old one, so two copies refreshing the same login can sign both out.
Jobs That Run as Root
Cron jobs, systemd units, andsudo commands often run as root with a minimal environment. To let them use Entire without passing environment variables, select the file store in root’s config.json and log in once as root:
HOME. This is for security. sudo -E keeps your environment, including your HOME. If Entire followed it, root would read its login and settings from a directory a non-root user owns, and write root-owned files there. Only root can change the user database, so no one else can redirect root’s config. A process with no HOME set also uses the user database. The same home holds root’s Entire cache and managed plugins. ENTIRE_CONFIG_DIR still overrides the config directory.
The example uses /root, the usual Linux home for root. On macOS, it is /var/root.
Fresh Environments on Every Run
When each run starts from a clean environment, pass a token throughENTIRE_TOKEN instead of logging in:
ENTIRE_TOKEN bypasses stored credentials. The CLI uses the token as-is, derives the control-plane endpoint from it, and never writes it to disk. It is never refreshed, so it must still be valid when the command runs:
A login token acts as you and expires after 8 hours, so it suits short-lived jobs, not a standing setup. Long-lived API keys for cloud agents and other automation aren’t available yet.
Reading Entire data, such as Trails, findings, or API responses, only needs the CLI installed and authenticated. Running
entire enable and installing agent hooks are only needed to capture an agent’s sessions.