Deepgram CLI — Getting Started

The dg CLI lets you transcribe files, stream live audio, synthesize speech, analyze text, and manage your Deepgram account from the terminal.

• Python 3.10 or later
• A Deepgram API key (get one free)

# Install
curl -fsSL https://deepgram.com/install.sh | sh

# Authenticate
dg login

# Transcribe an audio file
dg listen recording.wav

# Synthesize text-to-speech to a file
dg speak "Hello from Deepgram" -o hello.wav

# Transcribe a local file
dg listen audio.mp3

# Transcribe from a URL
dg listen https://example.com/audio.mp3

# Stream from your microphone
dg listen --mic

# Pipe transcript to another tool
dg -o json listen audio.mp3 | jq '.full_result.results.channels[0].alternatives[0].transcript'

# Generate speech and save to file
dg speak "Hello from Deepgram" -o hello.wav

# Pipe audio to your speaker
echo "Latest headlines" | dg speak | ffplay -nodisp -autoexit -

# Analyze a text file
dg read --file report.txt --topics --sentiment --summarize

# Summarize piped text
cat transcript.txt | dg read --summarize

# List your projects
dg projects --list

# Create an API key
dg keys --create --comment "ci-runner"

# Check your usage
dg usage

Account commands are flag-based. Run dg keys --help or dg projects --help for the full set.

The CLI defaults to human-readable output in the terminal. Use -o or --output to switch formats:

dg -o json listen audio.mp3   # Structured JSON
dg -o yaml listen audio.mp3   # YAML
dg -o table listen audio.mp3  # Formatted terminal table
dg -o csv listen audio.mp3    # CSV

-o belongs to dg itself, so it goes before the subcommand name. After the subcommand it fails to parse and exits 1. On dg speak the collision is quieter: there, a bare -o is the output file path, not a format.

Agent-friendly mode selects JSON on its own, without -o. A piped stdout alone does not trigger it.

For dg -o json listen, parse errors and progress output go to stderr, so redirecting stderr leaves stdout carrying the payload:

dg -o json listen audio.mp3 2>/dev/null > transcript.json

Some command-level errors still print to stdout — an authentication failure is the common one — so check the exit code rather than assuming stdout parses.

Most command and usage outcomes use these exit codes, so scripts and CI steps can branch on them:

if dg -o json listen audio.mp3 > transcript.json; then
  echo "transcribed"
else
  echo "failed with code $?" >&2
fi

The CLI auto-detects AI agent environments, including Claude Code, Aider, and OpenAI Codex, and adjusts its behavior:

• Disables interactive prompts
• Defaults to JSON output

To force the mode on:

CI=true dg listen audio.mp3
dg listen audio.mp3 --non-interactive

--agent-friendly does something different on a subcommand: it prints that command’s parameter documentation as JSON and exits without running it.

dg listen --agent-friendly

The CLI also includes commands for models, requests, profiles, updates, debugging, starter scaffolding, audio probing, and coding-assistant skills:

dg models --help
dg requests --help
dg profiles --help
dg update --help
dg debug --help
dg init --help
dg ffprobe --help
dg skills --help

• Install the CLI — More installation methods including pip, pipx, and Homebrew
• Authenticate — Learn about authentication options
• Speech-to-Text — Full transcription reference
• Text-to-Speech — Full TTS reference