voxi full command reference.

voxi

Standalone Linux voice input, continuous eager streaming, and desktop typing engine

Voxi is a high-performance voice input and typing engine for Linux/Wayland.
It provides continuous eager sentence streaming with local Cohere Transcribe by default,
modifier key gating daemon for hotkey safety, synthetic typing injection, and a btop-style monitor.

voxi agent

Run or control the unified Voxi voice-input agent

--daemon

run the agent daemon and control socket

--socket

Unix socket path (default: XDG runtime dir)

--state

persistent mode-state path

voxi agent record [toggle|start|stop]

Control recording through the agent

voxi agent set-mode [batch|streaming|eager]

Set the agent's selected voice-input backend

voxi agent status

Print the agent's selected mode and recording state

voxi bench [flags]

Benchmark CPU vs GPU transcription speed across configured Whisper models

Transcribes one audio clip through every whisper-engine model in spec/models.yaml
(driven via voxtype) on each requested backend, reporting the real-time factor (RTF)
and speedup for each model x backend pair. Non-whisper engines (e.g. cohere-transcribe)
are reported as skipped rather than benched. By default it uses a fixed reference clip
downloaded on demand into the user cache dir (never committed to the repo); pass
--record for a live microphone clip or --file for a local WAV.

--backends

comma-separated backends to bench: cpu, gpu (default: gpu,cpu) (default: [gpu,cpu])

--duration

seconds of microphone audio to record when --record is set (default: 8)

--file

use this 16kHz mono WAV instead of the reference clip or recording

--json

write the full bench report as JSON to this path

--models

comma-separated model names to bench (default: every whisper-engine model in spec/models.yaml; non-whisper models are reported as skipped)

--record

record live microphone audio instead of using the downloaded reference clip

--threads

CPU threads passed to voxtype (default: 6)

voxi chunks

Inspect, play, and debug recent recorded audio chunks and transcription metadata

Inspect, play, and debug the recordings cut by live dictation. Save a chunk permanently with `voxi sample add ID --chunk N`.

Terms:
chunk one recording cut by live dictation, with its ASR diagnostics; only the
last 100 are kept, in $XDG_RUNTIME_DIR (cleared on reboot) when available
sample a saved recording with its exact transcript, stored by purpose under
~/.local/share/voxi/samples/{dictation,noise,voice}
purpose dictation (ASR accuracy checks), noise (must yield no text; the only
publishable purpose) or voice (your own voice, for cloning and training;
needs your consent)
publish copy a noise sample into the repository's public store (testdata/samples)
merge join samples or chunks into one longer sample
voice an installed TTS voice, built from voice samples; not a sample itself
Reference: docs/SampleStore.md

voxi chunks delete [INDEX|last] [flags]

Delete recorded chunk audio and transcript metadata

Delete one recorded chunk, every stored chunk, or chunks matching selected categories.

--all

delete every stored chunk

--empty

delete chunks with empty rejection reason

--low-energy

delete chunks with low_energy_transient rejection

--unvoiced

delete chunks with unvoiced_transient rejection

-y, --yes

skip confirmation for --all and category filters

voxi chunks list [flags]

List recent recorded chunks and their transcription outcomes

-a, --all

include older chunks that are kept on disk but hidden by default

--color

colorize the LEVEL sparkline by loudness: auto, always, or never (default: auto)

--format

output format (text or json) (default: text)

-r, --reverse

list newest chunks first

voxi chunks play [INDEX|last]

Play audio of a recorded chunk (defaults to last)

voxi chunks show [INDEX|last] [flags]

Show detailed diagnostics for a chunk (defaults to last)

--format

output format (json or text) (default: json)

voxi completion

Generate the autocompletion script for the specified shell

Generate the autocompletion script for voxi for the specified shell.
See each sub-command's help for details on how to use the generated script.

voxi completion bash

Generate the autocompletion script for bash

Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package.
If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

source <(voxi completion bash)

To load completions for every new session, execute once:

#### Linux:

voxi completion bash > /etc/bash_completion.d/voxi

#### macOS:

voxi completion bash > $(brew --prefix)/etc/bash_completion.d/voxi

You will need to start a new shell for this setup to take effect.

--no-descriptions

disable completion descriptions

voxi completion fish [flags]

Generate the autocompletion script for fish

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

voxi completion fish | source

To load completions for every new session, execute once:

voxi completion fish > ~/.config/fish/completions/voxi.fish

