@darkdepot/whispr-cli

The whispr command-line tool for the Whispr desktop app. It talks only to the local desktop bridge written by a running Whispr app and never sends notes, transcripts, audio metadata, or API keys to a remote service.

Install

npm install -g @darkdepot/whispr-cli

Requires Node.js 20 or later.

Quick Start

Start Whispr, then run:

whispr doctor
whispr notes list
whispr notes transcript <note-id>

The CLI reads ~/.whispr/cli-bridge.json, which the desktop app writes with mode 0600. The file contains {version, port, token} for a local 127.0.0.1 HTTP bridge.

Backend

Only the local backend is supported in this package. This is intentional: Whispr's public CLI should be safe-by-default and should not accidentally send private notes or meeting transcripts to any cloud API.

Path selection follows the desktop app's storage logic:

1. WHISPR_BRIDGE_FILE=/path/to/cli-bridge.json
2. WHISPR_HOME=/path/to/whispr-home
3. WHISPR_CHANNEL=development|staging|production
4. VITE_WHISPR_CHANNEL=development|staging|production
5. NODE_ENV=development
6. production default: ~/.whispr/cli-bridge.json

Non-production channels use:

• development: ~/.whispr-dev/cli-bridge.json
• staging: ~/.whispr-stage/cli-bridge.json

Output Policy

List commands use tables in a terminal and JSON when piped. Pass --format json for backwards-compatible raw JSON, or --format json-v1 for the stable agent envelope:

{ "ok": true, "data": [], "meta": { "schema": "whispr.cli.v1" } }

Single-resource commands default to human output in a terminal and JSON when piped.

Errors are written to stderr and use stable exit codes:

| Code | Meaning | | ---- | ----------------------------------------------- | | 0 | Success | | 1 | User error, bad flags, malformed response | | 2 | Desktop bridge missing or unreachable | | 3 | Local bridge bearer token rejected | | 4 | Note, transcription, folder, or audio not found | | 5 | Refused dangerous write or unsafe overwrite |

Commands

whispr doctor [--verbose] [--format json|json-v1]
whispr version [--format json|json-v1]
whispr config get [--format json|json-v1]

whispr search <query> [--type notes] [--limit N] [--format json|json-v1|table]

whispr notes list [--folder <id>] [--limit N] [--format json|json-v1|table]
whispr notes get <id> [--format json|json-v1|markdown|transcript|transcript-json]
whispr notes transcript <id> [--format text|markdown|srt|vtt|json|json-v1] [--plain] [--timestamps]
whispr notes export [id] --out <dir> [--folder <id>] [--limit N]
                    [--format markdown|json|transcript|transcript-json]
                    [--include-transcript] [--overwrite] [--dry-run]
whispr notes create --content <text> | --content-file <path> [--title <t>] [--folder <id>] [--format json|json-v1]
whispr notes update <id> [--content <t>] [--folder <id>] [--title <t>] [--format json|json-v1]
whispr notes delete <id> [--dry-run] [--yes] [--format json|json-v1]
whispr notes search <query> [--limit N] [--format json|json-v1|table]

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

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

whispr audio delete <transcription-id> [--dry-run] [--yes] [--format json|json-v1]

Examples

whispr doctor --format json
whispr search "onboarding" --format json-v1
whispr notes list --limit 10 --format json-v1
whispr notes transcript 42 --format vtt
whispr notes export --out ./whispr-export --format markdown --include-transcript
whispr notes get 42 --format transcript-json

Development

cd packages/whispr-cli
npm install
npm run lint
npm test
npm run pack:check

npm run pack:check builds the package, runs the safety scan, and shows the exact files that would be published to npm.

Publishing

The package is published from the manual GitHub Actions workflow Publish CLI to npm.

Configure npm trusted publishing for @darkdepot/whispr-cli before using the workflow:

• provider: GitHub Actions
• organization/user: darkdepot
• repository: whispr
• workflow filename: publish-cli.yml
• allowed action: npm publish

The workflow uses GitHub OIDC instead of a long-lived npm token. It installs from package-lock.json, runs the package checks, refuses to republish an existing version, and publishes to npm.

For an emergency local publish from a trusted maintainer machine:

cd packages/whispr-cli
npm ci
npm run prepublishOnly
npm publish --access public --auth-type=web