Deepgram CLI

Usage: dg [OPTIONS] COMMAND [ARGS]...

████████████████
██████████████████
████████████████████
█████████████████████
███████      ████████
███████       ███████
             ████████
      ███████████████
    ████████████████
  ████████████████
████████████████

deepctl — Official Deepgram CLI STT · TTS · Audio Intelligence

The official Deepgram CLI brings speech-to-text, text-to-speech, audio intelligence, and project management directly into your terminal. Aliases: deepctl, deepgram, dg.

Installation

Quick Install

macOS / Linux (Homebrew):

brew tap deepgram/tap
brew install deepgram

Homebrew brings in ffmpeg and portaudio automatically — dg listen --mic, dg debug probe, and raw audio piping all work without further setup. To upgrade later: brew upgrade deepgram.

macOS / Linux (curl):

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

Windows (PowerShell):

iwr https://deepgram.com/install.ps1 -useb | iex

Package Managers

pip install deepctl          # pip
uv tool install deepctl      # uv
pipx install deepctl         # pipx

Try Without Installing

uvx deepctl --help
pipx run deepctl --help

Getting Started

# Authenticate with Deepgram
dg login

# Transcribe an audio file
dg listen recording.wav

# Text-to-speech
dg speak "Hello from Deepgram" -o hello.mp3

# Live microphone transcription
dg listen --mic

# Analyze text for sentiment and topics
dg read "The product is amazing" --sentiment --topics

Examples

Speech-to-text

# File or URL — auto-detected
dg listen keynote.mp3 --diarize --model nova-3
dg listen https://cdn.example.com/podcast.mp3

# Pipe to jq for scripting
dg -o json listen standup.mp3 \
  | jq '.results.channels[0].alternatives[0].transcript'

# Live microphone with interim (partial) results
dg listen --mic --model nova-3 --interim

# Raw audio stream from ffmpeg
ffmpeg -i video.mp4 -f s16le -ar 16000 -ac 1 - \
  | dg listen --encoding linear16

Captions (WebVTT & SRT)

# Generate a WebVTT file
dg listen keynote.mp3 --webvtt --save-to keynote.vtt

# SRT with speaker labels
dg listen interview.mp3 --srt --diarize --save-to interview.srt

# Stream live captions from the microphone
dg listen --mic --webvtt

# Captions from a video via ffmpeg
ffmpeg -i video.mp4 -f s16le -ar 16000 -ac 1 - \
  | dg listen --encoding linear16 --srt

Text intelligence

dg read earnings.txt --sentiment --summarize --topics

Text-to-speech

# Stream directly to a player
dg speak "Hello from Deepgram" | ffplay -nodisp -autoexit -

Account & project management

dg whoami                                        # Auth status
dg projects --list                               # List projects
dg keys --create --comment 'ci-pipeline' --dry-run  # Dry-run key creation
dg usage --last-month                            # Usage stats
dg requests --status failed --endpoint listen   # Debug failed requests

Raw API & MCP

# Hit any endpoint directly
dg api /v1/projects --jq '.projects[0].name'

# MCP server for AI editors (Claude Code, Cursor, etc.)
dg mcp --transport sse --port 8000

Features

Speech-to-Text

Transcribe audio files, URLs, or live microphone input.

dg listen meeting.wav --diarize --smart-format
dg listen https://example.com/audio.mp3 --model nova-3
dg listen --mic --model nova-3 --language en-US
cat audio.raw | dg listen --encoding linear16 --sample-rate 16000

Text-to-Speech

Convert text to natural speech. Supports file output and piping.

dg speak "Welcome to Deepgram" -o welcome.mp3
dg speak --file script.txt -o output.mp3 -m aura-2-luna-en
echo "Hello" | dg speak -o greeting.mp3
dg speak "Stream me" | ffplay -nodisp -    # pipe to audio player

Text Intelligence

Analyze text for sentiment, summaries, topics, and intents.

dg read "Customer called about billing" --sentiment --summarize
dg read --file article.txt --topics --intents
cat feedback.txt | dg read --sentiment

