# How to Configure the Agent Reach Transcribe Command with Groq or OpenAI

> Master the Agent Reach transcribe command! Configure Groq or OpenAI API keys and effortlessly transcribe audio files. Get started now for efficient voice-to-text.

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

---

**To use the Agent Reach transcribe command with Groq or OpenAI, store your API keys using `agent-reach configure groq-key <key>` or `agent-reach configure openai-key <key>`, then run `agent-reach transcribe <file> --provider groq` or `--provider openai`.**

The **Agent Reach** CLI ships with a built-in transcription pipeline that supports multiple Whisper-compatible providers. This guide explains how to configure the **Agent Reach transcribe command with Groq or OpenAI** providers, set up authentication keys, and manage provider fallback behavior according to the source implementation in `Panniantong/Agent-Reach`.

## Provider Architecture and Configuration Keys

The transcription logic lives in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py), which defines a `PROVIDERS` dictionary (lines 30–41) mapping each provider to its API endpoint, model name, and configuration key name.

| Provider | Endpoint | Model | Config Key |
|----------|----------|-------|------------|
| **Groq** | `https://api.groq.com/openai/v1/audio/transcriptions` | `whisper-large-v3` | `groq_api_key` |
| **OpenAI** | `https://api.openai.com/v1/audio/transcriptions` | `whisper-1` | `openai_api_key` |

When `transcribe()` is invoked, the `_provider_order()` function determines which backends to attempt (default `auto` tries Groq first, then falls back to OpenAI). The `_provider_key()` method (lines 57–61) retrieves the appropriate key from a `Config` instance. If a requested provider lacks a key, the code raises `NoProviderConfigured` (lines 175–179).

The configuration mapping itself is defined in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 22–27), which links feature requirements to their respective key fields.

## Configuring API Keys via CLI

You must store your API credentials before running transcription jobs. The CLI writes keys to `~/.agent-reach/config.yaml` and also respects environment variables.

1. **Obtain your API keys** from the [Groq dashboard](https://console.groq.com) or [OpenAI platform](https://platform.openai.com).

2. **Save the keys using the configure command**:

```bash

# Configure Groq

agent-reach configure groq-key gsk_xxxxxxxxxxxxxxxxxxxxxxxx

# Configure OpenAI  

agent-reach configure openai-key sk-xxxxxxxxxxxxxxxxxxxxxxxx

```

These commands invoke the `configure` sub-command in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (around line 1100), which updates the local config file with the fields `groq_api_key` and `openai_api_key` respectively.

## Running the Transcribe Command

The `_cmd_transcribe` handler in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (around line 64) forwards CLI arguments to the `transcribe()` function. You can explicitly select a provider or rely on the automatic fallback chain.

**Auto-fallback (Groq → OpenAI):**

```bash
agent-reach transcribe https://youtu.be/example_video

```

**Force Groq only:**

```bash
agent-reach transcribe ./audio.m4a --provider groq

```

**Force OpenAI only:**

```bash
agent-reach transcribe ./audio.m4a --provider openai

```

When forced, the transcription fails fast with a clear error if the corresponding `groq_api_key` or `openai_api_key` is missing.

## Error Handling for Missing Credentials

If you attempt to use a provider without configuring its key, the pipeline raises `NoProviderConfigured` from [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) (lines 175–179), prompting you to run the specific `configure` command for that provider.

## Summary

- **Provider definitions** reside in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py), mapping Groq and OpenAI to their respective Whisper endpoints and models.
- **Configuration keys** `groq_api_key` and `openai_api_key` are managed via [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) and stored in `~/.agent-reach/config.yaml`.
- **CLI setup** requires running `agent-reach configure groq-key <key>` or `agent-reach configure openai-key <key>` before transcription.
- **Provider selection** uses `--provider groq` or `--provider openai`; omitting the flag enables automatic fallback from Groq to OpenAI.

## Frequently Asked Questions

### How do I switch between Groq and OpenAI when transcribing?

Use the `--provider` flag to explicitly select the backend. Run `agent-reach transcribe <file> --provider groq` to force Groq, or `--provider openai` to force OpenAI. If you omit the flag, the `auto` mode attempts Groq first and falls back to OpenAI if the Groq request fails or the key is missing.

### Where does Agent Reach store my API keys?

The `agent-reach configure` command writes keys to a YAML file at `~/.agent-reach/config.yaml`. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) reads this file at runtime, also checking for environment variables that match the key names `groq_api_key` and `openai_api_key`.

### What model does each provider use for transcription?

According to the `PROVIDERS` dictionary in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py), Groq uses the `whisper-large-v3` model, while OpenAI uses the `whisper-1` model. These are hardcoded in the provider configuration and sent as the `model` parameter in the respective API requests.

### Can I transcribe YouTube URLs directly?

Yes. The `transcribe()` function in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) handles URL detection, downloads the audio stream, compresses it if necessary, and chunks large files before sending them to the configured Whisper endpoint. Simply pass the URL as the argument: `agent-reach transcribe https://youtu.be/dQw4w9WgXcQ`.