MacWhisper Command-Line Tool

Using the MacWhisper Command-Line Tool

MacWhisper (13.20) ships with an optional command-line tool called mw  that lets you drive the app from Terminal — list and switch models, transcribe files, pipe results into other programs, and automate transcription from scripts.

The CLI talks to the running MacWhisper app over a local socket, so it uses the exact same engines, models, and settings you've configured in the UI. If MacWhisper isn't running when you invoke mw  , the CLI will launch it for you automatically.

1. Installing the CLI

1. Open MacWhisper → Settings → Advanced.
2. Under Command-Line Tool, click Install.
3. MacWhisper will place the mw   binary at /usr/local/bin/mw  . macOS may ask for your password the first time — this is required to write into /usr/local/bin  .
4. When the install is complete, the pane shows a green checkmark: "installed at /usr/local/bin/mw".

To remove it later, return to the same pane and click Uninstall.

Verify the install

Open a new Terminal window and run:

$ mw version
MacWhisper 13.19.2 (1409)

If you see a version number, you're ready to go. If your shell can't find mw  , make sure /usr/local/bin   is on your PATH   (it is by default on macOS).

2. Commands at a glance

mw   on its own prints a help summary. Add --help   to any subcommand for detailed options (mw transcribe --help  ).

3. Working with models

List installed models

$ mw models list
  ID                                        NAME                      SIZE
  whisper-cpp:ggml-tiny.en                  Tiny (English Only)       80 MB
  whisperkit:openai_whisper-small           Small                     483 MB
▸ parakeet-pro:nvidia_parakeet-v2_476MB     Parakeet v2 (476MB)       476 MB
  apple:en-GB                               English (United Kingdom)  -

• The ▸   marker shows the currently selected model.
• The ID column (e.g. whisperkit:openai_whisper-small  ) is what you pass to --model   or mw models select  .
• apple:<locale>   entries are Apple's on-device speech models provided by macOS 26+. Their size shows -   because the OS manages storage for them.

Switch the active model

$ mw models select whisperkit:openai_whisper-small
Selected: whisperkit:openai_whisper-small (Small)

The change applies immediately to both the CLI and the MacWhisper UI. If the model isn't installed, the command fails with a clear error — download it from the MacWhisper UI first.

4. Transcribing files

The simplest case — print a transcript to stdout:

$ mw transcribe ~/Desktop/meeting.m4a
Hello everyone, welcome to the meeting...

By default, transcriptions are transient — they are returned to the terminal and then discarded. They do not show up in your MacWhisper history unless you ask.

Useful flags

• --model <engine>:<model-id>  — override the active model just for this run.mw transcribe --model apple:en-GB talk.wav  
• --persist  — save the transcription into MacWhisper's history (same as a regular in-app transcription).
• --stream  — print segments as soon as they finalize, instead of waiting for the whole file. Works best with local engines (WhisperKit, ParakeetKit, Apple speech). Cloud engines (OpenAI, Groq, Deepgram, ElevenLabs, MacWhisper AI) only return one final result, so --stream   has no effect for them.

Progress output

When stderr is a terminal, mw transcribe   renders a live Transcribing: 47%   progress line on stderr. The actual transcript goes to stdout, so redirection stays clean:

mw transcribe foo.m4a > transcript.txt          # transcript.txt contains ONLY the transcript
mw transcribe foo.m4a | grep "hello"            # grep sees only transcript lines
mw transcribe foo.m4a 2>/dev/null               # suppress progress when scripting
mw transcribe foo.m4a > out.txt 2>&1            # capture both, if you want progress too

You can interrupt a transcription at any time with Ctrl+C.

5. Cool things to do with it

Transcribe and copy to clipboard

mw transcribe meeting.m4a | pbcopy

Transcribe every recording in a folder

for f in ~/Recordings/*.m4a; do
    mw transcribe "$f" > "${f%.m4a}.txt"
done

Word count of a call

mw transcribe call.m4a | wc -w

Find every mention of a name across a folder of recordings

for f in *.m4a; do
    echo "=== $f ==="
    mw transcribe "$f" 2>/dev/null | grep -i "acme corp"
done

Transcribe and summarise with a local LLM

mw transcribe interview.m4a | ollama run llama3 "Summarise the key points:"

Live-pipe a long file into a note

Using --stream  , you'll see transcript lines appear in the target file as they're produced:

mw transcribe --stream lecture.m4a | tee lecture.txt

One-off transcription with a different model without changing your default

mw transcribe --model whisperkit:openai_whisper-small quick-note.m4a

Save a proper entry into MacWhisper history from a script

mw transcribe --persist ~/Recordings/meeting.m4a > /dev/null

The transcription appears in the MacWhisper window like a normal import.

6. Troubleshooting

• mw: command not found  — the /usr/local/bin   directory isn't on your PATH  . Open a new Terminal window, or add export PATH="/usr/local/bin:$PATH"   to your shell profile.
• "File not found" — mw transcribe   resolves ~   and relative paths against your current directory. Double-check the path, or drag the file into Terminal to paste its absolute path.
• CLI hangs or can't reach the app — quit and relaunch MacWhisper, then try mw version  . The CLI auto-launches MacWhisper if it's not running (5-second timeout).
• A model ID isn't recognised — run mw models list   to see the exact IDs you can use, and make sure the model has been downloaded from MacWhisper's UI first.
• Progress line clutters a log file — add 2>/dev/null   to suppress it, or 2>&1   to capture it alongside stdout.

7. Uninstalling

Open MacWhisper → Settings → Advanced → Command-Line Tool and click Uninstall. MacWhisper will remove the binary from /usr/local/bin/mw  .