Project Management

Manage your Deepgram account from the terminal.

dg projects --list                        # List projects
dg keys --list                            # List API keys
dg keys --create --comment "staging"      # Create API key
dg members                                # List team members
dg members --invite user@co.com           # Invite member
dg usage --last-month                     # View usage stats
dg billing                                # Check balances
dg requests --limit 20 --status failed    # Request history
dg models --type tts                      # List available models

Direct API Access

Make authenticated requests to any Deepgram endpoint.

dg api /v1/projects
dg api /v1/projects -X POST -f name="New Project"
dg api /v1/listen -X POST --input audio.wav --jq '.results'

Debugging Tools

Diagnose audio, network, and browser issues.

dg debug audio --file recording.wav       # Analyze audio compatibility
dg debug network --verbose                # Test connectivity to Deepgram
dg debug probe --port 3100                # Live stream audio analysis

MCP Server

Connect Deepgram tools to AI coding assistants (Claude Code, Cursor, etc.).

dg mcp                                    # Start MCP server (stdio)
dg mcp --transport sse --port 8000        # SSE transport

Add to your editor's MCP config:

{
  "mcpServers": {
    "deepgram": {
      "type": "stdio",
      "command": "dg",
      "args": ["mcp"]
    }
  }
}

AI Tool Integration

Automatically detect and configure AI coding assistants with Deepgram skills.

dg skills status                          # Detect AI tools
dg skills setup                           # Interactive setup wizard
dg skills install --all                   # Install for all detected tools

Starter Apps

Scaffold a new project from Deepgram templates.

dg init --list                            # Browse templates
dg init node-live-transcription           # Clone and set up

CI / Automation

Every command is CI-friendly. Authentication works via environment variables, all interactive prompts have flag-based alternatives, and destructive operations require explicit --yes.

# CI authentication
export DEEPGRAM_API_KEY="your-key"
export DEEPGRAM_PROJECT_ID="your-project-id"

# Non-interactive usage
dg listen recording.wav
dg speak "Deploy complete" -o notification.mp3
dg keys --create --comment "ci-key" --scopes member
dg keys --delete KEY_ID --yes
dg read --file report.txt --summarize

# Output formats for scripting
dg projects --list -o json
dg keys --list -o csv
dg usage --last-week -o yaml

When running in a non-TTY environment (pipes, CI, or AI coding tools), the CLI automatically switches to structured JSON output with plain-text status messages.

Plugins

Extend the CLI with custom commands.

dg plugin search deepctl-               # Find plugins
dg plugin install <package>              # Install
dg plugin list                           # List installed
dg plugin remove <package>              # Remove

Create your own — see the plugin example.

Configuration

Priority: CLI flags > environment variables > profile config > project config

dg login                                 # Interactive or --api-key
dg login --profile staging --api-key SK  # Named profiles
dg profiles --list                       # List profiles
dg profiles --switch staging             # Switch profile

Output format on any command: --output json|yaml|table|csv

Telemetry

The CLI phones home anonymous error reports to help us catch crashes and regressions before users have to file an issue. It's on by default and easy to turn off.

What's collected: Python exceptions, stack traces, the CLI version, and the Python runtime. Request bodies, headers, cookies, API keys, email addresses, IP addresses, and usernames are scrubbed before send. No performance traces, no profiling, no replays — errors only.

Where it goes: the dx-cli Sentry project owned by the Deepgram DX team.

Opt out

Persistent (recommended):

dg config set telemetry.enabled false

One-shot (CI, scripts, single command):

DEEPCTL_TELEMETRY_DISABLED=1 dg listen recording.wav

Override the destination

For forks or self-hosted Sentry, point telemetry at your own DSN:

export DEEPCTL_TELEMETRY_DSN='https://<key>@<your-sentry>/<project>'

DEEPCTL_TELEMETRY_DISABLED always wins. The default DSN is baked into the package and only used when the override is unset.

Development