You will need to start a new shell for this setup to take effect.

--no-descriptions

disable completion descriptions

voxi completion powershell [flags]

Generate the autocompletion script for powershell

Generate the autocompletion script for powershell.

To load completions in your current shell session:

voxi completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command
to your powershell profile.

--no-descriptions

disable completion descriptions

voxi completion zsh [flags]

Generate the autocompletion script for zsh

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need
to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(voxi completion zsh)

To load completions for every new session, execute once:

#### Linux:

voxi completion zsh > "${fpath[1]}/_voxi"

#### macOS:

voxi completion zsh > $(brew --prefix)/share/zsh/site-functions/_voxi

You will need to start a new shell for this setup to take effect.

--no-descriptions

disable completion descriptions

voxi config

Read or change select voxtype config.toml fields

voxi config get type-delay-ms

Print current type_delay_ms value

voxi config import DIR [flags]

Merge stop-words, replacements, and vocabulary from another machine's local Voxi state

Merge stop-words.json, replacements.json, and vocabulary.txt from DIR --
a local, previously-copied ~/.config/voxi-shaped directory -- into this machine's
local Voxi state. DIR must already be a local directory (e.g. copied over with
scp/rsync/USB beforehand) -- import performs no transfer of its own.

config.yaml and env are intentionally not imported: they hold machine-specific
settings (paths, device IDs) that don't safely carry over between machines.

--only

import only these areas: stop-words,replacements,vocabulary (default: all found in DIR)

--overwrite

replace a colliding replacement entry instead of skipping it (stop-words and vocabulary are always additive)

voxi config set type-delay-ms MS

Set type_delay_ms, preserving comments and other settings

voxi daemon

Run background services managed by voxi

voxi daemon modifier-service [flags]

Dedicated evdev modifier key state monitoring daemon

Monitors physical modifier keys (Ctrl, Alt, Super, Shift) across all /dev/input/event* keyboards,
and exports an atomic 1-byte bitmask state to a world-readable file (/run/voxi/modifiers).
Never captures or records non-modifier keycodes, preserving strict privacy.

--interval

polling and update interval (default: 10ms) (default: 10ms)

--state-file

path to world-readable modifier state file (default: /run/voxi/modifiers) (default: /run/voxi/modifiers)

voxi eager [flags]

Continuous eager sentence streaming dictation into focused window

Continuously captures audio from the microphone with a circular pre-roll buffer.
Segments speech on natural conversational pauses (silence > 800ms) or rolling windows,
transcribes completed phrases immediately with the selected model's engine (Cohere
Transcribe via crispasr by default, or Whisper via voxtype for an explicit --model),
and types finalized sentences directly into the active application via dotool with zero
dropped words across pauses. crispasr is required for the default engine; voxtype is only
required when an explicit Whisper --model is selected.

--daemon

run as background systemd daemon listening for toggle control

--history

record transcribed utterances into local dictation history (default: true)

--max-window

maximum window length in ms before forcing a phrase chunk (default: 8000) (default: 8000)

--min-speech

minimum speech duration in ms to ignore noise (default: 200) (default: 200)

--model

model name, see spec/models.yaml (default: cohere-transcribe-03-2026)

--modifier-gating

wait for physical modifiers before typing output (default: true)

--pre-roll

pre-speech circular buffer duration in ms to preserve starting phonemes (default: 500) (default: 500)

--silence

silence duration in ms to finalize an utterance chunk (default: 800) (default: 800)

--speech-context

bounded local vocabulary hints (default: true)

--threshold

audio RMS energy threshold to trigger speech detection (default: 150) (default: 150)

--type

type transcribed sentences directly into the focused window via dotool (default: true)

--vocabulary

additional comma-separated speech-context terms

voxi feedback

Manage local dictation feedback

voxi feedback replacement

Manage exact Cohere transcript corrections

voxi feedback replacement add HEARD WRITTEN [flags]

Add a heard-form to written-form mapping, case-insensitive and case-adaptive

--fixed-case

always write WRITTEN exactly as given, regardless of how HEARD was cased (use for domains and the like)

voxi feedback replacement cleanup [flags]

Remove case-variant duplicates now redundant under case-insensitive matching

--dry-run

preview duplicates without writing changes

voxi feedback replacement list

List exact Cohere transcript corrections

voxi feedback replacement remove HEARD

Remove an exact heard-form mapping

