> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# login

> Log in to Entire.

Log in to Entire.

```bash theme={null}
entire login [flags]
```

By default this opens a browser redirect flow. If Entire is running interactively, it prompts before opening the approval URL automatically.

With no interactive terminal, over SSH, or on a Linux or BSD machine with no graphical display, `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.

| Flag | Description |
| - | - |
| `--device` | Use the device-code flow, entering a code in your browser, instead of the default browser redirect. |
| `--server URL` | Login server to authenticate against. Rarely needed; the default serves all standard accounts. Defaults to `https://auth.entire.io`. |

```bash theme={null}
# Device-code flow, for a remote host or container
entire login --device
```

> [!NOTE]
>
> A completed login is saved as a [context](https://docs.entire.com/cli-reference/auth.md#login-contexts): 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`](https://docs.entire.com/cli-reference/auth#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:

```bash theme={null}
ENTIRE_TOKEN_STORE=file entire login
```

Tokens are written with `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:

```json ~/.config/entire/config.json theme={null}
{"token_store": "file"}
```

`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, sign in as a service account or store your own login.

### Sign In as a Service Account

On a platform that issues OIDC tokens to its jobs, such as GitHub Actions or Google Cloud, the job signs in with no stored credential. See the [OpenID Connect (OIDC) guide](https://docs.entire.com/guides/configuration/oidc.md).

On any other platform, create a [service account secret](https://docs.entire.com/guides/configuration/service-accounts.md#sign-in-with-a-secret) and set it as `ENTIRE_TOKEN`:

```bash theme={null}
ENTIRE_TOKEN=<secret> entire ...
```

The CLI exchanges the secret for a service account token and renews that token as needed.

### 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:

```bash theme={null}
entire login --device
```

Approve the printed code from any browser. The stored login refreshes itself, so later runs need no further setup. If the machine has no usable keyring, add `ENTIRE_TOKEN_STORE=file` or [set `token_store` in `config.json`](#machines-with-no-os-keyring). 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, and `sudo` 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:

```bash theme={null}
sudo mkdir -p /root/.config/entire
echo '{"token_store": "file"}' | sudo tee /root/.config/entire/config.json
sudo entire login --device
```

Except on Windows, Entire reads root's home directory from the system user database, not from `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 login token through `ENTIRE_TOKEN` instead of logging in. Get the token by running [`entire auth token`](https://docs.entire.com/cli-reference/auth#auth-token) on a machine where you're logged in, store it as a secret in the environment, and run:

```bash theme={null}
ENTIRE_TOKEN=<login token> entire ...
```

`ENTIRE_TOKEN` bypasses stored credentials, and the CLI never writes it to disk. A login token acts as you and expires after 8 hours. Use it for a one-off job. For a job that runs on every push or on a schedule, [sign in as a service account](#sign-in-as-a-service-account).

> [!NOTE]
>
> 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.
