Vowen CLI

Install the CLI

One click from settings, or a single curl or PowerShell line

Command reference

Every command, flag, and example

MCP server

Give Claude Code and other agents access to your Vowen data

Manual transcription

The same import pipeline the CLI drives with vowen transcribe

What the CLI is

vowen is a small companion binary that talks to the Vowen desktop app. It is not a second copy of Vowen and it does not transcribe anything itself. Every command is a request to the app already running on your machine, so the CLI gets the same models you configured in the UI, the same dictionary and text replacements, the same plan limits, and the same data stores. So the desktop app has to be installed, and something has to be running. If the app is closed when you type a command, the CLI wakes it in the background for you (see Launching the app below). The CLI ships and versions independently of the desktop app. vowen --version and the app version are unrelated numbers.

How it connects

The vowen command does not run Vowen. It talks to the copy already running on your machine, so the app has to be open for any command to work.

vowen  ──▶  the running Vowen app  (this machine only)

Nothing is reachable from another machine, and no request leaves your computer. A few things the CLI deliberately cannot do:

Secrets are never returned. Anything that looks like an API key, token, secret, password or licence comes back as <redacted> from vowen settings get.
Only some settings can be written. vowen settings set accepts a fixed list of keys. Shortcuts, API keys, sync and account settings are not on it. The full list is in the command reference.
Deleting requires a paid plan. vowen delete and vowen notes delete exit with code 5 on the Free plan.

The CLI connection is on by default. vowen settings set cliServerEnabled false turns it off, taking effect the next time the app starts. With it off, no vowen command can reach the app.

What you can do with it

Area	Commands
Read your data	`history`, `search`, `read`, `stats`, `export`, `watch`
Meeting notes	`notes list`, `notes read`, `notes create`, `notes import`, `notes regenerate`, `notes update`, `notes delete`, `notes start/stop/pause/resume`
Transcribe files	`transcribe`, `import`, `models`
Configure	`tags`, `tag`, `vocab`, `replacements`, `expansions`, `settings`
Control the app	`record start/stop/toggle/cancel`, `status`, `app launch`, `app version`
Setup and tooling	`doctor`, `mcp`, `update`, `completion`

Full syntax for all of them is on the command reference page.

Global flags

These three flags work on every command.

--json: machine-readable output

Prints the raw API response as indented JSON instead of the human-readable table. Use it in scripts. The table layout is not a stable contract; the JSON shape is what the app actually serves.

vowen history --limit 50 --json | jq -r '.items[] | .text'
vowen status --json | jq -r '.model'

vowen watch never pretty-prints. It always emits one compact JSON object per line (NDJSON), so it can be piped straight into a line-oriented consumer.

vowen watch --type dictation | while read -r line; do
  echo "$line" | jq -r '.text'
done

--no-launch: never start the app

By default, a command issued while the app is closed launches it. --no-launch turns that off. If no live app is found, the command fails immediately with exit code 3.Use it in cron jobs, CI, and status checks where silently starting a desktop app would be the wrong behavior.

vowen status --no-launch

--timeout: how long to wait for the app

How long to wait for the app to come up after the CLI wakes it. Defaults to 20s. Accepts Go duration strings: 5s, 1m, 500ms.

vowen status --timeout 45s

This is the launch wait only. It does not cap how long a transcription takes.

Launching the app

When the app is not running and --no-launch was not passed, the CLI fires the vowen://cli/wake deeplink and polls until the API answers or --timeout expires. On macOS it launches without stealing focus, so a command typed in your terminal will not pull a window in front of you. The deeplink can only wake the app. It carries no data and cannot read or write anything, so a link clicked in a browser cannot reach your history.

Exit codes

Code	Meaning
`0`	Success
`1`	Error (bad arguments, file not found, API error, network failure)
`3`	The app is not running, and could not be launched within the timeout
`5`	Your plan does not allow this operation

The CLI exits 5 when the app answers upgrade_required, which happens when you delete history or notes, exceed the free lifetime transcription limit, or queue a second transcription while one is already running.

Handling exit 3 in a script

#!/usr/bin/env bash
set -uo pipefail

# Probe without launching, so this script never pops a desktop app open
# unexpectedly on a headless or unattended run.
vowen status --no-launch >/dev/null 2>&1
case $? in
  0)
    ;;
  3)
    echo "Vowen is not running." >&2
    # Decide explicitly: either bail out...
    exit 0
    # ...or wake it on purpose:
    # vowen app launch --timeout 60s || exit 1
    ;;
  5)
    echo "This operation needs a paid plan." >&2
    exit 1
    ;;
  *)
    echo "vowen failed unexpectedly." >&2
    exit 1
    ;;
esac

vowen history --type dictation --limit 20 --json > today.json

Diagnostics

Run vowen doctor first when something is not working. It prints the CLI version, your platform, whether it can reach the app, and then the app version, plan, and active engine and model. It never launches the app, so a “not reachable” line is a genuine signal rather than a race.

$ vowen doctor
CLI version:   0.2.0
Platform:      darwin/arm64
Server file:   /Users/you/Library/Application Support/Vowen/cli/server.json
API:           127.0.0.1:52341 (v1) — OK
App version:   0.5.4
Plan:          pro
Engine/model:  parakeet / parakeet-v2

Vowen CLI

Install the CLI

Command reference

MCP server

Manual transcription

What the CLI is

How it connects

What you can do with it

Global flags

Launching the app

Exit codes

Handling exit 3 in a script

Diagnostics

Next steps

Installation

Commands

Install the CLI

Command reference

MCP server

Manual transcription

​What the CLI is

​How it connects

​What you can do with it

​Global flags

​Launching the app

​Exit codes

​Handling exit 3 in a script

​Diagnostics

​Next steps

Installation

Commands

What the CLI is

How it connects

What you can do with it

Global flags

Launching the app

Exit codes

Handling exit 3 in a script

Diagnostics

Next steps