> ## Documentation Index
> Fetch the complete documentation index at: https://superwhisper.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI and MCP server

> Search your Superwhisper history and control the app from the terminal on macOS. Run the CLI as an MCP server to give AI assistants access.

The `superwhisper` CLI gives you terminal access to your local transcription history, [meetings](https://superwhisper.com/docs/meetings/overview.md), 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 and meetings.

![The superwhisper CLI showing its command list and the output of superwhisper stats](https://mintcdn.com/superwhisper/nuTetdsD4WaOh6uF/images/screens/mac/cli-stats.png?fit=max\&auto=format\&n=nuTetdsD4WaOh6uF\&q=85\&s=e6e02a70c383eb79be2d6c83e5d279b2)

> [!NOTE]
>
> 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

```bash theme={null}
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](https://github.com/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 |
| `meetings` | List recent meetings. `meetings search <query>` searches them, and `meetings read [ID]` prints a summary, notes, and attendees. Add `--transcript` for the full transcript |
| `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](https://superwhisper.com/docs/get-started/interface-vocabulary.md) terms |
| `snippets` | List, set, or remove [replacements](https://superwhisper.com/docs/get-started/interface-vocabulary.md#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](https://superwhisper.com/docs/get-started/transcribe-files.md) needs Pro |
| `completions` | Generate shell completions |
| `doctor` | Diagnostic info about the database, for bug reports |
| `mcp` | Run as an MCP server over stdio |

Examples:

```bash theme={null}
superwhisper search "quarterly report"
superwhisper history --since 2026-09-01 --mode Mail
superwhisper read --raw
superwhisper meetings read --transcript
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 meetings, and control over vocabulary and snippets:

```bash theme={null}
superwhisper mcp
```

The server speaks MCP over stdio and exposes tools for search, history, reading recordings, meetings, modes, stats, vocabulary, and snippets. The meeting tools are `meetings`, `search_meetings`, and `read_meeting`.

The easiest way to connect an AI app is from Superwhisper: open **Meeting settings → Agents** and turn on the app. See [Ask an agent about your meetings](https://superwhisper.com/docs/meetings/share.md#ask-an-agent-about-your-meetings).

To connect from the terminal, run `mcp install` with the app's name: `claude-code`, `codex` (also used by the ChatGPT desktop app), `claude-desktop`, or `cursor`. It also installs a meetings skill that tells the agent how to use the meeting tools.

```bash theme={null}
superwhisper mcp install claude-code
superwhisper mcp status       # Show which apps are connected
superwhisper mcp uninstall    # Remove Superwhisper from every app
```

To add it to another MCP client, use this configuration:

```json theme={null}
{
  "mcpServers": {
    "superwhisper": {
      "command": "superwhisper",
      "args": ["mcp"]
    }
  }
}
```

> [!TIP]
>
> If you connect Claude Code through the [coding agent integration](https://superwhisper.com/docs/get-started/coding-agents.md), the MCP server is set up for you.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.