macOS

CLI Tool

A shell-friendly command-line tool that connects to the local TypeWhisper API server for transcription, model management, audio settings, and portable settings backups.

On this page

Installation

Install the CLI from the TypeWhisper app: Settings > Advanced > Command Line Tool > Install Command Line Tool. This places the typewhisper binary at /usr/local/bin/typewhisper.

Important

The TypeWhisper app must be running with the API server enabled. The CLI automatically discovers the current port and token from api-discovery.json.

Download a model if needed, load it, and select it for transcription. Take the engine and model IDs from typewhisper models. The command waits until the model is ready, which can take up to ten minutes for a download, and then prints its status. Add --json for the API response.

shell

typewhisper models load --engine parakeet --model parakeet-tdt-0.6b-v3

output

ready: parakeet parakeet-tdt-0.6b-v3

`models unload`

Available from TypeWhisper 1.8.

Unload the active model of an engine to free memory. Its downloaded files stay on your Mac. The command takes only --engine; with --model, it stops with an error.

shell

typewhisper models unload --engine parakeet

output

unloaded: parakeet parakeet-tdt-0.6b-v3

`models delete`

Available from TypeWhisper 1.8.

Delete the downloaded files of a model. This works only for engines that manage their own model downloads, such as WhisperKit. For other engines, such as Parakeet, TypeWhisper returns an error.

shell

typewhisper models delete --engine whisper --model openai_whisper-large-v3_turbo

output

deleted: whisper openai_whisper-large-v3_turbo

HTTP API: Load, unload, and delete models

`transcribe`

Transcribe an audio file or piped audio input.

shell

typewhisper transcribe recording.wav

`export`

Export all supported settings to a TypeWhisper Settings Backup JSON file.

shell

typewhisper export typewhisper-settings.json

`import`

Import every category in a TypeWhisper Settings Backup file and print a merge/skip summary.

shell

typewhisper import typewhisper-settings.json

`import --replace`

Available from TypeWhisper 1.8.

Import a backup like import, and also overwrite workflows, profiles, and prompt actions with the same name and the hotkey slots the backup contains. Use it to apply edits you made to an exported file. Nothing is deleted; profiles keep their priority and workflows their position. Add --json for the API response.

shell

typewhisper import typewhisper-settings.json --replace

output

Workflows: 0 imported, 1 updated, 7 skipped
Dictionary: 0 imported, 52 skipped
Snippets: 0 imported, 6 skipped
Prompt Actions: 0 imported, 0 updated, 2 skipped
Profiles: 0 imported, 0 updated, 2 skipped
Hotkeys: 1 applied, 7 skipped
Plugins: 0 installed, 2 skipped
History: 0 imported, 41 skipped as duplicates, 0 skipped by retention
Preferences: 27 applied
Update channel applied

HTTP API: Settings Backup: API and CLI

`audio`

Available from TypeWhisper 1.8.

Show the input the next recording uses, the microphone priority list, the connected inputs with their device IDs, and the audio ducking, media pause, and sound feedback settings. Add --json for the API response, for example to save it.

shell

typewhisper audio

output

Active input: MacBook Pro Microphone [BuiltInMicrophoneDevice]
Input priority:
  1. HyperX QuadCast 2 [AppleUSBAudioEngine:HyperX:QuadCast 2] (not connected)
Available inputs:
  MacBook Pro Microphone [BuiltInMicrophoneDevice] (system default)
  BlackHole 2ch [BlackHole2ch_UID]
Audio ducking: on (20% volume)
Pause media during recording: off
Sound feedback: on

`audio set`

Available from TypeWhisper 1.8.

Change audio settings with a JSON object from a file, or from stdin with -. As in the API, the object contains only the fields you want to change. The command then prints the new settings. While a dictation or Recorder recording is running or still being processed, TypeWhisper rejects the change.

shell

echo '{"input_priority":[{"id":"BlackHole2ch_UID"}]}' | typewhisper audio set -

HTTP API: Audio settings

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.

shell

mkdir -p ~/.config/typewhisper
typewhisper export ~/.config/typewhisper/settings.json
typewhisper import ~/.config/typewhisper/settings.json
typewhisper import ~/.config/typewhisper/settings.json --json
typewhisper import ~/.config/typewhisper/settings.json --replace

Import merges into the destination Mac instead of clearing it first and deletes nothing. Duplicate Dictionary entries and snippets and unavailable or installed plugins are skipped, occupied hotkey slots are preserved, and old history can be excluded by the destination retention policy. From TypeWhisper 1.8, workflows, profiles, prompt actions, and history entries that already exist unchanged are skipped as well, so importing a backup onto the Mac it came from duplicates nothing. Edited items are added as new ones unless you add --replace.

Important

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`	`transcribe`: override the transcription engine for this request. `models load`, `models unload`, and `models delete`: the engine to act on
`--model`	`transcribe`: override the transcription model for this request. `models load` and `models delete`: the model to act on
`--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
`--replace`	`import`: also overwrite workflows, profiles, and prompt actions with the same name and the hotkey slots in the backupAvailable from TypeWhisper 1.8.

Examples

Transcribe a file:

shell

typewhisper transcribe meeting.m4a

Pipe audio from stdin:

shell

ffmpeg -i video.mp4 -f wav - | typewhisper transcribe -

JSON output with jq:

shell

typewhisper transcribe --json recording.wav | jq .text

Translate to German:

shell

typewhisper transcribe --translate-to de recording.wav

Use a custom port:

shell

typewhisper --port 9000 status

Export a portable backup to a dotfiles directory:

shell

mkdir -p ~/.config/typewhisper
typewhisper export ~/.config/typewhisper/settings.json

Restore a backup and receive a machine-readable summary:

shell

typewhisper import settings.json --json

Available from TypeWhisper 1.8. Apply edits you made to that file, including changed hotkeys:

shell

typewhisper import ~/.config/typewhisper/settings.json --replace

Available from TypeWhisper 1.8. Switch to another model for one job and unload it afterwards to free memory. models load also makes it the selected model in TypeWhisper, so load your usual model again to switch back:

shell

typewhisper models
typewhisper models load --engine whisper \
  --model openai_whisper-large-v3_turbo
typewhisper transcribe interview.m4a > interview.txt
typewhisper models unload --engine whisper

Available from TypeWhisper 1.8. Record from BlackHole 2ch for a while and restore your audio settings afterwards:

shell

if typewhisper audio --json > audio-settings.json.tmp &&
  mv audio-settings.json.tmp audio-settings.json; then
  echo '{"input_priority":[{"id":"BlackHole2ch_UID"}],"audio_ducking_enabled":false}' |
    typewhisper audio set -
  printf '%s ' "Play speech into BlackHole 2ch, dictate it, then press Return to restore your settings."
  read -r _
  jq 'del(.input_devices, .active_input)' audio-settings.json |
    typewhisper audio set -
fi

CLI Tool

Installation

Commands

`status`

`models`

`models load`

`models unload`

`models delete`

`transcribe`

`export`

`import`

`import --replace`

`audio`

`audio set`

Large files

Settings backup and dotfiles

Options

Examples