git clone https://github.com/deepgram/cli && cd cli
uv sync --group dev
make dev                                 # Format + lint + test
make check                               # Format + lint + typecheck (no tests)

Architecture

cli/
├── src/deepctl/                      # Main CLI entry point
├── packages/
│   ├── deepctl-cmd-api/              # API command for deepctl
│   ├── deepctl-cmd-billing/          # Billing command for deepctl
│   ├── deepctl-cmd-completion/       # Shell completion command for deepctl
│   ├── deepctl-cmd-debug/            # Debug command group for deepctl
│   ├── deepctl-cmd-debug-audio/      # Audio debug subcommand for deepctl
│   ├── deepctl-cmd-debug-browser/    # Browser debug subcommand for deepctl
│   ├── deepctl-cmd-debug-network/    # Network debug subcommand for deepctl
│   ├── deepctl-cmd-debug-probe/      # Debug probe subcommand for deepctl — live ffprobe analysis during streaming
│   ├── deepctl-cmd-debug-toolkit/    # Toolkit subcommand for dg debug — runs field support scripts from deepgram/support-toolkit
│   ├── deepctl-cmd-ffprobe/          # FFprobe configuration command for deepctl
│   ├── deepctl-cmd-init/             # Init command for deepctl — scaffold Deepgram starter apps
│   ├── deepctl-cmd-keys/             # API keys management command for deepctl
│   ├── deepctl-cmd-listen/           # Listen (live speech-to-text) command for deepctl
│   ├── deepctl-cmd-login/            # Login command for deepctl
│   ├── deepctl-cmd-mcp/              # MCP proxy command for deepctl — connects to Deepgram's developer API
│   ├── deepctl-cmd-members/          # Members management command for deepctl
│   ├── deepctl-cmd-models/           # Models command for deepctl
│   ├── deepctl-cmd-plugin/           # Plugin management command for deepctl
│   ├── deepctl-cmd-projects/         # Projects command for deepctl
│   ├── deepctl-cmd-read/             # Read (text intelligence) command for deepctl
│   ├── deepctl-cmd-requests/         # Requests history command for deepctl
│   ├── deepctl-cmd-skills/           # AI coding assistant skill management for deepctl
│   ├── deepctl-cmd-speak/            # Speak (text-to-speech) command for deepctl
│   ├── deepctl-cmd-transcribe/       # Transcribe command for deepctl
│   ├── deepctl-cmd-update/           # Update command for deepctl
│   ├── deepctl-cmd-usage/            # Usage command for deepctl
│   ├── deepctl-core/                 # Core components for deepctl
│   ├── deepctl-plugin-example/       # Example plugin for deepctl
│   ├── deepctl-shared-utils/         # Shared utilities for deepctl
│   └── deepctl-telemetry/            # Opt-out phone-home telemetry for deepctl
├── tests/                            # Integration tests
└── Makefile                          # Development tasks

Commands

Command	Description
`deepctl api`	API command for deepctl
`deepctl billing`	Billing command for deepctl
`deepctl completion`	Shell completion command for deepctl
`deepctl debug audio`	Audio debug subcommand for deepctl
`deepctl debug browser`	Browser debug subcommand for deepctl
`deepctl debug network`	Network debug subcommand for deepctl
`deepctl debug probe`	Debug probe subcommand for deepctl — live ffprobe analysis during streaming
`deepctl debug toolkit`	Toolkit subcommand for dg debug — runs field support scripts from deepgram/support-toolkit
`deepctl debug`	Debug command group for deepctl
`deepctl ffprobe`	FFprobe configuration command for deepctl
`deepctl init`	Init command for deepctl — scaffold Deepgram starter apps
`deepctl keys`	API keys management command for deepctl
`deepctl listen`	Listen (live speech-to-text) command for deepctl
`deepctl login`	Login command for deepctl
`deepctl logout`	Login command for deepctl
`deepctl mcp`	MCP proxy command for deepctl — connects to Deepgram's developer API
`deepctl members`	Members management command for deepctl
`deepctl models`	Models command for deepctl
`deepctl plugin`	Plugin management command for deepctl
`deepctl profiles`	Login command for deepctl
`deepctl projects`	Projects command for deepctl
`deepctl read`	Read (text intelligence) command for deepctl
`deepctl requests`	Requests history command for deepctl
`deepctl skills`	AI coding assistant skill management for deepctl
`deepctl speak`	Speak (text-to-speech) command for deepctl
`deepctl transcribe`	Transcribe command for deepctl
`deepctl update`	Update command for deepctl
`deepctl usage`	Usage command for deepctl
`deepctl whoami`	Login command for deepctl

