CLI and MCP server

The superwhisper CLI gives you terminal access to your local transcription history, vocabulary, and snippets. It can also run as an MCP (Model Context Protocol) server, so AI assistants like Claude Code can search and read your dictations.

The superwhisper CLI showing its command list and the output of superwhisper stats

The CLI is available on macOS only. It reads the same local database as the app, and its commands run entirely on your device. If you connect an AI assistant over MCP, the transcripts it queries are sent to that assistant and handled under its own model and data settings.

Install

curl -fsSL https://superwhisper.com/install-cli.sh | bash

The script installs the latest release to /usr/local/bin, or to ~/.local/bin if that isn’t writable. If your shell can’t find superwhisper after install, add ~/.local/bin to your PATH. Binaries and checksums are published at superultrainc/superwhisper-cli-release.

Commands

Command	What it does
`search <query>`	Full-text search across all transcriptions. Supports FTS5 syntax: `AND`, `OR`, `NOT`, `"phrase"`, `prefix*`
`history`	List recent transcriptions. Filter with `--mode`, `--since`, `--before`
`read [ID]`	Read one transcription (the latest if no ID). `--raw` shows the transcription before AI processing
`stats`	Transcription statistics
`modes`	List modes used in your recordings, with counts
`export`	Export everything, oldest first, as `jsonl` or `markdown`
`vocab`	List, add, or remove vocabulary terms
`snippets`	List, set, or remove replacements: the same From → To pairs as Settings → Vocabulary in the app
`record`	Toggle recording in the running app
`start`	Start recording. Does nothing if already recording
`stop`	Stop recording. Does nothing if not recording
`switch [mode]`	Switch the active mode by name or key. Without an argument, lists your modes
`settings`	Open the settings window
`transcribe <file>`	Send an audio file to the app to transcribe. File transcription needs Pro
`completions`	Generate shell completions
`doctor`	Diagnostic info about the database, for bug reports
`mcp`	Run as an MCP server over stdio

Examples:

superwhisper search "quarterly report"
superwhisper history --since 2026-09-01 --mode Mail
superwhisper read --raw
superwhisper export -f markdown > dictations.md
superwhisper vocab add "Superwhisper"
superwhisper snippets set "my work email" "you@yourcompany.com"
superwhisper switch Message
superwhisper transcribe ~/Downloads/note.m4a

The app-control commands (record, start, stop, switch, settings, and transcribe) send a request to the running app, so Superwhisper must be open for them to work. Most commands accept --json for machine-readable output. Point the CLI at a non-default install with --db <path> (or SUPERWHISPER_DB) and --settings <path> (or SUPERWHISPER_SETTINGS).

MCP server

Run the CLI as an MCP server to give AI assistants read access to your history and control over vocabulary and snippets:

superwhisper mcp

The server speaks MCP over stdio and exposes tools for search, history, reading recordings, modes, stats, vocabulary, and snippets. To add it to Claude Code manually:

claude mcp add superwhisper -- superwhisper mcp

If you connect Claude Code through the coding agent integration, the MCP server is set up for you.

Get Started

Modes

Features

Models

Account & Billing

Security & Privacy

Troubleshooting

Enterprise

Install

Commands

MCP server

​Install

​Commands

​MCP server

Install

Commands

MCP server