deepctl 0.2.9

Official Deepgram CLI for speech recognition and audio intelligence

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:

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 listen standup.mp3 -o json \
  | 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 transcribe meeting.wav --diarize --smart-format
dg transcribe 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 [e-mail]           # 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 transcribe 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

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-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
├── 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	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-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

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

1. Fork the repository
2. uv sync --group dev
3. make dev (formats, lints, tests)
4. Submit a pull request

See AGENTS.md for detailed architecture and conventions.

Links

• Documentation
• API Reference
• Discord
• Issues

License

MIT