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

# CLI command reference

> Every vowen command, flag, and example.

Every command below talks to the running Vowen app. Read [the overview](/cli/overview) first if you have not, especially the [global flags](/cli/overview#global-flags) (`--json`, `--no-launch`, `--timeout`) and the [exit codes](/cli/overview#exit-codes).

## All commands

| Command                         | What it does                                                      |
| ------------------------------- | ----------------------------------------------------------------- |
| [`history`](#history)           | List recent dictations, transcriptions, or notes                  |
| [`search`](#search)             | Full-text search across everything                                |
| [`read`](#read)                 | Print one item's full text                                        |
| [`delete`](#delete)             | Delete a dictation, transcription, or note                        |
| [`stats`](#stats)               | Lifetime and 30-day statistics                                    |
| [`export`](#export)             | Bulk export as JSONL or Markdown                                  |
| [`watch`](#watch)               | Stream new items as NDJSON                                        |
| [`notes`](#meeting-notes)       | List, read, create, import, regenerate, and control meeting notes |
| [`transcribe`](#transcribe)     | Transcribe audio or video files and wait for the result           |
| [`import`](#import)             | Queue files for transcription without waiting                     |
| [`models`](#models)             | List usable transcription models                                  |
| [`tags`](#tags)                 | Manage the two tag pools                                          |
| [`tag`](#tag)                   | Add or remove tags on one item                                    |
| [`vocab`](#vocab)               | Manage your dictionary                                            |
| [`replacements`](#replacements) | Manage text replacements applied to transcripts                   |
| [`expansions`](#expansions)     | Manage live typing expansions                                     |
| [`settings`](#settings)         | Read settings, write whitelisted ones                             |
| [`record`](#record)             | Start, stop, toggle, or cancel dictation                          |
| [`status`](#status)             | App connection, version, model, recording state                   |
| [`app`](#app)                   | Launch the app or print its version                               |
| [`doctor`](#doctor)             | Diagnostics                                                       |
| [`update`](#update)             | Self-update the CLI                                               |
| [`completion`](#completion)     | Generate a shell completion script                                |
| [`mcp`](#mcp)                   | Run as an MCP server over stdio                                   |

<Tip>Give any item id as a prefix. `vowen read 1734` resolves as long as exactly one item starts with those digits; an ambiguous prefix is rejected rather than guessed, and an exact match always wins over a prefix match.</Tip>

## Your data

<AccordionGroup>
  <Accordion title="history: list recent items">
    ```
    vowen history [flags]
    ```

    Newest first. Defaults to dictations only.

    | Flag             | Default     | Description                                     |
    | ---------------- | ----------- | ----------------------------------------------- |
    | `--limit`, `-l`  | `10`        | Maximum results                                 |
    | `--offset`, `-o` | `0`         | Results to skip                                 |
    | `--type`, `-t`   | `dictation` | `dictation`, `transcription`, `note`, or `all`  |
    | `--since`        |             | Only items on or after this date (`YYYY-MM-DD`) |
    | `--before`       |             | Only items before this date (`YYYY-MM-DD`)      |

    ```bash theme={null}
    vowen history
    vowen history --type all --limit 50
    vowen history --since 2026-08-01 --before 2026-08-15 --json
    ```

    The table shows id, date, type, and a truncated preview, with `[processing]` or `[error]` appended where relevant. When more results exist than were printed, a footer tells you how many.
  </Accordion>

  <Accordion title="search: full-text search">
    ```
    vowen search <query> [flags]
    ```

    Searches dictation text, titles, summaries, pre-enhancement originals, context notes, and filenames. Every term you give must appear somewhere in the item; matching is case-insensitive substring matching, not fuzzy.

    | Flag            | Default     | Description                                    |
    | --------------- | ----------- | ---------------------------------------------- |
    | `--limit`, `-l` | `20`        | Maximum results                                |
    | `--type`, `-t`  | `all`       | `dictation`, `transcription`, `note`, or `all` |
    | `--tag`         |             | Filter by tag id                               |
    | `--since`       |             | Only items on or after this date               |
    | `--before`      |             | Only items before this date                    |
    | `--sort`        | `relevance` | `relevance` or `date`                          |

    ```bash theme={null}
    vowen search "standup notes"
    vowen search postgres migration --type note --sort date
    vowen search invoice --limit 5 --json | jq -r '.results[].id'
    ```

    Output is a compact table with a snippet around the first match. Use [`read`](#read) to get the full text of a result.
  </Accordion>

  <Accordion title="read: print one item's text">
    ```
    vowen read [id] [--raw]
    ```

    With an id, prints that item. Without one, prints your most recent dictation.

    | Flag    | Description                                                   |
    | ------- | ------------------------------------------------------------- |
    | `--raw` | Print the pre-AI-enhancement transcript when the item has one |

    ```bash theme={null}
    vowen read                      # latest dictation
    vowen read 1734567890123
    vowen read 17345 --raw          # what you actually said, before enhancement
    vowen read 17345 --json         # full item with metadata
    ```
  </Accordion>

  <Accordion title="delete: remove an item">
    ```
    vowen delete <id>
    ```

    Aliases: `rm`, `remove`. Works on dictations, transcriptions, and meeting notes.

    ```bash theme={null}
    vowen delete 1734567890123
    ```

    <Warning>Deletion is permanent and is not undoable from the CLI. It requires a paid plan; on the free plan the command exits with code 5.</Warning>
  </Accordion>

  <Accordion title="stats: usage statistics">
    ```
    vowen stats
    ```

    Always prints JSON: your lifetime totals, per-day activity for the last 30 days, and counts of dictations, transcriptions, and notes.

    ```bash theme={null}
    vowen stats | jq '.counts'
    ```
  </Accordion>

  <Accordion title="export: bulk export">
    ```
    vowen export [flags]
    ```

    Exports oldest first.

    | Flag             | Default | Description                                    |
    | ---------------- | ------- | ---------------------------------------------- |
    | `--format`, `-f` | `jsonl` | `jsonl` or `markdown`                          |
    | `--type`, `-t`   | `all`   | `dictation`, `transcription`, `note`, or `all` |
    | `--since`        |         | Only items on or after this date               |
    | `--before`       |         | Only items before this date                    |
    | `--output`, `-o` |         | Write to a file instead of stdout              |

    ```bash theme={null}
    vowen export > everything.jsonl
    vowen export --format markdown --type note -o notes.md
    vowen export --type dictation --since 2026-01-01 --format jsonl -o 2026.jsonl
    ```

    JSONL gives you one complete item object per line. Markdown gives a `## Title` heading per item with id, type, and date as a small metadata list, the body text, and a `### Summary` section where one exists.
  </Accordion>

  <Accordion title="watch: stream new items">
    ```
    vowen watch [flags]
    ```

    Polls the app and prints each newly finished item as a single-line JSON object. Runs until you interrupt it.

    | Flag           | Default | Description                                    |
    | -------------- | ------- | ---------------------------------------------- |
    | `--interval`   | `2s`    | Poll interval                                  |
    | `--type`, `-t` | `all`   | `dictation`, `transcription`, `note`, or `all` |

    ```bash theme={null}
    vowen watch --type dictation | jq -r '.text'
    vowen watch --interval 5s >> ~/dictation-log.ndjson
    ```

    Items that already existed when `watch` started are not replayed, and items still processing are held back until they settle, so you never get a half-finished transcript. If the app restarts mid-watch (which rotates the auth token), `watch` reconnects on its own instead of dying.
  </Accordion>
</AccordionGroup>

## Meeting notes

All of these live under `vowen notes`.

<AccordionGroup>
  <Accordion title="notes list: browse notes">
    ```
    vowen notes list [flags]
    ```

    Alias: `ls`. Newest first.

    | Flag             | Default | Description                      |
    | ---------------- | ------- | -------------------------------- |
    | `--limit`, `-l`  | `10`    | Maximum results                  |
    | `--offset`, `-o` | `0`     | Results to skip                  |
    | `--tag`          |         | Filter by tag id                 |
    | `--since`        |         | Only notes on or after this date |
    | `--before`       |         | Only notes before this date      |

    ```bash theme={null}
    vowen notes list
    vowen notes list --limit 30 --since 2026-08-01
    ```
  </Accordion>

  <Accordion title="notes read: print a note">
    ```
    vowen notes read <id> [flags]
    ```

    | Flag           | Description                         |
    | -------------- | ----------------------------------- |
    | `--summary`    | Print the AI summary                |
    | `--transcript` | Print the raw transcript            |
    | `--context`    | Print the context notes you entered |

    ```bash theme={null}
    vowen notes read 1734567890123
    vowen notes read 17345 --transcript > transcript.txt
    vowen notes read 17345 --json | jq -r '.title'
    ```

    With no flag, `notes read` prints the note's main body, which for an app-generated note is its AI summary. A title line appears above it when the note has one.
  </Accordion>

  <Accordion title="notes create: create a note from text">
    ```
    vowen notes create [flags]
    ```

    Content comes from `--text`, `--file`, or piped stdin, in that order of precedence.

    | Flag        | Description                                              |
    | ----------- | -------------------------------------------------------- |
    | `--title`   | Note title                                               |
    | `--text`    | Note content                                             |
    | `--file`    | Read note content from a file, as text                   |
    | `--context` | Context notes (attendees, agenda, and so on)             |
    | `--tag`     | Tag name or id, repeatable; created if it does not exist |

    ```bash theme={null}
    vowen notes create --title "Weekly sync" --text "Discussed the Q3 roadmap."
    vowen notes create --file agenda.md --tag work --tag planning
    pbpaste | vowen notes create --title "Pasted"
    ```

    <Warning>`--file` reads the file as text. Handing it a recording produces a note full of binary garbage. Use [`notes import`](#notes-import) for audio and video.</Warning>
  </Accordion>

  <Accordion title="notes import: audio or video into a meeting note">
    ```
    vowen notes import <file>... [flags]
    ```

    Transcribes and summarizes media files into meeting notes, the same pipeline as the Import button on the Notes page and as a watch folder with a meeting-note destination.

    | Flag             | Description                                               |
    | ---------------- | --------------------------------------------------------- |
    | `--model`, `-m`  | Transcription model id override (see [`models`](#models)) |
    | `--language`     | Language code override                                    |
    | `--provider`     | AI provider override for the summary                      |
    | `--template`     | Summary template override                                 |
    | `--diarize`      | Label speakers (paid plans)                               |
    | `--num-speakers` | Expected speaker count, used with `--diarize`             |
    | `--tag`          | Tag name or id, repeatable                                |
    | `--no-wait`      | Queue and print the note id immediately                   |

    ```bash theme={null}
    vowen notes import meeting.m4a
    vowen notes import *.m4a --no-wait
    vowen notes import call.wav --model parakeet-v3 --diarize --template standup
    ```

    Anything you do not pass falls back to your meeting-notes preferences. The work outlives a single HTTP request, so without `--no-wait` the CLI polls the note and shows elapsed time on stderr until it settles.
  </Accordion>

  <Accordion title="notes regenerate: rebuild a summary or transcript">
    ```
    vowen notes regenerate <id> [flags]
    ```

    By default the AI summary is rebuilt from the existing transcript. `--transcript` instead re-runs transcription against the note's stored audio, which produces a fresh summary as well.

    | Flag             | Description                                    |
    | ---------------- | ---------------------------------------------- |
    | `--summary`      | Regenerate only the summary (the default)      |
    | `--transcript`   | Re-transcribe the stored audio, then summarize |
    | `--model`, `-m`  | Transcription model id override                |
    | `--language`     | Language code override                         |
    | `--provider`     | AI provider override for the summary           |
    | `--template`     | Summary template override                      |
    | `--diarize`      | Label speakers (paid plans)                    |
    | `--num-speakers` | Expected speaker count                         |
    | `--no-wait`      | Start and print the note id immediately        |

    ```bash theme={null}
    vowen notes regenerate 17345 --template exec-brief
    vowen notes regenerate 17345 --transcript --model whisper-large-v3
    ```

    Passing both `--summary` and `--transcript` is rejected, since `--transcript` already regenerates the summary.
  </Accordion>

  <Accordion title="notes update: edit a note">
    ```
    vowen notes update <id> [flags]
    ```

    Only the fields you pass are changed. Passing an empty string clears that field.

    | Flag        | Description       |
    | ----------- | ----------------- |
    | `--title`   | New title         |
    | `--text`    | New content       |
    | `--context` | New context notes |
    | `--summary` | New summary       |

    ```bash theme={null}
    vowen notes update 17345 --title "Q3 planning (final)"
    vowen notes update 17345 --context "Attendees: Ana, Bo, Chen"
    ```
  </Accordion>

  <Accordion title="notes delete: remove a note">
    ```
    vowen notes delete <id>
    ```

    Aliases: `rm`, `remove`.

    ```bash theme={null}
    vowen notes delete 1734567890123
    ```

    <Warning>Permanent, and requires a paid plan. On the free plan this exits with code 5.</Warning>
  </Accordion>

  <Accordion title="notes start / stop / pause / resume: control a recording session">
    ```
    vowen notes start [--template <name>]
    vowen notes stop
    vowen notes pause
    vowen notes resume
    ```

    ```bash theme={null}
    vowen notes start --template standup
    vowen notes stop
    ```

    `notes start` does not report success until it has confirmed a session is genuinely live. Microphone capture happens inside the app window, so the CLI polls status for up to 15 seconds. If nothing started, it fails with a message pointing you at the Vowen window; the cause is usually a missing microphone or screen permission.
  </Accordion>
</AccordionGroup>

## Transcription

<AccordionGroup>
  <Accordion title="transcribe: transcribe files and wait">
    ```
    vowen transcribe <file>... [flags]
    ```

    Uses your currently selected model and language unless you override them. Results are saved to the app's Transcribe page like any manual import.

    | Flag              | Description                                   |
    | ----------------- | --------------------------------------------- |
    | `--model`, `-m`   | Model id override (see [`models`](#models))   |
    | `--language`      | Language code override                        |
    | `--diarize`       | Label speakers (paid plans)                   |
    | `--num-speakers`  | Expected speaker count, used with `--diarize` |
    | `--no-timestamps` | Flatten the output, no timestamps             |
    | `--tag`           | Tag name or id for the result, repeatable     |
    | `--no-wait`       | Queue and return the id immediately           |

    ```bash theme={null}
    vowen transcribe interview.m4a
    vowen transcribe *.wav --model whisper-large-v3 --tag research
    vowen transcribe call.mp3 --diarize --num-speakers 3
    vowen transcribe lecture.mp4 --json | jq -r '.text' > lecture.txt
    ```

    Progress is written to stderr, so redirecting stdout gives you a clean transcript. With multiple files, each transcript is preceded by a `==> file (id …)` header.

    <Note>The free plan allows a limited lifetime number of manual transcriptions and runs one at a time. Exceeding either exits with code 5.</Note>
  </Accordion>

  <Accordion title="import: queue files without waiting">
    ```
    vowen import <file>... [flags]
    ```

    Same as `transcribe --no-wait`, with friendlier output. It prints the queued id for each file and reminds you how to follow along.

    | Flag             | Description                    |
    | ---------------- | ------------------------------ |
    | `--model`, `-m`  | Model id override              |
    | `--language`     | Language code override         |
    | `--diarize`      | Label speakers (paid plans)    |
    | `--num-speakers` | Expected speaker count         |
    | `--tag`          | Tag for the result, repeatable |

    ```bash theme={null}
    vowen import ~/Recordings/*.m4a
    vowen history --type transcription
    ```

    <Note>`vowen import` produces transcriptions. `vowen notes import` produces meeting notes with an AI summary. Different commands, different destinations.</Note>
  </Accordion>

  <Accordion title="models: list available models">
    ```
    vowen models [--all]
    ```

    Lists the models you can use right now: local models you have downloaded, plus cloud models you have configured an API key for. The active one is marked.

    | Flag    | Description                                                   |
    | ------- | ------------------------------------------------------------- |
    | `--all` | Also include models that are not downloaded or not configured |

    ```bash theme={null}
    vowen models
    vowen models --all
    vowen models --json | jq -r '.active'
    ```

    Use the `ID` column as the value for `--model` on [`transcribe`](#transcribe) and [`notes import`](#notes-import).
  </Accordion>
</AccordionGroup>

## Dictionary, threads, and settings

<AccordionGroup>
  <Accordion title="tags: manage tag pools">
    ```
    vowen tags list|create|rename|delete [--pool notes|transcriptions]
    ```

    There are two independent tag pools. `--pool` is a persistent flag on every subcommand and defaults to `notes`.

    ```bash theme={null}
    vowen tags list
    vowen tags list --pool transcriptions
    vowen tags create "Client work" --color "#7C3AED"
    vowen tags rename "Client work" "Client"
    vowen tags delete Client
    ```

    | Subcommand | Syntax                                      | Notes                                                 |
    | ---------- | ------------------------------------------- | ----------------------------------------------------- |
    | `list`     | `vowen tags list`                           | Alias `ls`. Prints id, name, color                    |
    | `create`   | `vowen tags create <name> [--color <c>]`    | Reports if the tag already existed instead of failing |
    | `rename`   | `vowen tags rename <id-or-name> <new-name>` |                                                       |
    | `delete`   | `vowen tags delete <id-or-name>`            | Aliases `rm`, `remove`                                |
  </Accordion>

  <Accordion title="tag: tag an item">
    ```
    vowen tag <item-id> [--add <tag>] [--remove <tag>]
    ```

    | Flag       | Description                                                     |
    | ---------- | --------------------------------------------------------------- |
    | `--add`    | Tag name or id to add, repeatable; created if it does not exist |
    | `--remove` | Tag name or id to remove, repeatable                            |

    ```bash theme={null}
    vowen tag 17345 --add work
    vowen tag 17345 --add work --add urgent --remove draft
    ```

    At least one of `--add` or `--remove` is required. The CLI looks the item up first to find out whether it is a note or a transcription, so names resolve against the correct pool automatically.
  </Accordion>

  <Accordion title="vocab: manage your dictionary">
    ```
    vowen vocab list|add|remove
    ```

    Aliases for the group: `dictionary`, `dict`. These are the terms the transcriber should recognize, the same list as the [Dictionary](/features/dictionary) page.

    ```bash theme={null}
    vowen vocab list
    vowen vocab add MySQL
    vowen vocab add MySQL Nginx PostgreSQL "Anthony André"
    vowen vocab add --file words.txt
    pbpaste | vowen vocab add
    vowen vocab remove MySQL
    ```

    | Subcommand | Syntax                      | Notes                                                         |
    | ---------- | --------------------------- | ------------------------------------------------------------- |
    | `list`     | `vowen vocab list`          | Alias `ls`. One term per line                                 |
    | `add`      | `vowen vocab add <term>...` | `--file`/`-f` reads one term per line; piped stdin works too  |
    | `remove`   | `vowen vocab remove <term>` | Aliases `rm`, `delete`. Matches the whole term, ignoring case |

    `add` reports what it added and what it skipped as already present, so it is safe to re-run over the same list.
  </Accordion>

  <Accordion title="replacements: text replacements on transcripts">
    ```
    vowen replacements list|set|remove
    ```

    Aliases for the group: `threads`, `snippets`. These are the trigger-to-replacement rules applied to transcripts, the same list as the [Threads](/features/threads) page.

    ```bash theme={null}
    vowen replacements list
    vowen replacements set "my address" "12 Rue de Rivoli, Paris"
    vowen replacements remove "my address"
    ```

    | Subcommand | Syntax                                           | Notes                                     |
    | ---------- | ------------------------------------------------ | ----------------------------------------- |
    | `list`     | `vowen replacements list`                        | Alias `ls`                                |
    | `set`      | `vowen replacements set <trigger> <replacement>` | Creates or updates, keyed by trigger      |
    | `remove`   | `vowen replacements remove <trigger>`            | Aliases `rm`, `delete`. Accepts an id too |
  </Accordion>

  <Accordion title="expansions: live typing expansions">
    ```
    vowen expansions list|set|enable|disable|remove
    ```

    The shortcut-to-body expansions of the [text expander](/features/text-expander).

    ```bash theme={null}
    vowen expansions list
    vowen expansions set ":addr" "12 Rue de Rivoli, Paris"
    vowen expansions set ":sig" "**Best, Ana**" --format markdown
    vowen expansions disable ":addr"
    vowen expansions enable ":addr"
    vowen expansions remove ":addr"
    ```

    | Subcommand | Syntax                                                              | Notes                                                                    |
    | ---------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------ |
    | `list`     | `vowen expansions list`                                             | Alias `ls`. Shows shortcut, body, and whether it is on, off, or built in |
    | `set`      | `vowen expansions set <shortcut> <body> [--format plain\|markdown]` | Creates or updates, keyed by shortcut                                    |
    | `enable`   | `vowen expansions enable <shortcut>`                                |                                                                          |
    | `disable`  | `vowen expansions disable <shortcut>`                               |                                                                          |
    | `remove`   | `vowen expansions remove <shortcut>`                                | Aliases `rm`, `delete`. Accepts an id too                                |

    Built-in expansions cannot be deleted. `remove` rejects them and tells you to disable them instead.
  </Accordion>

  <Accordion title="settings: read and write settings">
    ```
    vowen settings get [key]
    vowen settings set <key> <value>
    ```

    `get` with no key prints all settings as JSON. With a key, prints just that value. Anything that looks like an API key, token, secret, password, or licence comes back as `<redacted>`.

    ```bash theme={null}
    vowen settings get
    vowen settings get language
    vowen settings set language en
    vowen settings set autoPaste true
    vowen settings set dailyGoal 30
    ```

    Values are parsed before being sent: `true` and `false` become booleans, digits become numbers, text starting with `{` or `[` is parsed as JSON, and everything else stays a string.

    **`set` only accepts these keys.** Anything else is rejected. Shortcuts, API keys, sync, and account settings are deliberately not writable from the CLI, because a malformed shortcut config can leave the keyboard hook in a bad state.

    `language`, `modelSize`, `transcriptionEngine`, `autoPaste`, `restoreClipboard`, `allowClipboardHistory`, `removeFillerWords`, `translateToEnglish`, `englishSpelling`, `theme`, `dailyGoal`, `saveRecordings`, `meetingNotesAutoStopOnEnd`, `meetingDetectionEnabled`, `cliServerEnabled`
  </Accordion>
</AccordionGroup>

## App control

<AccordionGroup>
  <Accordion title="record: control dictation">
    ```
    vowen record start [--mode instant|hold]
    vowen record stop
    vowen record toggle
    vowen record cancel
    ```

    Drives the same dictation path as your keyboard shortcut, so the transcript lands in your history and is pasted wherever your cursor is, exactly as if you had held the key.

    | Subcommand | Description                                                                     |
    | ---------- | ------------------------------------------------------------------------------- |
    | `start`    | Start recording. `--mode` accepts `instant` or `hold` and defaults to `instant` |
    | `stop`     | Stop and transcribe what was captured                                           |
    | `toggle`   | Start if idle, stop if recording                                                |
    | `cancel`   | Stop and discard, transcribing and pasting nothing                              |

    ```bash theme={null}
    vowen record start
    vowen record stop
    vowen record cancel
    ```

    `cancel` mirrors the Esc cancel path exactly, including clearing any active mute.
  </Accordion>

  <Accordion title="status: what the app is doing">
    ```
    vowen status
    ```

    ```
    $ vowen status
    App:        Vowen 0.5.4 (running)
    Plan:       pro
    Engine:     parakeet
    Model:      parakeet-v2
    Language:   en
    Recording:  false
    ```

    A notes-session line is added when one is active. `--json` returns the full status object, which also carries the platform and API version.

    ```bash theme={null}
    vowen status --json | jq -r '.plan'
    vowen status --no-launch   # exits 3 rather than starting the app
    ```
  </Accordion>

  <Accordion title="app: launch or version">
    ```
    vowen app launch
    vowen app version
    ```

    `app launch` starts the app in the background if it is not running and prints "Vowen is running." once the API answers. On macOS it does not steal focus.

    `app version` prints the running desktop app's version, which is unrelated to `vowen --version`.

    ```bash theme={null}
    vowen app launch --timeout 60s
    vowen app version
    ```
  </Accordion>
</AccordionGroup>

## Setup and tooling

<AccordionGroup>
  <Accordion title="doctor: diagnostics">
    ```
    vowen doctor
    ```

    Prints the CLI version, platform, the `VOWEN_CLI_SERVER` override if set, the discovered server file, the loopback port and API version, then the app version, plan, engine, and model.

    `doctor` never launches the app, so "not reachable" is a real answer rather than a race. See [the troubleshooting section](/cli/installation#troubleshooting) for how to read its output.
  </Accordion>

  <Accordion title="update: self-update the CLI">
    ```
    vowen update [--check]
    ```

    | Flag      | Description                                        |
    | --------- | -------------------------------------------------- |
    | `--check` | Report whether an update exists, do not install it |

    ```bash theme={null}
    vowen update --check
    vowen update
    ```

    Downloads the release manifest, verifies the SHA-256, and swaps the binary atomically. On Windows the running executable is renamed out of the way first, so this works even while `vowen mcp` is live under a coding agent.
  </Accordion>

  <Accordion title="completion: shell completions">
    ```
    vowen completion bash|zsh|fish|powershell
    ```

    Writes a completion script to stdout.

    ```bash theme={null}
    # zsh
    vowen completion zsh > "${fpath[1]}/_vowen"

    # bash
    vowen completion bash > /usr/local/etc/bash_completion.d/vowen

    # fish
    vowen completion fish > ~/.config/fish/completions/vowen.fish
    ```

    ```powershell theme={null}
    # PowerShell
    vowen completion powershell | Out-String | Invoke-Expression
    ```

    Run `vowen completion <shell> --help` for the exact install instructions for your setup.
  </Accordion>

  <Accordion title="mcp: run as an MCP server">
    ```
    vowen mcp
    ```

    Runs a Model Context Protocol server over stdio, exposing 23 tools covering search, history, notes, transcription, tags, vocabulary, replacements, expansions, settings, and recording control.

    ```bash theme={null}
    claude mcp add vowen -- vowen mcp
    ```

    This is not a command you run interactively. See [the MCP server page](/cli/mcp-server) for the full tool list and client setup.
  </Accordion>
</AccordionGroup>

## Environment variables

| Variable           | Effect                                                                                                |
| ------------------ | ----------------------------------------------------------------------------------------------------- |
| `VOWEN_CLI_SERVER` | Path to a `server.json` to use instead of normal discovery. When set, no other location is considered |

`VOWEN_CLI_SERVER` exists for development against a test instance. It is exclusive on purpose, so pointing the CLI at a throwaway app can never silently fall through to your real one.