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

vowen  ──HTTP──▶  127.0.0.1:<random port>  ──▶  the running Vowen app

On every launch, the app starts a loopback HTTP API and writes cli/server.json inside its user data folder with the port and a bearer token. The file is written with 0600 permissions.
The CLI reads that file and sends Authorization: Bearer <token> on every request.
The server binds 127.0.0.1 only. It is never reachable from another machine.
The token is regenerated on every app start, so a token captured from an old session is useless.

The API also limits what the CLI can reach:

Secrets are redacted on read. Any settings key that looks like an API key, token, secret, password, or licence comes back as <redacted> from vowen settings get.
Writes are whitelisted. 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 return exit code 5 on the free plan.

The loopback API is on by default. vowen settings set cliServerEnabled false turns it off, and it takes 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, the server file it discovered, the loopback port and API version, 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