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

# Local vs cloud backends

> How the CLI decides whether to talk to the desktop app or the cloud API.

Every CLI command works against one of two backends:

* **Local** — the desktop app's loopback bridge. Fast, offline-capable, mutates SQLite directly via the same code paths the UI uses (audio cleanup, sync hooks, search index, broadcast all run).
* **Remote** — the cloud REST API at `api.openwhispr.com`. Works when the desktop app is closed or you're on a different machine.

## Auto-detection (default)

In auto mode, the CLI picks a backend in this order:

1. The `--local` or `--remote` flag (if passed)
2. The `OPENWHISPR_BACKEND` environment variable (`local`, `remote`, or `auto`)
3. The `backend` key in `~/.openwhispr/cli-config.json`
4. **Auto:** local if the desktop bridge is reachable, otherwise remote if an API key is configured, otherwise an error with guidance

## Force a backend

```bash theme={null}
openwhispr --local notes list
openwhispr --remote notes list
OPENWHISPR_BACKEND=remote openwhispr notes list
```

Or persist the choice:

```bash theme={null}
openwhispr config set backend local
```

## When to prefer each

| Situation                                         | Backend                 |
| ------------------------------------------------- | ----------------------- |
| Desktop app open, recent recording                | Local — most up-to-date |
| Desktop closed or different machine               | Remote                  |
| You want immediate UI feedback (broadcast events) | Local                   |
| You don't trust the local SQLite to be in sync    | Remote                  |
| Offline                                           | Local only              |

## Capability matrix

| Command                                      | Local |             Remote            |
| -------------------------------------------- | :---: | :---------------------------: |
| `notes list/get/create/update/delete/search` |   ✓   |               ✓               |
| `folders list/create`                        |   ✓   |               ✓               |
| `transcriptions list/get/delete`             |   ✓   |               ✓               |
| `audio delete`                               |   ✓   | ✗ (cloud doesn't store audio) |

## Mixing local and remote during a meeting

If the desktop app is recording or has just finished a meeting, prefer `--local`. The local SQLite is authoritative until sync reconciles. Running destructive commands against remote during this window can drift the two copies until the next sync pulls them back together.