Guides: install and run

Native packages for Debian 12+ and derivatives (Ubuntu 24.04+, Mint 22+…), Fedora, openSUSE Leap and Arch Linux. There are two installation paths; pick one per machine.

# Debian 12+, Ubuntu 24.04+, Mint 22+...
sudo apt install ./vosk-cli-dictation_0.5.4~beta_all.deb

# Fedora
sudo dnf install ./vosk-cli-dictation-0.5.4~beta-1.fc42.noarch.rpm

# openSUSE Leap
sudo zypper install ./vosk-cli-dictation-0.5.4~beta-1.leap156.noarch.rpm

# Arch Linux
sudo pacman -U ./vosk-cli-dictation-0.5.4_beta-1-any.pkg.tar.zst

git clone https://github.com/RonanDavalan/vosk-cli-dictation.git
cd vosk-cli-dictation
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

Dictation languages

Four languages ship: English, French, German and Spanish. The active one is chosen by --lang, otherwise the operating system language, otherwise default_model in the configuration file.

vosk-cli-dictation --lang fr

Each language needs its Vosk acoustic model unzipped under ~/.local/share/vosk-models/ (package) or vosk-model/ (checkout).

The command can download a language’s small model and check it against a known hash:

vosk-cli-dictation --download-model en

On the first run with no model at all, it offers the same download.

Driving a session

Start and stop by voice with a two-word phrase, per language:

Between start and stop, speech is typed into whichever window has focus. Punctuation and newlines are spoken as well (comma, new line, …); the full per-language list is printed at startup.

The same actions exist as subcommands, meant to be bound to a desktop keyboard shortcut — the supported path under Wayland:

vosk-cli-dictation --toggle        # start or pause
vosk-cli-dictation --finalize      # stop and copy the text
vosk-cli-dictation --sleep-toggle  # release the microphone / resume

vosk-cli-dictation --diagnose reports the session type, injection backend, audio device and model status, then exits.

Trigger modes

The start/stop gesture depends on interaction.mode in the configuration file. Default toggle (above): one gesture starts, a separate gesture stops. Two other modes: maintenue — push-to-talk, dictation lasts exactly as long as the hotkeys.push_to_talk key (default Ctrl_R) is held down; silence — a single gesture starts the session, which stops and copies itself once interaction.silence_timeout_ms (default 700 ms) passes with no further speech. In every mode, the spoken stop phrase and --finalize keep working as a safety net.

Wayland and X11

Text is injected through the clipboard, so it needs both a keystroke tool and a clipboard tool: wtype + wl-clipboard under Wayland, xdotool + xclip under X11, with ydotool as a driver-level keystroke fallback (wl-clipboard is still required). The native packages pull these in; a source install adds them itself. Without a clipboard tool the paste re-inserts the last thing copied by hand. ydotool, when it is the fallback, needs the ydotoold daemon and membership of the input group (log out and back in after adding it). Global Alt hotkeys reach X11 and XWayland windows only; on Wayland, bind the subcommands above to your desktop’s own shortcut settings for every window.

Full reference

Every configuration key, the model-path cascade and the control socket are documented in the project’s docs/: configuration.md and the vosk-cli-dictation(1) manpage, both in the four languages. See Understand for how the pieces fit together.