CLI Reference

Macaw ships with an Ollama-style CLI for managing models, running the server, and transcribing audio. All commands are available via the macaw binary.

macaw --help

Commands

`macaw serve`

Start the API server and gRPC workers.

Basic usage

macaw serve

Custom host and port

macaw serve --host 0.0.0.0 --port 9000

Flag	Default	Description
`--host`	`127.0.0.1`	Bind address
`--port`	`8000`	HTTP port
`--models-dir`	`~/.macaw/models`	Models directory
`--cors-origins`	`*`	Allowed CORS origins
`--log-format`	`text`	Log format (`text` or `json`)
`--log-level`	`info`	Log level (`debug`, `info`, `warning`, `error`)

The server starts:

FastAPI HTTP server on the specified port
STT gRPC worker on port 50051
TTS gRPC worker on port 50052

Production

For production deployments, use structured logging and bind to all interfaces:

macaw serve --host 0.0.0.0 --log-format json --log-level info

`macaw transcribe`

Transcribe an audio file or stream from the microphone.

Transcribe a file

macaw transcribe recording.wav --model faster-whisper-large-v3

Stream from microphone

macaw transcribe --stream --model faster-whisper-large-v3

Flag	Short	Default	Description
`--model`	`-m`	—	Model to use (required)
`--format`		`json`	Output format (`json`, `text`, `verbose_json`, `srt`, `vtt`)
`--language`	`-l`	auto	Language code (e.g., `en`, `pt`)
`--no-itn`		—	Disable Inverse Text Normalization
`--hot-words`		—	Comma-separated hot words
`--stream`		—	Stream from microphone instead of file
`--server`		`http://localhost:8000`	Server URL (connects to running server)

File mode sends the audio to the REST API for batch transcription. Stream mode connects to the WebSocket endpoint for real-time transcription.

With hot words and language

macaw transcribe call.wav -m faster-whisper-large-v3 -l pt --hot-words "Macaw,OpenVoice"

Output as subtitles

macaw transcribe video.wav -m faster-whisper-large-v3 --format srt

`macaw translate`

Translate audio to English.

Translate Portuguese audio

macaw translate reuniao.wav --model faster-whisper-large-v3

Flag	Short	Default	Description
`--model`	`-m`	—	Model to use (required)
`--format`		`json`	Output format
`--no-itn`		—	Disable ITN
`--hot-words`		—	Comma-separated hot words
`--server`		`http://localhost:8000`	Server URL

English output only

Translation always produces English text, regardless of the source language. This matches the OpenAI API behavior.

`macaw list`

List installed models.

macaw list

NAME                        TYPE   ENGINE            SIZE
faster-whisper-large-v3     stt    faster-whisper    3.1 GB
kokoro                      tts    kokoro            982 MB
wenet-chinese               stt    wenet            1.2 GB

Flag	Default	Description
`--models-dir`	`~/.macaw/models`	Models directory to scan

`macaw inspect`

Show detailed information about a model.

macaw inspect faster-whisper-large-v3

Name:           faster-whisper-large-v3
Type:           stt
Engine:         faster-whisper
Architecture:   encoder-decoder
Size:           3.1 GB

Capabilities:
  Hot words:          false (via initial_prompt workaround)
  Initial prompt:     true
  Batch:              true
  Word timestamps:    true
  Max concurrent:     1

Engine Config:
  beam_size:          5
  vad_filter:         false
  compute_type:       float16
  device:             cuda

Flag	Default	Description
`--models-dir`	`~/.macaw/models`	Models directory

`macaw ps`

List models loaded on a running server.

macaw ps

NAME                        TYPE   ENGINE            STATUS
faster-whisper-large-v3     stt    faster-whisper    ready
kokoro                      tts    kokoro            ready

Flag	Default	Description
`--server`	`http://localhost:8000`	Server URL to query

This queries the GET /v1/models endpoint on the running server.

`macaw pull`

Download a model from HuggingFace Hub.

Download a model

macaw pull faster-whisper-large-v3

Force re-download

macaw pull faster-whisper-large-v3 --force

Flag	Default	Description
`--models-dir`	`~/.macaw/models`	Download destination
`--force`	—	Re-download even if already exists

`macaw remove`

Remove an installed model.

Remove with confirmation

macaw remove faster-whisper-large-v3

Skip confirmation

macaw remove faster-whisper-large-v3 --yes

Flag	Short	Default	Description
`--models-dir`		`~/.macaw/models`	Models directory
`--yes`	`-y`	—	Skip confirmation prompt

Typical Workflow

1. Install a model

macaw pull faster-whisper-large-v3

# 2. Verify it's installed
macaw list

# 3. Start the server
macaw serve

# 4. In another terminal — check loaded models
macaw ps

# 5. Transcribe a file
macaw transcribe audio.wav -m faster-whisper-large-v3

# 6. Stream from microphone
macaw transcribe --stream -m faster-whisper-large-v3

# 7. Translate foreign audio
macaw translate foreign.wav -m faster-whisper-large-v3

Environment Variables

CLI commands respect these environment variables:

Variable	Default	Description
`MACAW_MODELS_DIR`	`~/.macaw/models`	Default models directory
`MACAW_SERVER_URL`	`http://localhost:8000`	Default server URL for client commands
`MACAW_LOG_LEVEL`	`info`	Default log level
`MACAW_LOG_FORMAT`	`text`	Default log format

On this page