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

# Login and pairing

> Pair your machine to your Veil account via the browser. Credentials are stored in the OS keychain.

The CLI uses browser-based device pairing. You run `veil login`, confirm in the browser, and the CLI writes credentials to the OS keychain. You stay paired until you run `veil logout` or revoke the device from the dashboard.

## Pair your machine

<Steps>
  <Step title="Run veil login">
    ```bash theme={null}
    veil login
    ```

    To set a custom label for this device:

    ```bash theme={null}
    veil login --device-name "my-ci-runner"
    ```

    If you omit `--device-name`, the CLI generates one from your hostname (for example, `macbook-pro-a3f2`).
  </Step>

  <Step title="Confirm in the browser">
    The CLI prints a pairing code and opens a verification URL in your browser. If the browser doesn't open automatically (headless or SSH environments), copy the URL from the terminal.

    Sign in to Veil and approve the pairing request. The page shows the device name and which modes will be available.
  </Step>

  <Step title="Pairing confirmed">
    Once you approve, the CLI prints a summary:

    ```
    Paired as you@example.com on device "macbook-pro-a3f2".
    Sandbox mode: ready
    Live mode:    locked — complete production KYC to unlock
    ```

    Sandbox credentials are issued immediately. Live credentials are issued only after you have completed production KYC.
  </Step>
</Steps>

## Credential storage

Credentials are stored in the OS keychain using `@napi-rs/keyring`, under the service name `veil-cli`. A single keychain entry holds both sandbox and live keys (where available), along with the active mode, device name, and account email.

<Note>
  On Linux, the keychain backend requires `libsecret` (e.g. GNOME Keyring). If the keychain is unavailable or locked when `veil login` runs, the CLI exits with a hint pointing at libsecret. `veil login` opens a browser to complete pairing, so it isn't designed for headless CI use.
</Note>

## Check your session

```bash theme={null}
veil whoami
```

Prints the account email, active mode, and device name for the current pairing.

## Log out

```bash theme={null}
veil logout
```

Clears the keychain entry on this machine. The device's API key is revoked server-side the next time you log in from the same device.

## Manage devices from the dashboard

Paired devices appear in the dashboard under Settings → Paired Devices. From there you can see all active device pairings and revoke individual ones.

If a mode's key is revoked or expired, the CLI prompts you to run `veil mode <other>` to continue in the unaffected mode, or `veil login` to restore the revoked one.