Windows

CLI Tool

Use TypeWhisper from PowerShell, scripts, and local automation.

On this page

Install and prepare

Open Settings > Advanced > Command line tool and click Install.
Open a new terminal afterward so the updated user PATH is loaded.
In Settings > Advanced > API server, turn on Enable HTTP API.
Verify the connection with typewhisper status.

powershell

typewhisper status

The CLI is a client for the local HTTP API. TypeWhisper must be running and the HTTP API must be enabled.

Without --port, the CLI reads api-discovery.json in the profile of the app that installed it, then the legacy api-port file, and finally falls back to 8978. A CLI without that binding checks %LOCALAPPDATA%\TypeWhisper-WinUI.

To reach another profile, such as the Microsoft Store edition's, pass its folder with --profile <directory> or set the TYPEWHISPER_PROFILE environment variable to it. The CLI then reads only the discovery files in that folder.

powershell

typewhisper status --profile "$env:LOCALAPPDATA\Packages\TypeWhisper.TypeWhisper_51tqb5623pxja\LocalCache\Local\TypeWhisper-WinUI"

The CLI uses the token from the discovery file only for the port listed there, and ignores it when discovery reports that no token is required. Priority is --api-token, the TYPEWHISPER_API_TOKEN environment variable, then discovery.

Commands

`status`

Shows API, engine, and model status.

powershell

typewhisper status

`models`

Lists the currently available local and cloud models. The ID and ENGINE columns hold the IDs for the commands below; an asterisk marks the selected model.

powershell

typewhisper models

`models load`

Load a model and select it for transcription. Take the engine and model IDs from typewhisper models. The command does not download anything, so a local model must already be downloaded. It waits until the model is loaded and then prints its status. Add --json for the API response.

powershell

typewhisper models load --engine sherpa-onnx --model parakeet-tdt-0.6b

output

ready: sherpa-onnx parakeet-tdt-0.6b

`models unload`

Unload an engine's model to free memory. Its downloaded files stay on your PC. The command needs only --engine; it accepts --model but ignores it. After you unload Parakeet, TypeWhisper has no model ready until you load one again.

powershell

typewhisper models unload --engine sherpa-onnx

output

unloaded: sherpa-onnx parakeet-tdt-0.6b

`models delete`

Delete the downloaded files of a model. This works for local engines whose plugin can remove model files, such as Parakeet and whisper.cpp; for cloud engines, TypeWhisper returns an error. TypeWhisper does not delete the model an engine has selected or may still have loaded.

powershell

typewhisper models delete --engine sherpa-onnx --model canary-180m-flash

output

deleted: sherpa-onnx canary-180m-flash

HTTP API: Load, unload, and delete models

`transcribe <file|->`

Transcribes a local file path or raw audio from stdin.

shell

typewhisper transcribe meeting.m4a
typewhisper transcribe - < audio.wav

Global flags

Flag	Description
`--port <N>`	Override the port; otherwise try CLI discovery, then fallback 8978
`--profile <directory>`	Read the discovery files from this profile folder; overrides the TYPEWHISPER_PROFILE environment variable
`--api-token <token>`	Override the discovery and environment token
`--json`	Machine-readable JSON output
`--version`	Print the CLI version
`--help, -h`	Show help

transcribe flags

Flag	Description
`--language <code>`	Set one exact source language
`--language-hint <code>`	Repeatable ordered hint for auto-detection
`--task <task>`	transcribe or translate
`--translate-to <code>`	Translation target language
`--engine <id>`	Override the engine for this request
`--model <id>`	Override the model for this request
`--await-download`	Wait for a local model restore or download

--language and --language-hint cannot be combined. Repeat --language-hint for multiple hints in the desired order.

Model command flags

Flag	Description
`--engine <id>`	The engine to act on; always required
`--model <id>`	The model to act on; required for load and delete, ignored by unload

These flags apply to models load, models unload, and models delete. The flags of the same name for transcribe override the model for one request only.

Examples

powershell

typewhisper transcribe recording.wav --language de --json
typewhisper transcribe recording.wav --language-hint de --language-hint en
typewhisper transcribe recording.wav --engine <engine-id> --model <model-id>
typewhisper transcribe recording.wav --task translate --translate-to en
typewhisper transcribe recording.wav --await-download
typewhisper --port 9000 status

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:

powershell

typewhisper models
typewhisper models load --engine whisper-cpp --model large-v3-turbo
typewhisper transcribe interview.m4a
typewhisper models unload --engine whisper-cpp

HTTP API and authentication