Openwhispr CliSAFE

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: openwhispr-cli
description: Use this skill whenever the user wants to operate on OpenWhispr notes, folders, transcriptions, or audio from a terminal or shell. The OpenWhispr CLI (`openwhispr` binary, npm package `@openwhispr/cli`) talks to either the local desktop app or the cloud API and exposes every operation needed for managing notes, folders, transcriptions, audio, plus auth and config. Trigger this skill when the user mentions "openwhispr cli", running shell commands against OpenWhispr, automating note workflows, cleaning up a transcription, building agent integrations against OpenWhispr, or scripting any OpenWhispr operation — even if they don't say "CLI" explicitly.
---

# 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`, 

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.