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

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, 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 (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 or OpenAI platform.

2. Save the keys using the configure command:

# 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 (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 (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):

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

Force Groq only:

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

Force OpenAI only:

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 (lines 175–179), prompting you to run the specific configure command for that provider.

Summary

• Provider definitions reside in 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 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 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}