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

# CLI authentication

> How the CLI authenticates to the local desktop app and the cloud API.

The CLI uses different credentials for each backend. Local needs nothing from you; remote needs an API key.

## Local backend (desktop bridge)

When the OpenWhispr desktop app is running, it exposes a loopback HTTP bridge on `127.0.0.1`. The app writes a one-time bearer token to `~/.openwhispr/cli-bridge.json` (mode `0600`) at startup; the CLI reads it automatically.

You don't need to run `auth login` for local mode. If the desktop app is closed or hasn't started the bridge yet, the CLI treats local as unavailable.

## Remote backend (cloud API)

Generate a key and store it locally:

<Steps>
  <Step title="Create an API key">
    Open the desktop app, go to **Integrations > API Keys**, and create a key with the scopes you need (`notes:read`, `notes:write`, `transcriptions:delete`, etc.).

    Keys look like `owk_live_abc123...` and are shown once.
  </Step>

  <Step title="Store the key">
    ```bash theme={null}
    openwhispr auth login
    ```

    The CLI prompts for the key and saves it to `~/.openwhispr/cli-config.json` with `0600` permissions.
  </Step>

  <Step title="Confirm it works">
    ```bash theme={null}
    openwhispr auth status
    ```

    Reports whether a key is configured and whether the cloud API accepts it.
  </Step>
</Steps>

## Logout

```bash theme={null}
openwhispr auth logout
```

Clears the key from `~/.openwhispr/cli-config.json`. The desktop bridge token is not affected.

## Scopes

API-key scopes are enforced server-side. If a command fails with exit code `3` and a "scope" error, the key is missing the required scope — regenerate it from the desktop app with the right boxes ticked.

| Scope                   | Commands that need it                          |
| ----------------------- | ---------------------------------------------- |
| `notes:read`            | `notes list/get/search`, `folders list`        |
| `notes:write`           | `notes create/update/delete`, `folders create` |
| `transcriptions:read`   | `transcriptions list/get`                      |
| `transcriptions:delete` | `transcriptions delete`                        |