Packages

Package	Description
`deepctl-cmd-api`	API command for deepctl
`deepctl-cmd-billing`	Billing command for deepctl
`deepctl-cmd-completion`	Shell completion command for deepctl
`deepctl-cmd-debug`	Debug command group for deepctl
`deepctl-cmd-debug-audio`	Audio debug subcommand for deepctl
`deepctl-cmd-debug-browser`	Browser debug subcommand for deepctl
`deepctl-cmd-debug-network`	Network debug subcommand for deepctl
`deepctl-cmd-debug-probe`	Debug probe subcommand for deepctl — live ffprobe analysis during streaming
`deepctl-cmd-debug-toolkit`	Toolkit subcommand for dg debug — runs field support scripts from deepgram/support-toolkit
`deepctl-cmd-ffprobe`	FFprobe configuration command for deepctl
`deepctl-cmd-init`	Init command for deepctl — scaffold Deepgram starter apps
`deepctl-cmd-keys`	API keys management command for deepctl
`deepctl-cmd-listen`	Listen (live speech-to-text) command for deepctl
`deepctl-cmd-login`	Login command for deepctl
`deepctl-cmd-mcp`	MCP proxy command for deepctl — connects to Deepgram's developer API
`deepctl-cmd-members`	Members management command for deepctl
`deepctl-cmd-models`	Models command for deepctl
`deepctl-cmd-plugin`	Plugin management command for deepctl
`deepctl-cmd-projects`	Projects command for deepctl
`deepctl-cmd-read`	Read (text intelligence) command for deepctl
`deepctl-cmd-requests`	Requests history command for deepctl
`deepctl-cmd-skills`	AI coding assistant skill management for deepctl
`deepctl-cmd-speak`	Speak (text-to-speech) command for deepctl
`deepctl-cmd-transcribe`	Transcribe command for deepctl
`deepctl-cmd-update`	Update command for deepctl
`deepctl-cmd-usage`	Usage command for deepctl
`deepctl-core`	Core components for deepctl
`deepctl-plugin-example`	Example plugin for deepctl
`deepctl-shared-utils`	Shared utilities for deepctl
`deepctl-telemetry`	Opt-out phone-home telemetry for deepctl

Release

Merging conventional commits to main triggers release-please to open a release PR. Merging that PR creates tags and publishes all changed packages to PyPI. Each package is versioned independently.

Requirements

Python 3.10+
Cross-platform: Linux, Windows, macOS

Contributing

Fork the repository
uv sync --group dev
make dev (formats, lints, tests)
Submit a pull request

See AGENTS.md for detailed architecture and conventions.

Links

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 280 Commits
.claude		.claude
.github		.github
docs/assets		docs/assets
packages		packages
scripts		scripts
src/deepctl		src/deepctl
tests		tests
web		web
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
conftest.py		conftest.py
context7.json		context7.json
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Deepgram CLI

Installation

Quick Install

Package Managers

Try Without Installing

Getting Started

Examples

Speech-to-text

Captions (WebVTT & SRT)

Text intelligence

Text-to-speech

Account & project management

Raw API & MCP

Features

Speech-to-Text

Text-to-Speech

Text Intelligence

Project Management

Direct API Access

Debugging Tools

MCP Server

AI Tool Integration

Starter Apps

CI / Automation

Plugins

Configuration

Telemetry

Opt out

Override the destination

Development

Architecture

Commands

Packages

Release

Requirements

Contributing

Links

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 90

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages