CLI Usage & Automation
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
MacParakeet provides a first-class Command Line Interface (macparakeet-cli) designed as a canonical automation surface for Apple Silicon. While the project includes a SwiftUI macOS application, the CLI serves as the foundation, allowing AI agents, headless Mac mini deployments, and developer scripts to interact with the underlying MacParakeetCore library. The CLI is intentionally designed for automation rather than as a mere GUI mirror, focusing on high-throughput transcription, historical search, and integration with Large Language Model (LLM) providers.
Sources: AGENTS.md:12-16, integrations/README.md:10-14, plans/active/cli-as-canonical-parakeet-surface.md:20-24
The tool utilizes Semantic Versioning (SemVer) and maintains a stable public contract, specifically for JSON outputs and error handling. This allows external tools like OpenClaw and Hermes Agent to reliably shell out to MacParakeet for local speech-to-text (STT) processing on the Apple Neural Engine (ANE).
Sources: plans/active/cli-as-canonical-parakeet-surface.md:135-139, integrations/README.md:21-25
Architecture and Integration Flow
The macparakeet-cli acts as a consumer of MacParakeetCore, which handles the heavy lifting of STT pipelines, database persistence via SQLite, and LLM integrations.
System Hierarchy
The following diagram illustrates how the CLI sits within the overall project architecture:
The CLI is the load-bearing surface for automated clients, while the GUI is a separate consumer of the same core logic and local database.
Sources: plans/active/cli-as-canonical-parakeet-surface.md:95-115, AGENTS.md:12-16
Data Flow for Transcription
When an automation request is made, the CLI follows a deterministic path to process audio and return structured results.
Automation Capabilities
The CLI exposes several key subcommands designed for headless environments. Unlike the GUI, the CLI does not handle interactive dictation or live recording; it focuses on processing existing files, URLs, and historical data.
Core Automation Surfaces
| Category | Subcommands | Purpose |
|---|---|---|
| Transcription | transcribe, export | Process local files, media URLs, or podcasts into multiple formats (JSON, TXT, SRT, VTT). |
| History & Search | history, search | Query prior dictations and transcriptions stored in the shared SQLite database. |
| Intelligence | prompts, llm | Run prompt library templates against transcripts via LLM providers (Anthropic, OpenAI, etc.). |
| System Health | health, spec | Probe model readiness, database accessibility, and binary dependencies (FFmpeg, yt-dlp). |
| Configuration | config, models | Manage shared preferences and select speech-to-text models (Parakeet v2/v3, Nemotron, Whisper). |
Sources: integrations/README.md:16-52, integrations/README.md:105-130, plans/completed/2026-06-19-boundary-contracts.md:65-70
Machine-Readable Contracts
For reliable automation, the CLI provides two primary output modes:
--jsonFlag: Used for read-only query commands (e.g.,health,history,prompts list).--format jsonOption: Used for commands that output content in multiple formats (e.g.,transcribe,export,meetings transcript).
Sources: integrations/README.md:275-280, plans/completed/2026-06-19-boundary-contracts.md:65-70
Configuration and Models
The CLI allows agents to manage the speech recognition stack and application-wide settings. These settings are shared with the GUI via the com.macparakeet.MacParakeet preference suite.
Model Selection
Users can explicitly download and select specific STT models:
- Parakeet v3: Multilingual default.
- Parakeet v2: English-only optimized.
- Nemotron / WhisperKit: Optional engines requiring separate local downloads.
macparakeet-cli models download whisper-large-v3-v20240930-turbo-632MB
macparakeet-cli models select whisper-large-v3-v20240930-turbo-632MB --json
Sources: integrations/README.md:135-155, integrations/README.md:325-330
Exit Codes and Error Handling
The CLI uses standard exit codes to signal success or failure types, enabling deterministic branching in scripts.
| Exit Code | Meaning | Context |
|---|---|---|
| 0 | Success | Work completed normally. |
| 1 | Runtime Failure | Work attempted but failed (e.g., LLM error, DB error, STT failure). |
| 2 | Validation / Misuse | Malformed invocation (e.g., unknown flag, missing required argument). |
| 130 | SIGINT | Process interrupted by user. |
Sources: integrations/README.md:365-370, plans/completed/2026-06-19-boundary-contracts.md:135-140
Agent Skill Integration
The CLI is specifically designed to be wrapped as a "skill" for agents like OpenClaw or Hermes. A typical integration includes a SKILL.md (or similar) file that describes the CLI's capabilities to the agent.
Integration Principles
- Health Checks: Agents should run
macparakeet-cli health --jsonat initialization to verify binary dependencies likeffmpegandyt-dlp. - Environment Variables: API keys for LLM providers should be passed via environment variables (e.g.,
ANTHROPIC_API_KEY) rather than literal flags to avoid exposure in process listings. - Privacy Posture: All STT and database operations are strictly local. Network egress only occurs for explicit model repairs, media URL downloads, or optional LLM calls.
Sources: integrations/README.md:225-265, integrations/README.md:285-295, AGENTS.md:75-78
Typical Command Usage for Agents
# Transcribe with app-selected defaults
macparakeet-cli transcribe /path/to/audio.mp3 --engine app-default --format json
# Search meeting recordings
macparakeet-cli meetings search "architecture" --json
# Run an AI summary on a transcription
macparakeet-cli prompts run "Summary" --transcription <id> --provider anthropic --json
Sources: integrations/README.md:165-180, integrations/README.md:200-215
Summary
The macparakeet-cli transforms MacParakeet from a desktop utility into a powerful automation engine for Apple Silicon. By providing stable JSON contracts, deterministic exit codes, and comprehensive health probing, it enables a "headless" workflow where speech-to-text serves as a local, private infrastructure layer for AI agents and developer toolchains. This local-first posture on the Apple Neural Engine ensures high performance without the privacy risks or costs associated with cloud-based transcription services.