voxi feedback silence-artifact

Manage whole-utterance silence artifacts

voxi feedback silence-artifact add PHRASE

voxi feedback silence-artifact list

voxi feedback silence-artifact remove PHRASE

voxi feedback status

Show a combined summary of local stop-word, silence-artifact, and vocabulary state

voxi feedback stop-word

Manage local ASR stop-word rules

voxi feedback stop-word add PHRASE

voxi feedback stop-word disable ID

voxi feedback stop-word enable ID

voxi feedback stop-word list

voxi feedback stop-word remove PHRASE

voxi feedback vocabulary

Manage persistent speech-context terms

voxi feedback vocabulary add TERM

voxi feedback vocabulary list

voxi feedback vocabulary remove TERM

voxi history

Recent dictation history (local-only, treat as sensitive)

voxi history clear

Delete all recorded history

voxi history copy ID

Copy a history entry's text to the clipboard

voxi history list [flags]

List recent transcripts, most recent first

--format

output format (text or json) (default: text)

--limit

show at most N entries (default: all) (default: 0)

voxi history record

Internal: record stdin as a history entry and echo it back unchanged

voxi history retype ID

Type a history entry's text into the currently focused window

voxi install [flags]

Install Voxi for this user (optional: --modifierd needs sudo)

Install the CLI and systemd user services under your home directory, then enable and start voxi-agent.service.
When TTS tools are missing, Voxi asks before using sudo and the system package manager.

Use --no-tts to persistently opt out of TTS packages. Use --voxcpm to install the VoxCPM Vulkan runtime and cloned-voice model. Use --modifierd for the optional system-wide physical modifier daemon; it also requires sudo and Linux systemd.

--modifierd

also install the optional system-wide modifier daemon (requires sudo)

--no-tts

disable TTS and skip Festival/espeak-ng system packages

--voxcpm

install the VoxCPM Vulkan runtime, model, and cloned-voice references

voxi man [flags]

generate and print or install roff man pages

man generates standard roff/troff man pages from voxi's command tree.

Without flags, it prints the roff man page to stdout (e.g. voxi man | man -l -).
With --install, it writes .1 man pages to ~/.local/share/man/man1
(or /usr/local/share/man/man1 if root).
With --html, it prints one static HTML page covering every command to stdout.

-d, --dir

custom target directory for man pages (implies --install)

-h, --help

help for man

--html

print one static HTML page covering every command to stdout

--install

install man pages into standard system or user man directory

voxi mic [flags]

Check the PipeWire mic setup and optionally repair it

Show the default mic and any problems with it: no usable default, a saved default that is not connected, or a Bluetooth headphone in playback-only mode (A2DP) with no mic.

With --fix, clear the stale saved default, switch connected Bluetooth headphones to headset mode, and fall back to a built-in mic. Voxi runs the same check alongside every recording.

--fix

repair the problems found

voxi mode [batch|streaming|eager]

Show or switch the active voice-input mode

voxi monitor [flags]

Monitor voice input daemon, GPU acceleration, memory, and subprocess resources

-c, --compact

display compact two-box monitor layout

-i, --interval

refresh interval in seconds for --watch (default: 1)

-s, --sections

comma-separated sections: s(speed), h(hardware), t(transcript), d(daemons), tts, c(compact) (default: spec panel defaults)

-w, --watch

continuously refresh resource metrics

voxi record

Start, stop, or toggle active voice dictation recording

voxi record start

Start dictation recording

voxi record status

Print recording status (idle or recording)

voxi record stop

Stop dictation recording

voxi record toggle

Toggle dictation recording on or off

voxi sample

Manage persistent audio samples

Record, save, edit, merge, and publish persistent audio samples.

Terms:
chunk one recording cut by live dictation, with its ASR diagnostics; only the
last 100 are kept, in $XDG_RUNTIME_DIR (cleared on reboot) when available
sample a saved recording with its exact transcript, stored by purpose under
~/.local/share/voxi/samples/{dictation,noise,voice}
purpose dictation (ASR accuracy checks), noise (must yield no text; the only
publishable purpose) or voice (your own voice, for cloning and training;
needs your consent)
publish copy a noise sample into the repository's public store (testdata/samples)
merge join samples or chunks into one longer sample
voice an installed TTS voice, built from voice samples; not a sample itself
Reference: docs/SampleStore.md

--public-store

