CLI Tool
Ein shell-freundliches Kommandozeilen-Tool, das sich für Transkription und portable Einstellungs-Backups mit dem lokalen TypeWhisper-API-Server verbindet.
Installation
Installiere die CLI über die TypeWhisper-App: Einstellungen > Erweitert > CLI Tool > Installieren. Dies platziert die typewhisper Binary unter /usr/local/bin/typewhisper.
Die TypeWhisper-App muss mit aktiviertem API-Server laufen. Die CLI erkennt den aktuellen Port und das Token automatisch über api-discovery.json.
Befehle
status
Prüfen, ob der API-Server läuft und welches Modell geladen ist.
typewhisper status
models
Alle verfügbaren Modelle und ihren Status auflisten.
typewhisper models
transcribe
Eine Audiodatei oder per Pipe eingegebenes Audio transkribieren.
typewhisper transcribe recording.wav
export
Alle unterstützten Einstellungen in eine JSON-Datei im TypeWhisper-Backupformat exportieren.
typewhisper export typewhisper-settings.json
import
Alle Kategorien eines TypeWhisper-Einstellungs-Backups importieren und eine Zusammenfassung übernommener und übersprungener Daten ausgeben.
typewhisper import typewhisper-settings.json
Große Dateien
Wenn du einen lokalen Dateipfad übergibst, reicht die CLI den Pfad an die laufende TypeWhisper-App weiter, statt die Dateibytes hochzuladen. Dadurch gilt das HTTP-Upload-Limit nicht für große Aufnahmen.
Per Pipe übergebenes stdin nutzt weiterhin den Upload-Endpunkt /v1/transcribe und ist auf 256 MiB begrenzt. Größere stdin-Uploads liefern 413 Payload Too Large.
Einstellungs-Backups und Dotfiles
export und import verwenden dasselbe JSON-Schema wie Einstellungen > Erweitert > Backup & Restore. Relative Pfade beziehen sich auf das aktuelle Verzeichnis, ~ wird aufgelöst und Exporte werden atomar geschrieben. Mit --json erhältst du eine maschinenlesbare Exportbestätigung oder Importantwort.
mkdir -p ~/.config/typewhisper
typewhisper export ~/.config/typewhisper/settings.json
typewhisper import ~/.config/typewhisper/settings.json
typewhisper import ~/.config/typewhisper/settings.json --json
Der Import führt Daten mit dem Ziel-Mac zusammen, statt ihn vorher zu leeren. Workflows und Profile werden angehängt, Duplikate und nicht verfügbare Plugins können übersprungen werden, belegte Hotkey-Slots bleiben erhalten und alter Verlauf kann durch die Aufbewahrungsregel des Ziel-Macs ausgelassen werden.
Backups können Transkriptionsverlauf, Prompts, App- und Website-Regeln sowie weitere persönliche Konfiguration enthalten. Prüfe ein Backup, bevor du es in ein Dotfiles-Repository eincheckst. Die CLI liest $XDG_CONFIG_HOME/typewhisper/config.toml nicht automatisch.
Optionen
| Flag | Beschreibung |
|---|---|
--port | Den automatisch erkannten API-Server-Port überschreiben |
--api-token | Das erkannte Bearer-Token überschreiben; TYPEWHISPER_API_TOKEN bietet dieselbe Möglichkeit |
--dev | Die Discovery-Datei von TypeWhisper-Dev statt der Release-App verwenden |
--json | Maschinenlesbares JSON ausgeben |
--help / -h / --version | Befehlshilfe oder installierte CLI-Version anzeigen |
--language | ISO 639-1-Sprachcode (z.B. en, de) |
--language-hint | Wiederholbare, geordnete Sprachauswahl; nicht mit --language kombinierbar |
--task | transcribe (Standard) oder Sprache mit WhisperKit über translate ins Englische übersetzen |
--translate-to | Einen Apple-Translate-Schritt für die Zielsprache ausführen (z.B. de, fr; macOS 15+) |
--engine | Die Transkriptions-Engine für diesen Request überschreiben |
--model | Das Transkriptionsmodell für diesen Request überschreiben |
--await-download | Auf Wiederherstellung oder Modelldownload einer lokalen Engine warten, statt 409 zurückzugeben |
--no-corrections | Rohe Engine-Ausgabe ohne nachträgliche Wörterbuchkorrekturen zurückgeben |
Beispiele
Datei transkribieren:
typewhisper transcribe meeting.m4a
Audio von stdin einlesen:
ffmpeg -i video.mp4 -f wav - | typewhisper transcribe -
JSON-Ausgabe mit jq:
typewhisper transcribe --json recording.wav | jq .text
Ins Deutsche übersetzen:
typewhisper transcribe --translate-to de recording.wav
Benutzerdefinierten Port verwenden:
typewhisper --port 9000 status
Ein portables Backup in ein Dotfiles-Verzeichnis exportieren:
mkdir -p ~/.config/typewhisper
typewhisper export ~/.config/typewhisper/settings.json
Ein Backup wiederherstellen und eine maschinenlesbare Zusammenfassung erhalten:
typewhisper import settings.json --json