Local vs cloud backends

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:

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

Force a backend

openwhispr --local notes list
openwhispr --remote notes list
OPENWHISPR_BACKEND=remote openwhispr notes list

Or persist the choice:

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.

​Auto-detection (default)

​Force a backend

​When to prefer each

​Capability matrix

​Mixing local and remote during a meeting

Auto-detection (default)

Force a backend

When to prefer each

Capability matrix

Mixing local and remote during a meeting