> ## 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.

# Installing the CLI

> Install, update, and remove the vowen command line tool.

The `vowen` binary is a separate download from the desktop app. There are three ways to get it, and they all end up with the same binary in the same place.

<Note>The Vowen desktop app must be installed too. The CLI has no transcription engine of its own, it drives the app. See [how the CLI connects](/cli/overview#how-it-connects).</Note>

## Option 1: install from settings

The easiest path, and the one that keeps working when you change machines.

<Steps>
  <Step title="Open Settings > Developer">
    Open the Settings modal from the sidebar footer, then pick the **Developer** section.
  </Step>

  <Step title="Find Command Line Tool">
    The first card is **Command Line Tool**. If the CLI is not installed yet, it shows a single **Install CLI** button.
  </Step>

  <Step title="Click Install CLI">
    Vowen fetches the release manifest from `assets.vowen.ai`, downloads the archive for your platform, verifies its SHA-256 against the manifest, unpacks it, and writes the binary into a per-user bin directory.
  </Step>

  <Step title="Confirm it worked">
    The card switches to reading `vowen <version> installed at <path>`. Open a new terminal and run `vowen status`.
  </Step>
</Steps>

Two details of that flow:

* **The checksum is enforced, not advisory.** If the downloaded bytes do not match the SHA-256 in the manifest, the install aborts with "Checksum verification failed — refusing to install" and nothing is written.
* **The archive is unpacked in-process.** Vowen never shells out to `tar` or `unzip`. On Windows, a GNU `tar` from Git for Windows, MSYS2, Cygwin, or Strawberry Perl often wins the PATH lookup, reads `-f C:\...` as a remote `host:path` spec, and cannot read ZIP at all. Extracting inside the app removes that whole class of problem.

## Option 2: curl (macOS)

```bash theme={null}
curl -fsSL https://assets.vowen.ai/cli/install.sh | bash
```

The script resolves the latest version from `assets.vowen.ai/cli/latest.json`, downloads the universal macOS binary, verifies it against the published `checksums.txt`, installs it, and then runs `vowen --version` to confirm the binary actually executes before declaring success.

Two environment variables change its behavior:

| Variable            | Effect                                                                |
| ------------------- | --------------------------------------------------------------------- |
| `VOWEN_CLI_VERSION` | Install a specific version instead of the latest, for example `0.2.0` |
| `VOWEN_CLI_BINDIR`  | Install into a directory of your choosing                             |

```bash theme={null}
VOWEN_CLI_VERSION=0.2.0 curl -fsSL https://assets.vowen.ai/cli/install.sh | bash
VOWEN_CLI_BINDIR="$HOME/bin" curl -fsSL https://assets.vowen.ai/cli/install.sh | bash
```

<Note>This script is macOS-only. Run on anything else, it stops and points you at the PowerShell installer.</Note>

## Option 3: PowerShell (Windows)

```powershell theme={null}
irm https://assets.vowen.ai/cli/install.ps1 | iex
```

The Windows script does the same job: resolve the version, download `vowen-<version>-windows-x64.zip`, compare its SHA-256 against `checksums.txt`, extract it, unblock the file, add its directory to your **user** PATH, and run `vowen --version` to prove the binary works.

| Variable                 | Effect                                    |
| ------------------------ | ----------------------------------------- |
| `$env:VOWEN_CLI_VERSION` | Install a specific version                |
| `$env:VOWEN_CLI_BINDIR`  | Install into a directory of your choosing |

```powershell theme={null}
$env:VOWEN_CLI_VERSION = "0.2.0"
irm https://assets.vowen.ai/cli/install.ps1 | iex
```

<Tip>The PATH entry is written through the registry, preserving the value's original type. The obvious `[Environment]::SetEnvironmentVariable` approach reads back an already-expanded PATH and would permanently freeze every `%VAR%` you had in there.</Tip>

## Where the binary lands

| Platform | Location                                                                               |
| -------- | -------------------------------------------------------------------------------------- |
| macOS    | `/usr/local/bin/vowen` when that directory is writable, otherwise `~/.local/bin/vowen` |
| Windows  | `%LOCALAPPDATA%\Vowen\bin\vowen.exe`                                                   |

Both the in-app installer and the shell scripts follow the same policy, so it does not matter which one you used. `vowen doctor` prints the path it is running from if you are ever unsure.

The in-app installer also treats anything already on your PATH as installed. If you previously ran the shell installer with a custom `VOWEN_CLI_BINDIR`, the settings card finds that copy rather than dropping a second binary somewhere else.

## Updating

The CLI versions independently of the app, so "update" means "fetch whatever the release manifest currently points at", not "match the app version".

<Tabs>
  <Tab title="From settings">
    Open **Settings > Developer > Command Line Tool**. When a newer release exists, the card shows "Update available: `<yours>` to `<latest>`" and the **Update CLI** button becomes the primary action. Clicking it always goes to the network.
  </Tab>

  <Tab title="From the terminal">
    ```bash theme={null}
    vowen update --check   # report only
    vowen update           # download and install
    ```

    `vowen update` downloads the manifest, verifies the SHA-256, and swaps the binary in place. On Windows it renames the running executable out of the way first, so updating works even while `vowen mcp` is live under a coding agent.
  </Tab>
</Tabs>

## Uninstalling

<Tabs>
  <Tab title="From settings">
    **Settings > Developer > Command Line Tool > Uninstall CLI**. This removes every copy it knows about, including ones discovered on your PATH and any `.old` leftovers from a Windows update.
  </Tab>

  <Tab title="Manually">
    ```bash theme={null}
    # macOS
    rm -f /usr/local/bin/vowen ~/.local/bin/vowen
    ```

    ```powershell theme={null}
    # Windows
    Remove-Item "$env:LOCALAPPDATA\Vowen\bin\vowen.exe"
    ```

    On Windows, also remove `%LOCALAPPDATA%\Vowen\bin` from your user PATH if you no longer want it there.
  </Tab>
</Tabs>

Uninstalling the CLI does not touch the desktop app, your history, or your settings.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Windows: 'the binary would not run' after a successful download">
    The full message is: *"Installed to `<path>`, but the binary would not run. This is almost always antivirus quarantine — allow that file in Windows Security, then click again."*

    The download succeeded and the checksum matched, so the file is intact, but something on the machine is preventing it from executing. Both installers run `vowen --version` after writing the file so this gets caught here, instead of surfacing later as a confusing `'vowen' is not recognized` in your terminal.

    To fix it:

    1. Open **Windows Security > Virus & threat protection > Protection history** and look for a recent quarantine or block on `vowen.exe`.
    2. Restore it, or add an exclusion for `%LOCALAPPDATA%\Vowen\bin`.
    3. Run the installer again.

    Third-party antivirus products behave the same way; the exclusion just lives somewhere else. Unsigned or freshly published binaries are the usual trigger.
  </Accordion>

  <Accordion title="macOS: 'the binary would not run' after a successful download">
    The macOS variant of the same check reports: *"Installed to `<path>`, but the binary would not run. Check that `<dir>` is not mounted noexec."*

    This shows up when the install directory sits on a volume mounted with `noexec`, which strips the ability to execute anything stored there regardless of file permissions. Reinstall into a normal location:

    ```bash theme={null}
    VOWEN_CLI_BINDIR="$HOME/.local/bin" curl -fsSL https://assets.vowen.ai/cli/install.sh | bash
    ```
  </Accordion>

  <Accordion title="'vowen: command not found': PATH is not picking it up">
    The binary installed fine, your shell just cannot see it.

    **macOS.** If the installer fell back to `~/.local/bin` (because `/usr/local/bin` was not writable), that directory may not be on your PATH. The installer prints a warning when it detects this. Add it to your shell profile:

    ```bash theme={null}
    export PATH="$HOME/.local/bin:$PATH"
    ```

    Then open a new terminal, or `source` the profile you just edited.

    **Windows.** The PATH entry is added to your user environment, which existing terminals do not re-read. Close and reopen your terminal. If it still is not found, confirm the directory is present:

    ```powershell theme={null}
    [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment').GetValue('Path')
    ```

    Add `%LOCALAPPDATA%\Vowen\bin` manually if it is missing.

    Either way, you can always invoke the binary by full path to confirm it is really installed:

    ```bash theme={null}
    /usr/local/bin/vowen --version
    ```
  </Accordion>

  <Accordion title="Run vowen doctor">
    `doctor` never launches the app, so what it reports is the true current state.

    ```
    $ 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
    ```

    How to read it:

    * **`CLI version` printed but nothing else.** The binary works and the problem is the connection, not the install.
    * **`App: not reachable (is Vowen running?)`.** Either the app is closed, or the loopback API is disabled. Start the app and try again; if it is already running, check `cliServerEnabled` (see [the overview](/cli/overview#how-it-connects)).
    * **No `Server file` line.** The app has not written its discovery file, which normally means it has not started since the CLI API was enabled.
    * **`Status check: FAILED`.** The port answered but the request did not. This usually means a stale server file from an unclean quit; restarting the app rewrites it.
  </Accordion>

  <Accordion title="Checksum verification failed">
    The download did not match the published SHA-256, and the installer refused to write it. Nothing was installed, so there is nothing to clean up.

    This is nearly always a corporate proxy or content filter rewriting the response body. Retry on a different network, or download the archive listed in `assets.vowen.ai/cli/latest.json` directly and check it against `checksums.txt` yourself.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Command reference" icon="terminal" href="/cli/commands">
    Every command and flag, with examples
  </Card>

  <Card title="MCP server" icon="plug" href="/cli/mcp-server">
    `claude mcp add vowen -- vowen mcp`
  </Card>
</CardGroup>