Command reference

The CLI uses noun-verb syntax (notes list, not list-notes) — same convention as gh, kubectl, aws, stripe.

Global flags

Flag	Effect
`--local`	Force the local desktop bridge backend
`--remote`	Force the remote cloud API backend
`--format <fmt>`	Output format, per command. Supported values vary (`json`, `table`, `markdown`, `text`). Default depends on TTY: human-readable in a terminal, JSON when piped. Not all commands accept this flag — `notes create`, `notes update`, and `folders create` always emit full JSON.
`-h, --help`	Show command help
`-V, --version`	Print CLI version

Notes

openwhispr notes list [--folder <id>] [--limit N] [--format json|table]
openwhispr notes get <id> [--transcript] [--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|table]
openwhispr notes search <query> [--limit N] [--format json|table]

For notes with an AI-enhanced version (e.g. meeting notes), notes get’s markdown output shows the enhanced note when one exists, matching the desktop app. The raw fields are always available via --format json (content, enhanced_content). Pass --transcript to output only the note’s transcript — as speaker-labeled markdown, or as { "transcript": "..." } with --format json.

Folders

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

Transcriptions

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

--format text returns the plain transcript body. SRT and VTT subtitle formats aren’t currently exposed by the CLI — use --format json and post-process the segment data if you need timestamped subtitles.

Audio

openwhispr audio delete <transcription-id> [--format json|table]

Local-only. Deletes the audio file for a dictation transcription (meeting transcripts have no audio to delete — only their text is captured). The cloud API doesn’t store audio at all, so running with --remote exits with a “not supported” error.

Transcribe

openwhispr transcribe <file> [--model <id>] [--language <code>] [--prompt <text>]
                             [--format text|json] [--note] [--title <title>] [--folder <name>]

Transcribes an audio file and prints the transcript. Requires @openwhispr/cli 0.3.0 or later. Backend selection is the usual auto/--local/--remote, and the two backends behave quite differently here:

Local (desktop app running) — transcribes on your machine with whatever local model the app is set to use. Free, no file-size cap, and the audio never leaves the machine. --model <id> overrides the app’s choice; the model has to be downloaded in the app already, and if you get the name wrong the CLI lists the ones available.
Remote (--remote, or no desktop app) — sends the file to OpenWhispr Cloud. Needs a Pro or Business plan and a key with the transcriptions:write scope. Files over 4 MB are split into 4-minute chunks client-side before upload, which requires ffmpeg on your PATH.

Cloud transcription through the API is in beta. Limits, response shape, and availability may change, and there is no SLA. For long recordings or free, private transcription, use the OpenWhispr CLI with the desktop app running. See Transcribe audio (beta) for the limits.

Flag	Effect
`--model <id>`	Local only. Use a specific downloaded model instead of the app’s current one.
`--language <code>`	Language of the audio, e.g. `en`.
`--prompt <text>`	Remote only. Names and jargon to spell correctly, passed to the cloud model as a hint. Locally, the app’s dictionary does this job.
`--format text\|json`	`text` (default in a terminal) prints the transcript; `json` includes language, duration, provider and model. Neither backend returns timestamps yet, so there is no subtitle output.
`--note`	Also save the transcript as a note.
`--title <title>`	Title for the saved note. Only meaningful with `--note`.
`--folder <name>`	Folder for the saved note, by name. Only meaningful with `--note`.

# Local, with the app's current model
openwhispr transcribe memo.m4a

# JSON for scripting
openwhispr transcribe interview.wav --format json > interview.json

# Save straight into a note
openwhispr transcribe standup.mp3 --note --title "Standup 10 Sep" --folder Work

# Force the cloud beta and help it with names
openwhispr --remote transcribe memo.m4a --prompt "OpenWhispr, Siobhán, ARR"

Dictionary

openwhispr dictionary list [--format json|table]
openwhispr dictionary add <word...>
openwhispr dictionary remove <word...>

Manages the custom dictionary — the names, jargon and acronyms passed to the transcription model as a hint. add and remove take one or more words; quote anything with a space. Removal is by word, not id.

openwhispr dictionary add Siobhán "SOC 2" Kubernetes
openwhispr dictionary remove Kubernetes
openwhispr dictionary list --format json

Against the cloud API these need the dictionary:read and dictionary:write scopes — see Dictionary and snippets.

Snippets

openwhispr snippets list [--format json|table]
openwhispr snippets add <trigger> <replacement>
openwhispr snippets remove <trigger...>

Manages snippets — a trigger phrase and the text it becomes when you say it. add takes exactly one trigger and one replacement; remove takes one or more triggers.

openwhispr snippets add "cal link" "https://cal.com/you/30min"
openwhispr snippets add "sign off" "Best, Alex · alex@example.com"
openwhispr snippets remove "sign off"

Against the cloud API these need the snippets:read and snippets:write scopes.

Auth

openwhispr auth login    # prompts for API key, stores in ~/.openwhispr/cli-config.json
openwhispr auth logout
openwhispr auth status

Config

openwhispr config get
openwhispr config set backend auto|local|remote
openwhispr config set api-base https://api.openwhispr.com

Doctor

openwhispr doctor [--format json|table]

Reports which backends are reachable and exits non-zero if neither is.

Exit codes

Code	Meaning
0	Success
1	User error (bad arguments, missing required flag)
2	Backend unreachable (app not running, API unreachable)
3	Authentication failure (missing/invalid key, insufficient scope)
4	Not found (no such note/transcription/folder)

Overview

CLI

Integrations

Open source

Global flags

Notes

Folders

Transcriptions

Audio

Transcribe

Dictionary

Snippets

Auth

Config

Doctor

Exit codes

​Global flags

​Notes

​Folders

​Transcriptions

​Audio

​Transcribe

​Dictionary

​Snippets

​Auth

​Config

​Doctor

​Exit codes

Global flags

Notes

Folders

Transcriptions

Audio

Transcribe

Dictionary

Snippets

Auth

Config

Doctor

Exit codes