# How to Use the Transcribe Command with Groq versus OpenAI in Agent-Reach

> Learn to use the transcribe command in Agent-Reach with Groq and OpenAI providers. Discover automatic fallback for seamless voice-to-text transcription.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-19

---

**Agent-Reach's `transcribe` command supports both Groq and OpenAI as Whisper providers, with automatic fallback from Groq to OpenAI when using `--provider auto` (the default).**

The `transcribe` command in the [Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach) repository provides a unified interface for converting YouTube videos or local audio files into text using OpenAI-compatible Whisper APIs. You can explicitly choose between **Groq** and **OpenAI** as the backend provider, or let the tool automatically handle failover between them. This article explains how to configure, select, and troubleshoot both providers based on the actual implementation in the source code.

## Provider Configuration and Authentication

Before invoking the `transcribe` command, you must store the appropriate API keys using the built-in configuration system. The keys are persisted to `~/.agent-reach/config.yaml` and read at runtime via `Config().get()` in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).

### Configuring API Keys

Use the `configure` command to store your credentials:

```bash

# Required for Groq provider or auto fallback

agent-reach configure groq-key YOUR_GROQ_API_KEY

# Required for OpenAI provider or auto fallback

agent-reach configure openai-key YOUR_OPENAI_API_KEY

```

If you attempt to use a provider without configuring its key, the command aborts early with a `NoProviderConfigured` error, as validated in [`tests/test_transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_transcribe.py) (lines 22-26).

## Selecting Between Groq and OpenAI

The provider selection logic resides in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) and supports three distinct modes of operation.

### Explicit Provider Selection

Force a specific backend by passing the `--provider` flag:

```bash

# Use Groq's whisper-large-v3 model

agent-reach transcribe https://youtu.be/abc123 --provider groq

# Use OpenAI's whisper-1 model

agent-reach transcribe /path/to/audio.m4a --provider openai

```

When explicitly selected, the command attempts only that provider and fails if the corresponding API key is missing or the request errors out.

### Automatic Fallback (Default)

The default mode (`--provider auto`) tries Groq first, then falls back to OpenAI if the initial request fails:

```bash

# Tries Groq first; on HTTP error (e.g., 429), falls back to OpenAI

agent-reach transcribe https://youtu.be/abc123

```

This behavior is implemented in `_transcribe_with_fallback()` (lines 49-61 of [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py)), which walks the provider list returned by `_provider_order()` until one succeeds.

### Configuration-Driven Validation

Even in automatic mode, a provider is skipped if its API key is absent from the config file. The `_provider_order()` function (lines 99-105) returns `["groq", "openai"]` for auto mode, but `_transcribe_with_fallback()` checks key existence before attempting each endpoint.

## How Provider Selection Works Internally

The routing logic spans three core files:

1. **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** – Parses the `--provider` argument in `_cmd_transcribe()` (lines 1113-1122) and forwards it to the transcription engine.
2. **[`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py)** – Contains the provider definitions, fallback orchestration, and HTTP posting logic.
3. **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)** – Provides the `Config().get()` interface for retrieving `groq_api_key` and `openai_api_key`.

The provider table is defined as follows:

```python

# agent_reach/transcribe.py (lines 30-41)

PROVIDERS = {
    "groq": {
        "endpoint": "https://api.groq.com/openai/v1/audio/transcriptions",
        "model": "whisper-large-v3",
        "key_field": "groq_api_key",
    },
    "openai": {
        "endpoint": "https://api.openai.com/v1/audio/transcriptions",
        "model": "whisper-1",
        "key_field": "openai_api_key",
    },
}

```

The fallback sequence is determined by `_provider_order()`:

```python

# agent_reach/transcribe.py (lines 99-105)

def _provider_order(provider: str) -> List[str]:
    if provider == "auto":
        return ["groq", "openai"]
    if provider in PROVIDERS:
        return [provider]
    raise TranscribeError(...)

```

And executed via `_transcribe_with_fallback()`:

```python

# agent_reach/transcribe.py (lines 49-61)

def _transcribe_with_fallback(chunk, order, config):
    for p in order:
        if not _provider_key(p, config):
            continue        # skip unconfigured providers

        try:
            return transcribe_chunk(chunk, p, config=config)
        except TranscribeError as e:
            last_err = e
    raise TranscribeError(...)

```

## Usage Examples

| Goal | Command | Behavior |
|------|---------|----------|
| **Transcribe YouTube with Groq** | `agent-reach transcribe https://youtu.be/abc123 --provider groq` | Downloads audio via `yt-dlp`, compresses if needed, posts to `https://api.groq.com/openai/v1/audio/transcriptions` |
| **Transcribe local file with OpenAI** | `agent-reach transcribe /path/to/audio.m4a --provider openai` | Compresses audio if required, posts to `https://api.openai.com/v1/audio/transcriptions` |
| **Auto fallback** | `agent-reach transcribe audio.mp3` | Attempts Groq first; on failure, automatically retries with OpenAI |
| **Save output** | `agent-reach transcribe audio.mp3 -o transcript.txt` | Writes transcription to [`transcript.txt`](https://github.com/Panniantong/Agent-Reach/blob/main/transcript.txt) and prints confirmation |

## Summary

- **Configure keys first** using `agent-reach configure` for `groq_api_key` and/or `openai_api_key` before running transcription jobs.
- **Choose explicit providers** with `--provider groq` or `--provider openai`, or rely on `--provider auto` (default) to try Groq then OpenAI.
- **Understand the internals**: [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) defines the `PROVIDERS` table and `_provider_order()` logic, while [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) handles argument parsing in `_cmd_transcribe()`.
- **Groq uses** `whisper-large-v3` and **OpenAI uses** `whisper-1` according to the endpoint configurations in the source code.

## Frequently Asked Questions

### What happens if I don't configure an API key for my chosen provider?

The command raises a `NoProviderConfigured` error and exits immediately. As implemented in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py), the `_transcribe_with_fallback()` function checks for key existence via `_provider_key()` before attempting any HTTP request, and the CLI catches this in `_cmd_transcribe()` to display a user-friendly error message.

### Can I use both providers interchangeably without changing my config?

Yes. By storing both `groq_api_key` and `openai_api_key` in `~/.agent-reach/config.yaml`, you can switch between them using the `--provider` flag on a per-command basis, or use `--provider auto` to let the system handle failover automatically if one service is rate-limited.

### Why does automatic mode try Groq before OpenAI?

The `_provider_order()` function in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) explicitly returns `["groq", "openai"]` when the provider argument is set to `auto`. This ordering prioritizes Groq's typically faster inference and lower costs, falling back to OpenAI only if Groq returns an HTTP error or is unconfigured.

### How do I save the transcription output to a file instead of stdout?

Use the `-o` or `--output` flag followed by your desired filename: `agent-reach transcribe audio.mp3 -o transcript.txt`. The CLI writes the text to the specified path and prints a success message upon completion, handling both YouTube URLs and local file paths identically.