CLI

CLI

The Linux build exposes two typewhisper command-line interfaces:

• The control commands built into the main app binary — they drive the running instance over its Unix control socket (start/stop dictation, query state). See Desktop integration.
• The API client — a separate typewhisper binary that talks to the local HTTP API to check status, list models, and transcribe audio from scripts.

App control commands

Run from the main app's typewhisper entry point. With no instance running, the bare command launches the GUI; with one running it hands the command off over the control socket.

Command	Description
typewhisper	Launch the GUI, or toggle dictation if the app is already running.
typewhisper record start	Start dictation (idempotent).
typewhisper record stop	Stop dictation and transcribe (idempotent).
typewhisper record toggle	Start if idle, stop otherwise.
typewhisper record cancel	Drop in-flight audio with no transcription.
typewhisper status	Print the control-socket state as JSON.
typewhisper --minimized	Launch the GUI minimized to the tray.
typewhisper --help	Show usage.

These map cleanly to compositor key binds (Hyprland, Sway) — see Global hotkeys and Desktop integration.

API client

The API client talks to the local API, so make sure the API is enabled on the General settings page first.

Installing

Install the client from the General settings page. The installer writes a launcher shell script to ~/.local/bin/typewhisper (the directory on your PATH); that script execs the actual binary payload, which lives under ~/.local/share/TypeWhisper/Cli/.

Note: the released packages do not currently bundle the CLI binary. In those builds the General settings panel reports "CLI binary not found in this build" and the Install button is hidden rather than shown greyed out — there is nothing to install. To use the CLI today, build from source; the panel's Refresh button picks the binary up once it's present. Shipping the CLI in every release format is tracked separately.

When the app is running it publishes its port and bearer token to ~/.config/typewhisper/api-discovery.json, and the client auto-discovers both from there. You therefore usually do not need to pass --port or --token while the app is running. See HTTP API.

Commands

Command	Description
typewhisper status	Show app status and active model.
typewhisper models	List available models.
typewhisper transcribe <file|->	Transcribe an audio file. Use - to read WAV bytes from stdin.

Options for transcribe

Option	Description
--language <code>	Force a transcription language.
--language-hint <code>	Hint to bias language detection (repeatable).
--task transcribe|translate	Transcribe in the source language, or translate.
--translate-to <code>	Target language when translating.
--response-format json|verbose_json	Response shape; verbose_json adds per-segment timing.
--prompt <text>	Prompt/context passed to the engine.
--engine <id>	Override the transcription engine.
--model <id>	Override the model.
--await-download	Wait while the active engine restores or downloads its model before transcribing.

Uploads are capped at 100 MB. A transcribe request times out after 5 minutes, or 15 minutes when --await-download is given.

Global options

Option	Description
--port <N>	Port to connect to. Defaults to 9876; auto-discovered when the app is running.
--token <token>	Bearer token (alias: --api-token). You can also set TYPEWHISPER_API_TOKEN. Auto-discovered when the app is running.
--json	Emit machine-readable JSON output.
--version	Print the client version.
--help	Show usage.

Examples

typewhisper status --token "$TYPEWHISPER_API_TOKEN"
typewhisper transcribe recording.wav --language de --json
typewhisper transcribe recording.wav --engine groq --model whisper-large-v3-turbo
typewhisper transcribe - < audio.wav

Related pages

• HTTP API — the endpoints the API client calls and their request fields.
• General settings — enable the API and install the CLI.
• Desktop integration — how the app-control commands reach a running instance over the control socket.

---

Changelog

Date	Change
2026-06-17	Initial version.
2026-06-17	Added app control commands, --api-token alias, auto-discovery, transcribe limits, and launcher/binary path clarification.
2026-07-27	v0.13.0: noted that released packages don't bundle the CLI binary, so the Install button is hidden in those builds.