public (git-tracked) sample store root, relative to the repository root (default: testdata/samples)

voxi sample add ID [flags]

Add a recent chunk to the sample store

Copy audio from a recent chunk into the sample store and enter its transcript.

Example: voxi sample add meeting-intro --last --purpose dictation

--chunk

chunk index

--last

use the most recent chunk

--own-voice

confirm without prompting that this is your own voice and you consent to cloning it

--purpose

sample purpose: dictation, noise, or voice (default: dictation)

voxi sample delete ID...

Delete samples from the private store

Delete one or more samples from the private store. Every ID is checked before any sample is removed.

Example: voxi sample delete greeting keyboard-noise

voxi sample edit ID

Edit a sample transcript

Edit the transcript for a sample using $VISUAL or $EDITOR.

Example: voxi sample edit greeting

voxi sample list [flags]

List samples in the private store

List samples in the private store.

Example: voxi sample list --purpose dictation

--public

list the public store instead of the private store

--purpose

limit to dictation, noise, or voice

voxi sample merge ID SOURCE... [flags]

Merge samples or chunks into one longer sample

Join two or more samples (or, with --chunks, recent chunks) in the given order into a new sample.
Parts are separated by --gap silence and must share sample rate and format; nothing is resampled or normalized.
The joined transcript opens in $VISUAL/$EDITOR for review. Inputs are never changed; the new sample's
source field lists them. Chunks must come from one session, be accepted, and lie at most 30s apart,
unless --force is given.

Example: voxi sample merge paragraph intro-1 intro-2
Example: voxi sample merge paragraph --chunks 12 13 14 --purpose voice

--chunks

sources are chunk indices from `voxi chunks list`

--force

allow chunks from different sessions, far apart, or rejected

--gap

silence between parts (default: 300ms)

--max-duration

refuse merged audio longer than this (default: 20s)

--own-voice

confirm without prompting that this is your own voice and you consent to cloning it

--purpose

