Developer ToolsCommand-Line Interface

Deepgram CLI — Getting Started

Transcribe audio, synthesize speech, and manage your Deepgram account — all from your terminal.

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

Prerequisites

Quick Start

# 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

Core Workflows

Transcribe audio

# 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'

Text-to-speech

# 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 -

Text intelligence

# Analyze a text file
dg read --file report.txt --topics --sentiment --summarize
# Summarize piped text
cat transcript.txt | dg read --summarize

Account management

# 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.

Output Formats

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.

Exit Codes

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

CodeMeaning
0Success
1Command, execution, or usage error, such as an unknown command or invalid flag
2Root-level user interrupt
if dg -o json listen audio.mp3 > transcript.json; then
  echo "transcribed"
else
  echo "failed with code $?" >&2
fi

Exit codes are enforced as of CLI 0.3.0. Earlier versions exited 0 regardless of outcome, so a pipeline that ignored the exit code may begin surfacing failures it previously swallowed. dg listen --mic and dg mcp currently handle Ctrl-C themselves and exit 0; do not rely on an interrupt exit code for those commands.

Agent-Friendly Mode

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

Other Commands

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

Next Steps