The MacWhisper CLI: install mw, transcribe from Terminal, and every flag
By Ryleigh Newman · Published
MacWhisper ships with a command line tool called mw. It drives the app from Terminal: transcribe files and whole folders, detect speakers, write subtitles or JSON, and list or switch models. It talks to the running MacWhisper app over a local socket, so it uses the engines, models and settings you already set up, and it launches the app if it is not open.
I built YapToText, a different Mac app for dictation and file transcription, so read what I say about MacWhisper with that in mind. Every fact about MacWhisper here comes from its help article MacWhisper Command-Line Tool, read on October 10, 2026.
This app is completely free. You don't have to make an account. There are no subscriptions, no difficult downloads, and nothing is locked. Made for Apple silicon Macs. Source on GitHub.
This guide in other languages: العربية, Čeština, Dansk, Deutsch, Ελληνικά, Español, Suomi, Français, עברית, हिन्दी, Magyar, Bahasa Indonesia, Italiano, 日本語, 한국어, Norsk, Nederlands, Polski, Português, Română, Русский, Slovenčina, Svenska, ไทย, Türkçe, Українська, Tiếng Việt, 简体中文, 繁體中文
Install mw
- Open MacWhisper, then Settings, then Advanced.
- Under Command-Line Tool, click Install.
- Enter your Mac password if macOS asks. It is needed to write into /usr/local/bin.
- Open a new Terminal window and run mw version.
The tool lands at /usr/local/bin/mw, and the settings pane shows a green checkmark when it is done. If mw version prints a version number, it works. To remove it, return to the same pane and click Uninstall.
Transcribe a file
mw transcribe ~/Desktop/meeting.m4a
mw transcribe meeting.m4a > transcript.txt
mw transcribe meeting.m4a -o transcript.txt
mw transcribe meeting.m4a | pbcopyWhat happens: The transcript prints to standard output. A progress line goes to standard error, so a redirected file holds only the transcript.
By default a command line transcription is not kept. It is printed and discarded, and appears in MacWhisper's history only if you add --persist. Ctrl+C stops a run. An existing output file is never replaced unless you add --overwrite.
The commands
From MacWhisper's help article, read October 10, 2026. Add --help to any command for its options.
| Command | What it does |
|---|---|
| mw | A status overview: whether the app is reachable, the selected model, downloaded models, and example commands |
| mw version | Prints the MacWhisper version. Useful as a connection check |
| mw models list | Lists your installed transcription models, with an ID for each |
| mw models select | Changes the active model, in the command line tool and in the app |
| mw transcribe | Transcribes audio or video files, or whole folders, and prints the text |
Flags for mw transcribe
From the same article. A language the chosen model cannot transcribe fails with an error.
| Flag | What it does |
|---|---|
| --speakers, --no-speakers | Turns speaker detection on or off for this run. With it on, the transcript is grouped by speaker |
| --format | txt, the default, or srt, vtt, json, csv, md, html or avid |
| --style | transcript, subtitles or segments, the same styles as the app's Export panel |
| --model | Uses one model for this run without changing the app's selection |
| --language | An ISO code such as en or de, or auto, or multilingual |
| --output, -o | Writes the transcript to a file |
| --output-dir | Batch mode. Writes one transcript per input into a folder |
| --recursive | Includes subfolders when you pass a folder |
| --stream | Prints segments as they are finished. Local engines only |
| --persist | Keeps the transcription in MacWhisper's history |
| --timestamps, --milliseconds, --group, --max-chars-per-line, --fps | Fine-tune the layout |
Formats, and which need Pro
From the same article. The MacWhisper pricing page covers what Pro costs.
| Format | What you get | License |
|---|---|---|
| txt | Plain text | Everyone |
| srt | SubRip subtitles | Everyone |
| vtt | WebVTT subtitles | Everyone |
| csv | Rows of start, end and transcript, plus speaker when detected | Everyone |
| json | Millisecond timestamps, speakers per segment, and word timings | Pro |
| md | Markdown with timestamped blocks and speaker headings | Pro |
| html | A standalone HTML document | Pro |
| avid | Avid subtitle text with SMPTE timecodes | Pro |
Whole folders
mw transcribe ~/Recordings --recursive --output-dir ~/Transcripts
mw transcribe ~/Videos --output-dir ~/Subs --format srt
mw transcribe interview.m4a --speakers -o interview.txtWhat happens: Each input gets its own file, named after it, and the folder structure is mirrored. A file that fails is reported and skipped, and the run continues.
Speaker detection needs a model that supports it. The speaker recognition page covers that side of the app.
When it does not work
- mw: command not found. Open a new Terminal window, or add /usr/local/bin to your PATH.
- It hangs. Quit and reopen MacWhisper, then try mw version.
- A model ID is not recognized. Run mw models list for the exact IDs, and download the model in the app first.
- A Pro error on a format. json, md, html and avid need a Pro license.
- A sandbox error. A sandboxed program, including some AI coding tools, can be blocked from MacWhisper's socket. Run mw directly in Terminal.
The MacWhisper troubleshooting page covers the app itself.
Free routes from Terminal
YapToText has no command line tool. It transcribes a file you drop on it, one at a time, to plain text, free. If you want Terminal and nothing to buy, whisper.cpp is open source and is the engine YapToText is built on. The local Whisper guide has the commands, and the open source transcription page compares four free tools.
This app is completely free. You don't have to make an account. There are no subscriptions, no difficult downloads, and nothing is locked. Made for Apple silicon Macs. Source on GitHub.
The short version
- Install. Settings, Advanced, Command-Line Tool, Install.
- Run. mw transcribe, then a file or a folder.
- Free formats. txt, srt, vtt and csv.
- Pro formats. json, md, html and avid.
- History. Nothing is kept unless you add --persist.
If MacWhisper changes the tool and this page falls behind, open an issue on GitHub. Every one gets read.
This app is completely free. You don't have to make an account. There are no subscriptions, no difficult downloads, and nothing is locked. Made for Apple silicon Macs. Source on GitHub.
Related
Sources
- https://docs.macwhisper.com/article/57-macwhisper-command-line-tool (checked 2026-10-10)
- https://github.com/ryleighnewman/YapToText (checked 2026-10-10)
- https://apps.apple.com/us/app/yaptotext/id6786382289 (checked 2026-10-10)
Questions
Does MacWhisper have a command line tool?
Yes. It is called mw, and you install it from MacWhisper's Settings, under Advanced, Command-Line Tool.
How do I transcribe a file with MacWhisper from Terminal?
Run mw transcribe followed by the file path. The transcript prints to standard output, or to a file with -o.
Is the MacWhisper CLI free?
Its help article says txt, srt, vtt and csv output are available to everyone, and that json, md, html and avid need a Pro license.
Can the MacWhisper CLI transcribe a whole folder?
Yes. Pass a folder to mw transcribe, add --recursive for subfolders, and --output-dir to write one transcript per file.
Does mw need MacWhisper to be open?
It talks to the running app, and launches MacWhisper automatically if it is not open.