purpose of the new sample (default: the sources' purpose, dictation for chunks)

voxi sample move ID PURPOSE [flags]

Move a sample to another purpose

Move a sample to the dictation, noise, or voice purpose. Moving into voice asks you to confirm that the sample is your own voice and that you consent to cloning it.

Example: voxi sample move greeting noise

--own-voice

confirm without prompting that this is your own voice and you consent to cloning it

voxi sample play ID

Play a sample

Play a sample using a local audio player.

Example: voxi sample play greeting

voxi sample publish ID [flags]

Publish a noise sample to the public store

Encode a private noise sample as FLAC and copy it into the public (git-tracked) store. Only noise samples can be published, and you must confirm that the audio contains no intelligible speech.

Example: voxi sample publish keyboard-clack --no-speech

--no-speech

confirm without prompting that the sample contains no intelligible speech

voxi sample record [--purpose P] ID [flags]

Record a sample with a corrected transcript

Record audio from the microphone and save it with a corrected transcript.

Example: voxi sample record --purpose noise room-tone

--own-voice

confirm without prompting that this is your own voice and you consent to cloning it

--purpose

sample purpose: dictation, noise, or voice (default: dictation)

voxi sample show ID

Show sample metadata

Show the metadata for one sample.

Example: voxi sample show greeting

voxi say [text...] [flags]

Rewrite text for speech with an LLM, then read it aloud

--from

read from Wayland primary selection or clipboard

--interrupt

stop current TTS and replace it with this text

--llm

override the lmcoder host; narration is enabled by default

--no-llm

read the original text without LLM rewriting

--no-play

synthesize without playback (requires --output)

-o, --output

synthesize WAV directly to this file without playback

voxi settings [flags]

Interactive TUI for Voxi feature toggles and configuration

Interactive terminal menu to view and toggle core Voxi settings:
• LLM Post-Processing Cleaner
• Cleanup Model Selection
• ASR Model Selection
• TTS Backend (tts_backend)
• Keystroke Delay (type_delay_ms)
• Dictation History
• Modifier Key Gating (voxi-modifierd)

Pass --test (or 'voxi settings test') to verify that all configured features
and host dependencies are working.

-d, --dump

print current settings non-interactively

--format

output format: text or json (default: text)

--json

output current settings or test results as JSON

-t, --test

run end-to-end diagnostic checks on all configured settings and dependencies

voxi settings test [flags]

Run end-to-end diagnostic checks on all configured settings and dependencies

--format

output format: text or json (default: text)

--json

output diagnostic results as JSON

voxi shortcut

Manage the standard desktop recording shortcut

voxi shortcut remove

Remove the Voxi-owned GNOME shortcut

voxi shortcut setup [flags]

Configure Super+X on GNOME

-f, --force

proceed despite an existing Super+X assignment

voxi status

Show the active keyboard source and dotoold layout

voxi telemetry

Query correlated Eager pipeline telemetry

voxi telemetry query [flags]

List raw events or correlated lifecycle records

--chunk

filter by chunk ID

--event

filter raw events by event type

--format

output format: text or json (default: text)

--limit

maximum rows to print (0 means all within --max-events) (default: 100)

--max-events

hard memory bound on valid events in the selected time range (default: 100000)

--path

telemetry JSONL path (default: Voxi XDG data path)

--post-deactivation

filter chunks: any, true, or false (default: any)

--session

filter by session ID

--silence

filter chunks: any, true, or false (default: any)

--since

include timestamps at/after RFC3339 time

--success

filter events/chunks: any, true, or false (default: any)

--until

include timestamps at/before RFC3339 time

--view

view: events, chunks, or sessions (default: chunks)

voxi telemetry stats [flags]

Summarize latency, backlog, audio, words, and stage outcomes

--chunk

filter by chunk ID

--format

output format: text or json (default: text)

--max-events

hard memory bound on valid events in the selected time range (default: 100000)

--path

telemetry JSONL path (default: Voxi XDG data path)

--session

filter by session ID

--since

include timestamps at/after RFC3339 time

--until

include timestamps at/before RFC3339 time

voxi voice

Prepare and train custom Piper voices

Build TTS voices from your voice-purpose samples. Only samples in the voice purpose, stored with your own-voice consent, are ever read.

Terms:
chunk one recording cut by live dictation, with its ASR diagnostics; only the
last 100 are kept, in $XDG_RUNTIME_DIR (cleared on reboot) when available
sample a saved recording with its exact transcript, stored by purpose under
~/.local/share/voxi/samples/{dictation,noise,voice}
purpose dictation (ASR accuracy checks), noise (must yield no text; the only
publishable purpose) or voice (your own voice, for cloning and training;
needs your consent)
publish copy a noise sample into the repository's public store (testdata/samples)
merge join samples or chunks into one longer sample
voice an installed TTS voice, built from voice samples; not a sample itself
Reference: docs/SampleStore.md

voxi voice clone [flags]

Install a voice sample as a cloned-voice profile

Copies one voice-purpose sample WAV from the private sample store to ~/.local/share/voxi/voices/<name>.wav and records it as tts_voice_reference_wav in ~/.config/voxi/config.yaml for a cloned-voice engine. Only clone your own voice.

--name

voice profile name used for the installed WAV (default: cloned)

--sample

voice sample id to clone (required when more than one voice sample exists)

--store

private sample store root; only voice-purpose samples are used (default: /home/uwe/.local/share/voxi/samples)

voxi voice prepare [flags]

Convert local speech samples to a Piper training dataset

--output-dir

directory for the generated LJSpeech dataset (default: /home/uwe/.local/share/voxi/voice-training/dataset)

--store

private sample store root; only voice-purpose samples are used (default: /home/uwe/.local/share/voxi/samples)

voxi voice train [flags]

Fine-tune and install a custom Piper voice

Prepare voice-purpose samples from the private sample store, fine-tune a Piper medium checkpoint, export ONNX, and install the voice under ~/.local/share/voxi/voices/.

--accelerator

training accelerator: cpu or gpu (default: cpu)

--base

local medium checkpoint path or checkpoint URL (default: https://huggingface.co/datasets/rhasspy/piper-checkpoints/resolve/main/en/en_US/lessac/medium/epoch%3D2164-step%3D1355540.ckpt)

--batch-size

Piper training batch size (default: 16)

--dataset-dir

prepared LJSpeech dataset directory (default: /home/uwe/.local/share/voxi/voice-training/dataset)

--epochs

training epoch limit (default: 100)

--espeak-voice

espeak-ng language voice, for example en-us (default: en-us)

--name

voice name used for the installed ONNX files

--store

private sample store root; only voice-purpose samples are used (default: /home/uwe/.local/share/voxi/samples)

--work-dir

training logs, checkpoints, and exported model directory (default: /home/uwe/.local/share/voxi/voice-training/runs)