What is the Deepgram CLI?

The Deepgram CLI (dg or deepctl) is the official command-line interface for Deepgram's speech AI platform. It lets developers transcribe audio files and URLs, stream live speech-to-text from a microphone, synthesize text-to-speech, and interact with the full Deepgram REST API — all from the terminal.

How do I install the Deepgram CLI?

On macOS or Linux, run: curl -fsSL deepgram.com/install.sh | sh. On Windows PowerShell, run: iwr deepgram.com/install.ps1 | iex. You can also install via pip (pip install deepctl), pipx, uvx, or Homebrew.

How do I transcribe an audio file with the Deepgram CLI?

After logging in with 'dg login', run: dg listen recording.wav. You can also transcribe URLs (dg listen https://example.com/audio.mp3), enable speaker diarization (--diarize), select a model (--model nova-3), and export JSON for scripting (dg -o json listen recording.wav).

Does the Deepgram CLI work with AI coding tools like Claude Code?

Yes. The Deepgram CLI auto-detects AI agent environments including Claude Code, Aider, OpenAI Codex, and others. In agent context it automatically disables interactive prompts, routes status messages to stderr, and defaults to JSON output. Pass --agent-friendly to any command to get a machine-readable JSON schema of its parameters and capabilities.

What speech-to-text models does the Deepgram CLI support?

The Deepgram CLI supports all Deepgram models including nova-3 (default for streaming), nova-2, Whisper, and enhanced/base tier models. Use the --model flag or run 'dg models' to list all available models.

Can I pipe the Deepgram CLI output to other tools?

Yes. The CLI is fully UNIX-composable. Use --output json (or -o json) to get structured JSON, which can be piped to jq, grep, and other tools. When stdout is a pipe, the CLI automatically switches to JSON. Status messages always go to stderr to keep stdout clean.

Official Deepgram Developer Tool · v0.3.0

Speech AI,in your terminal.

Transcribe, synthesize, and stream audio. The official CLI for Deepgram's speech platform.

$curl -fsSL deepgram.com/install.sh | sh

dg — zsh — 80×24

❯

25+

Commands

nova-3

Default STT model

Python 3.10+

Runtime

MIT

License

Everything speech AI. One command.

Built for developers who live in the terminal and need their tools to keep up.

Speech-to-text

Transcribe files and URLs with nova-3. Speaker diarization, smart formatting, topic detection, and summaries — all from one command.

$ dg listen podcast.mp3 --diarize

Live streaming

WebSocket stream from mic or stdin. Real-time transcripts with interim results and word-level timing.

Text-to-speech

Stream speech with Flux TTS, or pick from 40+ Aura voices. Pipe to ffplay or save to file.

Agent-ready by default

Auto-detects Claude Code, Aider, and Codex. Disables prompts, routes status to stderr, switches to JSON — no flags needed.

# Auto-detected

CLAUDECODE=1

# Explicit

dg ... --agent-friendly

UNIX philosophy

Pipe-friendly.
Script-ready.

Every command writes structured data to stdout and diagnostics to stderr. Switch formats with -o json or let it auto-switch when piped. Plays nicely with every UNIX tool you already know.

JSON / YAML / table / CSV

Explicit output format, or auto-JSON when piped.

Errors to stderr

Clean stdout channel. No surprises in pipes.

Exit codes everywhere

Non-zero on error. Works in set -e scripts.

# Transcribe + extract with jq

$ dg -o json listen call.mp3 \

| jq '.results.channels[0] .alternatives[0].transcript'

"Hello and welcome to our Q1 review..."

# TTS piped to speaker

$ dg speak "Hello from Deepgram" \

| ffplay -nodisp -autoexit -

# Stream mic → log

$ dg -o json listen --mic | tee log.jsonl

ALL COMMANDS

Every workflow, covered.

From a quick transcription to a full production pipeline — there's a command for that.

dg listen

Transcribe a local file

Smart formatting, punctuation, and speaker diarization on any audio or video file.

$ dg listen podcast.mp3 --smart-format --diarize

dg listen

Fetch and transcribe a URL

$ dg listen https://dpgr.am/spacewalk.wav

dg listen

Live microphone transcription

Real-time WebSocket stream with interim results as you speak.

$ dg listen --mic --smart-format

dg listen

Stream via ffmpeg

Pipe any source ffmpeg can read — HLS, RTMP, webcam, or broadcast.

$ ffmpeg -i stream.m3u8 -f wav - \

| dg listen --srt

dg listen

Write live WebVTT captions

Pipe real-time caption output directly to a .vtt file.

$ dg listen --mic --webvtt > captions.vtt

dg listen

Redact sensitive audio

Strip PCI, SSN, or numbers from transcripts — works on files and live streams.

$ dg listen call.wav --redact pci --numerals

dg listen

Stream with Flux STT

Conversational turn-based model for live audio. Streaming only — use nova-3 for files.

$ dg listen --mic --model flux-general-en \

--redact aggressive_numbers

dg listen

Pipe transcript to an LLM

Chain with any LLM CLI for instant summarization or Q&A.

$ dg listen meeting.mp3 \

| llm "summarize key decisions"

dg speak

Synthesize speech to a file

Streams from Flux TTS by default — Aura voices stay available with -m aura-2-*.

$ dg speak "Hello from Deepgram" -o hello.wav

dg speak

Tune pace and expressivity

Flux-only controls: --speed in 0.05 steps from 0.85 to 1.15, and --expressivity from -2 to 2 (beta).

$ dg speak "So exciting!" --speed 1.05 \

--expressivity 2 -o lively.wav

dg speak

Pick an Aura voice

Speak v1 REST batch — 40+ Aura voices with mp3, linear16, flac, and opus output.

$ dg speak "Hola, mundo" -m aura-2-selena-es -o hola.mp3

dg speak

Pipe TTS to your speaker

Any text in, audio out. Works with ffplay, aplay, or mpv.

$ echo "Latest headlines" | dg speak \

| ffplay -nodisp -autoexit -

dg read

Analyze a text document

Topics, sentiment, and summary — all in one pass against Deepgram's text intelligence API.

$ dg read report.txt --topics --sentiment --summarize

dg read

Summarize piped text

$ cat transcript.txt | dg read --summarize

dg login

Authenticate the CLI

Walks through API key setup and saves it to your local profile.

$ dg login

dg keys

Create a scoped API key

$ dg keys --create --comment "ci-runner" --scopes member

dg projects

List all projects

$ dg projects --list

dg members

View project members

$ dg members --list

dg models

Browse available models

Filter by type, language, or tier to find the right model.

$ dg models --type stt

dg usage

Check usage and limits

$ dg usage

dg billing

View account balance

$ dg billing

dg requests

Audit recent API calls

$ dg -o json requests --limit 20

dg api

Call any Deepgram endpoint

Escape hatch for endpoints not yet covered by a dedicated command.

$ dg api /v1/projects

dg debug audio

Diagnose audio devices

Lists input devices and tests recording capability.

$ dg debug audio

dg debug network

Test Deepgram connectivity

Checks DNS, TLS, and WebSocket reachability to Deepgram endpoints.

$ dg debug network

dg init

Scaffold a starter app

Clone a Deepgram starter app, pre-wired and ready to run.

$ dg init

dg mcp

Run as MCP server

Expose every CLI command to Claude, Cursor, and other MCP clients.

$ dg mcp

dg skills

Regenerate AI skill files

Keep your coding agent's context current with the latest commands.

$ dg skills update

dg plugin

Install a community plugin

$ dg plugin install deepctl-cmd-studio

dg update

Self-update the CLI

Detects your install method and runs the right upgrade command.

$ dg update

dg completion

Install shell tab-completion

$ dg completion zsh --install

dg profiles

Switch between accounts

Keep separate credentials per environment and switch with one command.

$ dg profiles --list

dg profiles --switch staging

dg logout

Clear stored credentials

$ dg logout --profile staging

dg ffprobe

Point at a custom ffprobe

Used for local audio analysis before transcription.

$ dg ffprobe --path $(which ffprobe)

dg debug browser

Check browser capabilities

Verifies codec and WebSocket support for browser-based capture.

$ dg debug browser

dg debug probe

Proxy and inspect a live stream

Sits in front of a stream so you can see exactly what reaches Deepgram.

$ dg debug probe

Get started in seconds

One command. Every platform. Authenticate once, then go.

$curl -fsSL deepgram.com/install.sh | sh

# Authenticate

$ dg login

# Transcribe

$ dg listen audio.mp3

# Explore

$ dg --help

Built for AI agents

Works with your AI coding tools

dgauto-detects Claude Code, Aider, Codex and more. Detected agents get non-interactive defaults, clean JSON output, and stderr-only status — automatically.

dg listen audio.mp3 --agent-friendly

$ dg listen --agent-friendly

{

"command": "listen",

"agent_hints": "Accepts local files or HTTP URLs...",

"requires_auth": true,

"non_interactive": true,

"output_formats": ["json", "yaml", ...]

}

Speech AI,in your terminal.

Everything speech AI. One command.

Speech-to-text

Live streaming

Text-to-speech

Agent-ready by default

Pipe-friendly.Script-ready.

Every workflow, covered.

Transcribe a local file

Fetch and transcribe a URL

Live microphone transcription

Stream via ffmpeg

Write live WebVTT captions

Redact sensitive audio

Stream with Flux STT

Pipe transcript to an LLM

Synthesize speech to a file

Tune pace and expressivity

Pick an Aura voice

Pipe TTS to your speaker

Analyze a text document

Summarize piped text

Authenticate the CLI

Create a scoped API key

List all projects

View project members

Browse available models

Check usage and limits

View account balance

Audit recent API calls

Call any Deepgram endpoint

Diagnose audio devices

Test Deepgram connectivity

Scaffold a starter app

Run as MCP server

Regenerate AI skill files

Install a community plugin

Self-update the CLI

Install shell tab-completion

Switch between accounts

Clear stored credentials

Point at a custom ffprobe

Check browser capabilities

Proxy and inspect a live stream

Get started in seconds

Works with your AI coding tools

Pipe-friendly.
Script-ready.