> ## 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.
# Vowen CLI
> Drive the Vowen desktop app from your terminal, your scripts, and your coding agent.
One click from settings, or a single curl or PowerShell line
Every command, flag, and example
Give Claude Code and other agents access to your Vowen data
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](#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: ──▶ the running Vowen app
```
1. 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.
2. The CLI reads that file and sends `Authorization: Bearer ` on every request.
3. The server binds `127.0.0.1` only. It is never reachable from another machine.
4. 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 `` 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](/cli/commands#settings).
* **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](/cli/commands) page.
## Global flags
These three flags work on every command.
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.
```bash theme={null}
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.
```bash theme={null}
vowen watch --type dictation | while read -r line; do
echo "$line" | jq -r '.text'
done
```
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.
```bash theme={null}
vowen status --no-launch
```
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`.
```bash theme={null}
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
```bash theme={null}
#!/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
```
## Next steps
Install, update, uninstall, and troubleshoot
The complete reference