---
icon: lucide/mic
---

# transcribe

Transcribe audio from your microphone to text.

## Usage

```bash
agent-cli transcribe [OPTIONS]
```

## Description

This command:

1. Starts listening to your microphone immediately
2. Records your speech
3. When you press `Ctrl+C`, stops recording and finalizes transcription (Wyoming streams live; OpenAI uploads after stop)
4. Copies the transcribed text to your clipboard
5. Optionally uses an LLM to clean up the transcript

## Examples

```bash
# Basic transcription
agent-cli transcribe --input-device-index 1

# With LLM cleanup
agent-cli transcribe --input-device-index 1 --llm

# List available audio devices
agent-cli transcribe --list-devices

# Transcribe from a saved file (supports wav, mp3, m4a, ogg, flac, aac, webm)
agent-cli transcribe --from-file recording.wav

# Transcribe an MP3 file with OpenAI
agent-cli transcribe --from-file podcast.mp3 --asr-provider openai

# Transcribe an M4A voice memo with Gemini
agent-cli transcribe --from-file voice_memo.m4a --asr-provider gemini

# Re-transcribe most recent recording
agent-cli transcribe --last-recording 1
```

## Supported Audio Formats

The `--from-file` option supports multiple audio formats:

| Provider | Supported Formats |
|----------|-------------------|
| OpenAI | mp3, mp4, mpeg, mpga, m4a, wav, webm |
| Gemini | wav, mp3, aiff, aac, ogg, flac, m4a |
| Wyoming | Any format (converted via ffmpeg) |

> [!NOTE]
> For non-WAV formats with the Wyoming provider, [ffmpeg](https://ffmpeg.org/) must be installed on your system.

## Options

<!-- CODE:START -->
<!-- from agent_cli.docs_gen import all_options_for_docs -->
<!-- print(all_options_for_docs("transcribe")) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
### LLM Configuration

| Option | Default | Description |
|--------|---------|-------------|
| `--extra-instructions` | - | Additional instructions for the LLM to process the transcription. |
| `--llm/--no-llm` | `false` | Use an LLM to process the transcript. |

### Audio Recovery

| Option | Default | Description |
|--------|---------|-------------|
| `--from-file` | - | Transcribe audio from a file (supports wav, mp3, m4a, ogg, flac, aac, webm). Requires ffmpeg for non-WAV formats with Wyoming provider. |
| `--last-recording` | `0` | Transcribe a saved recording. Use 1 for most recent, 2 for second-to-last, etc. Use 0 to disable (default). |
| `--save-recording/--no-save-recording` | `true` | Save the audio recording to disk for recovery. |

### Provider Selection

| Option | Default | Description |
|--------|---------|-------------|
| `--asr-provider` | `wyoming` | The ASR provider to use ('wyoming', 'openai', 'gemini'). |
| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). |

### Audio Input

| Option | Default | Description |
|--------|---------|-------------|
| `--input-device-index` | - | Index of the audio input device to use. |
| `--input-device-name` | - | Device name keywords for partial matching. |
| `--list-devices` | `false` | List available audio input and output devices and exit. |

### Audio Input: Wyoming

| Option | Default | Description |
|--------|---------|-------------|
| `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. |
| `--asr-wyoming-port` | `10300` | Wyoming ASR server port. |

### Audio Input: OpenAI-compatible

| Option | Default | Description |
|--------|---------|-------------|
| `--asr-openai-model` | `whisper-1` | The OpenAI model to use for ASR (transcription). |
| `--asr-openai-base-url` | - | Custom base URL for OpenAI-compatible ASR API (e.g., for custom Whisper server: http://localhost:9898). |
| `--asr-openai-prompt` | - | Custom prompt to guide transcription (optional). |

### Audio Input: Gemini

| Option | Default | Description |
|--------|---------|-------------|
| `--asr-gemini-model` | `gemini-3-flash-preview` | The Gemini model to use for ASR (transcription). |

### LLM: Ollama

| Option | Default | Description |
|--------|---------|-------------|
| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. |
| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. |

### LLM: OpenAI-compatible

| Option | Default | Description |
|--------|---------|-------------|
| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. |
| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. |
| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). |

### LLM: Gemini

| Option | Default | Description |
|--------|---------|-------------|
| `--llm-gemini-model` | `gemini-3-flash-preview` | The Gemini model to use for LLM tasks. |
| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. |

### Process Management

| Option | Default | Description |
|--------|---------|-------------|
| `--stop` | `false` | Stop any running background process. |
| `--status` | `false` | Check if a background process is running. |
| `--toggle` | `false` | Toggle the background process on/off. If the process is running, it will be stopped. If the process is not running, it will be started. |

### General Options

| Option | Default | Description |
|--------|---------|-------------|
| `--clipboard/--no-clipboard` | `true` | Copy result to clipboard. |
| `--log-level` | `WARNING` | Set logging level. |
| `--log-file` | - | Path to a file to write logs to. |
| `--quiet` | `false` | Suppress console output from rich. |
| `--json` | `false` | Output result as JSON for automation. Implies --quiet and --no-clipboard. |
| `--config` | - | Path to a TOML configuration file. |
| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. |
| `--transcription-log` | - | Path to log transcription results with timestamps, hostname, model, and raw output. |


<!-- OUTPUT:END -->

## Workflow Integration

### Toggle Recording Hotkey

The `--toggle` flag is designed for hotkey integration:

```bash
# First press: starts recording
agent-cli transcribe --toggle --input-device-index 1

# Second press: stops recording and transcribes
agent-cli transcribe --toggle
```

### macOS Hotkey (skhd)

```
cmd + shift + r : /path/to/agent-cli transcribe --toggle --input-device-index 1
```

### Transcription Log

Log all transcriptions with timestamps:

```bash
agent-cli transcribe --transcription-log ~/.config/agent-cli/transcriptions.log
```

## Tips

- Use `--list-devices` to find your microphone's index
- Enable `--llm` for cleaner output with proper punctuation
- Use `--last-recording 1` to re-transcribe if you need to adjust settings
