openwhispr-cli

# OpenWhispr CLI

Use this reference when running the `openwhispr` command-line tool. The CLI is a single binary that operates against either the local desktop app (via a loopback HTTP bridge) or the cloud REST API. The same command works against both backends.

## Install

```bash
npm install -g @openwhispr/cli
```

Requires Node.js 20 or later. Verify with `openwhispr --version`. If the user reports `command not found`, ensure their npm global bin is on `$PATH`.

## Backends

Every command runs against one of two backends. The behavior is identical from the user's perspective — only the data source differs.

| Backend | What it talks to | Use when |
|---------|------------------|----------|
| **local** | Desktop app's loopback HTTP bridge on `127.0.0.1` | The desktop app is running. Authoritative during/right after a recording. |
| **remote** | `https://api.openwhispr.com/api/v1` | Desktop is closed, or running on a different machine, or the user wants cloud-side semantics. |

### How the CLI picks a backend

Resolution order (first match wins):

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

### Local backend (no setup needed)

When the desktop app starts, it writes `{version, port, token}` to `~/.openwhispr/cli-bridge.json` with mode `0600`. The CLI reads it automatically. If the file is missing or stale, local is treated as unavailable.

### Remote backend (needs an API key)

Generate a key in the desktop app under **Integrations > API Keys**, then run:

```bash
openwhispr auth login    # prompts for the key, stores it 0600 in ~/.openwhispr/cli-config.json
openwhispr auth status   # confirm it works
openwhispr auth logout   # clear it
```

API keys are scoped server-side. Match scopes to the commands the user needs to run:

| Scope | Commands |
|-------|----------|
| `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` |
| `usage:read` | (used internally by `doctor` and the remote backend's reachability ping) |

Scopes are enforced server-side; the CLI does not validate them locally. If a scope is missing, the API returns a 401/403 and the CLI exits with code 3.

## Output

The CLI auto-detects whether stdout is a TTY:

- TTY → human-readable (table for lists, markdown or text for single resources)
- Pipe/redirect → JSON

Override with `--format <fmt>`. Supported values vary by command:

- Lists (`notes list`, `notes search`, `folders list`, `transcriptions list`): `json|table`
- `notes get`: `json|markdown`
- `transcriptions get`: `json|text`
- `notes create`, `notes update`, `folders create`: no `--format` flag — always emit the full JSON of the created/updated resource on stdout
- Delete-style mutations (`notes delete`, `transcriptions delete`, `audio delete`) and status commands (`auth status`, `config get`, `doctor`, `version`): `--format json` for machine output; otherwise human-readable text

Always pass `--format json` when parsing CLI output programmatically.

## Exit codes

Honor these exit codes when scripting or recovering from errors:

| Code | Meaning | Recovery |
|------|---------|----------|
| 0 | Success | Continue |
| 1 | User error (bad args, missing required flag) | Fix the command and rerun |
| 2 | Backend unreachable | Start the desktop app, or run `auth login` for cloud, or try `--remote`/`--local` explicitly |
| 3 | Auth failure (missing/invalid key, insufficient scope) | Do not retry — surface to the user |
| 4 | Not found (no such note/transcription/folder) | Check the ID and rerun |

## Commands

Noun-verb syntax: `openwhispr <noun> <verb>`. Same convention as `gh`, `kubectl`, `aws`, `stripe`.

### Notes

```bash
openwhispr notes list [--folder <id>] [--limit N] [--format json|table]
openwhispr notes get <id> [--format json|markdown]
openwhispr notes create --content <text> | --content-file <path>
                        [--title <t>] [--folder <id>]
openwhispr notes update <id> [--content <t>] [--folder <id>] [--title <t>]
openwhispr notes delete <id> [--dry-run] [--format json]
openwhispr notes search <query> [--limit N] [--format json|table]
```

### Folders

```bash
openwhispr folders list [--format json|table]
openwhispr folders create --name <name> [--sort-order <n>]
```

Folder names must be unique per user. Create returns 409-equivalent on duplicates (exit code 1 with a clear message).

### Transcriptions

```bash
openwhispr transcriptions list [--limit N] [--format json|table]
openwhispr transcriptions get <id> [--format json|text]
openwhispr transcriptions delete <id> [--dry-run] [--format json]
```

`--format text` returns the plain transcript text body. SRT/VTT export is not currently exposed by the CLI; use `--format json` and post-process if you need timestamped subtitle formats.

### Audio

```bash
openwhispr audio delete <transcription-id> [--format json]
```

Local-only. The cloud API does not store audio. Running this with `--remote` returns a clear "not supported" error (exit 1).

### Auth

```bash
openwhispr auth login [--api-key <key>]   # prompts on stdin if --api-key omitted
openwhispr auth status [--format json]
openwhispr auth logout
```

`auth status` reads the stored config and reports whether a key is configured — it does **not** make a network call. To verify the key actually works, use `openwhispr doctor`.

### Config

```bash
openwhispr config get [--format json]
openwhispr config set backend auto|local|remote
openwhispr config set api-base https://api.openwhispr.com
```

Only `backend` and `api-base` are settable via `config set`. The API key is managed through `auth login`/`auth