CLI Tool
A shell-friendly command-line tool that connects to the local TypeWhisper API server for transcription and portable settings backups.
Installation
Install the CLI from the TypeWhisper app: Settings > Advanced > CLI Tool > Install. This places the typewhisper binary at /usr/local/bin/typewhisper.
The TypeWhisper app must be running with the API server enabled. The CLI automatically discovers the current port and token from api-discovery.json.
Commands
status
Check if the API server is running and which model is loaded.
typewhisper status
models
List all available models and their status.
typewhisper models
transcribe
Transcribe an audio file or piped audio input.
typewhisper transcribe recording.wav
export
Export all supported settings to a TypeWhisper Settings Backup JSON file.
typewhisper export typewhisper-settings.json
import
Import every category in a TypeWhisper Settings Backup file and print a merge/skip summary.
typewhisper import typewhisper-settings.json
Large files
When you pass a local file path, the CLI hands the path to the running TypeWhisper app instead of uploading the file bytes. This avoids the HTTP upload body limit for large recordings.
Piped stdin still uses the /v1/transcribe upload endpoint and is limited to 256 MiB. Larger stdin uploads return 413 Payload Too Large.
Settings backup and dotfiles
export and import use the same JSON schema as Settings > Advanced > Backup & Restore. Relative paths resolve from the current directory, ~ is expanded, and exports are written atomically. Add --json for a machine-readable export receipt or import result.
mkdir -p ~/.config/typewhisper
typewhisper export ~/.config/typewhisper/settings.json
typewhisper import ~/.config/typewhisper/settings.json
typewhisper import ~/.config/typewhisper/settings.json --json
Import merges into the destination Mac instead of clearing it first. Workflows and profiles are appended, duplicates and unavailable plugins can be skipped, occupied hotkey slots are preserved, and old history can be excluded by the destination retention policy.
Backups can contain transcription history, prompts, app/website rules, and other personal configuration. Review a backup before committing it to a dotfiles repository. The CLI does not automatically read $XDG_CONFIG_HOME/typewhisper/config.toml.
Options
| Flag | Description |
|---|---|
--port | Override the automatically discovered API server port |
--api-token | Override the discovered Bearer token; TYPEWHISPER_API_TOKEN provides the same override |
--dev | Connect to the TypeWhisper-Dev discovery file instead of the release app |
--json | Output machine-readable JSON |
--help / -h / --version | Show command help or the installed CLI version |
--language | ISO 639-1 language code (e.g., en, de) |
--language-hint | Repeatable ordered language shortlist; cannot be combined with --language |
--task | transcribe (default) or translate speech to English with WhisperKit |
--translate-to | Run an Apple Translate step for the target language (e.g., de, fr; macOS 15+) |
--engine | Override the transcription engine for this request |
--model | Override the transcription model for this request |
--await-download | Wait for a local engine to restore or download its model instead of returning 409 |
--no-corrections | Return raw engine output without post-transcription Dictionary Corrections |
Examples
Transcribe a file:
typewhisper transcribe meeting.m4a
Pipe audio from stdin:
ffmpeg -i video.mp4 -f wav - | typewhisper transcribe -
JSON output with jq:
typewhisper transcribe --json recording.wav | jq .text
Translate to German:
typewhisper transcribe --translate-to de recording.wav
Use a custom port:
typewhisper --port 9000 status
Export a portable backup to a dotfiles directory:
mkdir -p ~/.config/typewhisper
typewhisper export ~/.config/typewhisper/settings.json
Restore a backup and receive a machine-readable summary:
typewhisper import settings.json --json