| name | macparakeet-stt |
| description | Use when the user asks to transcribe audio or video, inspect or manage MacParakeet meeting recordings, search prior dictations/transcripts, or give an AI agent local speech-to-text tools on Apple Silicon. |
MacParakeet STT
Use macparakeet-cli for local-first speech-to-text and meeting artifact
management on macOS Apple Silicon. STT and database access are local. Do not
send audio or transcripts to an LLM unless the user explicitly asks for an
LLM-backed prompt/summary and provides or has configured a provider.
Startup Check
Run this before real work:
macparakeet-cli health --json
If it fails, report the errorType/message and stop. Do not guess that models,
FFmpeg, yt-dlp, or the database are ready. App-bundled CLI installs should
already have a signed yt-dlp helper seed; if yt-dlp is still missing and the
user wants media URL transcription, run
macparakeet-cli health --repair-binaries before retrying.
If database.status is schema_skew, the shared database was migrated by a
newer MacParakeet app than this CLI build understands. Tell the user to
upgrade macparakeet-cli, then stop; do not treat it as a database fault.
Core Commands
macparakeet-cli spec --json
macparakeet-cli transcribe "<path-or-media-url>" --format json
macparakeet-cli transcribe "<path-or-media-url>" --format transcript --no-history
macparakeet-cli models download whisper-large-v3-v20240930-turbo-632MB
macparakeet-cli models download cohere-transcribe
macparakeet-cli models list --json
macparakeet-cli models select parakeet-v3 --json
macparakeet-cli config set parakeet-model v3 --json
macparakeet-cli transcribe "<path-or-media-url>" --engine whisper --language ko --format json
macparakeet-cli transcribe "<path-or-media-url>" --engine cohere --language ja --format json
macparakeet-cli transcribe "<path-or-media-url>" \
--engine app-default \
--parakeet-model app-default \
--speaker-detection app-default \
--mode app-default \
--downloaded-audio app-default \
--media-audio-quality app-default \
--format json
macparakeet-cli config list --json
macparakeet-cli config set speech-engine parakeet --json
macparakeet-cli config set speaker-detection off --json
macparakeet-cli config set meeting-speaker-detection off --json
macparakeet-cli history transcriptions --json
macparakeet-cli history search-transcriptions "<query>" --json
macparakeet-cli history search "<query>" --json
macparakeet-cli meetings list --json
macparakeet-cli meetings show "<id-or-prefix-or-title>" --json
macparakeet-cli meetings transcript "<id-or-prefix-or-title>" --format json
macparakeet-cli meetings notes append "<id-or-prefix-or-title>" --text "<note>" --json
macparakeet-cli meetings results add "<id-or-prefix-or-title>" --name "Agent Notes" --stdin --json
macparakeet-cli meetings export "<id-or-prefix-or-title>" --format md --stdout
macparakeet-cli meetings export "<id-or-prefix-or-title>" --stdout --format json
Use meetings commands for Granola-style deterministic workflows: list
recordings, read transcripts, update notes, and export artifacts. These do not
summarize and do not require an LLM provider.
Only use prompt/LLM commands when the user asks for generated output:
macparakeet-cli prompts list --json
macparakeet-cli prompts run "<prompt-name>" \
--transcription "<id-or-prefix-or-title>" \
--provider "<provider>" --api-key-env "PROVIDER_API_KEY" --model "<model>" \
--json
Operating Rules
- Branch on process exit code first.
- Parse stdout as JSON for
--json commands and for format-selecting commands
when the command's documented JSON mode sends the payload to stdout. For
meetings export, that mode is --stdout --format json; --format json
without --stdout writes a JSON file and prints the path.
- Treat exit code
2 as invocation misuse; fix the command before retrying.
- Treat lookup ambiguity as normal; ask for or choose a more specific ID.
- Never delete user database records unless the user explicitly requests it.
- Prefer meeting ID or UUID prefix over title when mutating notes.
- Keep API keys in environment variables; do not put literal keys in commands.
- Use the full app-default group (
--engine app-default,
--parakeet-model app-default, --speaker-detection app-default,
--mode app-default, --downloaded-audio app-default, and
--media-audio-quality app-default) when you are intentionally checking
GUI-default behavior. Pin explicit flags for reproducible agent tests.
config get speaker-detection reports the saved file/URL app-default value,
which is on for a fresh preference store. config get meeting-speaker-detection reports the saved meeting app-default value, also
defaulting to on. Bare transcribe uses the file/URL value; meeting
retranscription uses the meeting value when --speaker-detection is left at
app-default. Pass --speaker-detection on or off to override it for one
run. For known speaker counts, use per-run --speaker-count,
--speaker-min, or --speaker-max instead of mutating the saved default.
