Usage: dg [OPTIONS] COMMAND [ARGS]...
████████████████
██████████████████
████████████████████
█████████████████████
███████ ████████
███████ ███████
████████
███████████████
████████████████
████████████████
████████████████
deepctl — Official Deepgram CLI STT · TTS · Audio IntelligenceThe official Deepgram CLI brings speech-to-text, text-to-speech, audio
intelligence, and project management directly into your terminal. Aliases:
deepctl, deepgram, dg.
macOS / Linux (Homebrew):
# Install and trust only the Deepgram formula.
brew install deepgram/tap/deepgramHomebrew 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 | shWindows (PowerShell):
iwr https://deepgram.com/install.ps1 -useb | iexpip install deepctl # pip
uv tool install deepctl # uv
pipx install deepctl # pipx
npm install -g @deepgram/cli # npm (installs dg and deepgram)The npm package is a launcher for the same Python CLI. It needs
Node.js 20+ and either uv or Python 3.10-3.14
with venv, and sets the CLI up on first run. It installs prebuilt wheels
only, so it (and npx) fails on Intel Macs and Windows on ARM64, where
cryptography has none; on an Intel Mac, use Homebrew. See
npm/README.md.
uvx deepctl --help
pipx run deepctl --help
npx @deepgram/cli --help# Authenticate with Deepgram
dg login
# Transcribe an audio file
dg listen recording.wav
# Text-to-speech (Flux TTS by default)
dg speak "Hello from Deepgram" -o hello.wav
# Live microphone transcription
dg listen --mic
# Analyze text for sentiment and topics
dg read "The product is amazing" --sentiment --topics# 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
# Redact sensitive numbers and spell numbers as digits (files or live)
# Flux STT (v2) accepts --redact numbers|aggressive_numbers; v1 also pci, ssn, …
dg listen call.wav --redact numbers --numerals
# Raw audio stream from ffmpeg
ffmpeg -i video.mp4 -f s16le -ar 16000 -ac 1 - \
| dg listen --encoding linear16# 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 --srtdg read earnings.txt --sentiment --summarize --topics# Stream directly to a player (Flux TTS streams a WAV; -loglevel error hides
# ffmpeg's cosmetic end-of-stream notice)
dg speak "Hello from Deepgram" | ffplay -loglevel error -nodisp -autoexit -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# Hit any endpoint directly
dg api /v1/projects --jq '.projects[0].name'
# MCP server (stdio) that lets AI editors search Deepgram's docs
dg mcpTranscribe 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 16000Convert text to natural speech. Supports file output and piping.
By default dg speak uses Flux TTS (flux-alexis-en) — the Speak v2 WebSocket
API, which streams and emits raw audio; its linear16 output is wrapped in a WAV
container so it is directly playable. Pass an aura-* model to use the Speak v1
batch REST API instead, which supports containerized formats like MP3.
# Quickstart — synthesize and hear it straight away
dg speak "Hello from Deepgram" --play
# Discover voices
dg speak --list-voices
# Flux TTS (v2, WebSocket streaming) — the default
dg speak "Hello from Flux" -o hello.wav
dg speak "Save it and play it" -o hello.wav --play
# Piped audio is a streaming WAV; -loglevel error hides ffmpeg's cosmetic
# end-of-stream notice (the audio is complete).
dg speak "Hello from Flux" | ffplay -loglevel error -nodisp -autoexit -
# Flux TTS streaming controls (flux-* only): --speed 0.85–1.15 (0.05 steps).
# --expressivity -2..2 is beta; its default 0 is nominal delivery.
dg speak "A little slower" --speed 0.9 --expressivity 1 -o slow.wav
# Aura (v1, batch REST) — opt in with -m aura-*; needed for MP3 output
dg speak "Welcome to Deepgram" -o welcome.mp3 -m aura-2-asteria-en
dg speak --file script.txt -o output.mp3 -m aura-2-luna-en
echo "Hello" | dg speak -o greeting.mp3 -m aura-2-asteria-en
# Aura-2 also has Spanish voices (e.g. aura-2-selena-es); run `dg models`
# for the full, current list.
dg speak "Hola, bienvenido a Deepgram" -o hola.mp3 -m aura-2-selena-es--play uses the first available system player (ffplay, afplay, paplay,
or aplay); install ffmpeg if none is present. With the Flux default the
audio is streamed into the player as it arrives, so playback starts at
first-audio latency rather than after the whole utterance. Each fallback
player is checked against the requested format before the API call: aplay
plays PCM/WAV only and paplay adds FLAC and Opus but not MP3 or AAC, while
ffplay and afplay (macOS) play every format. Playing Aura's default MP3 on
Linux needs ffplay or --encoding flac.
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 --sentimentManage 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 modelsMake 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'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 analysisdg mcp runs a local MCP server over stdio for AI coding assistants (Claude
Code, Cursor, etc.). It has one tool, search_deepgram_knowledge_sources,
which searches Deepgram's documentation. It uses your API key from dg login
or DEEPGRAM_API_KEY; don't put the key in the MCP config. SSE and HTTP
transports aren't supported.
dg mcp # Start MCP server (stdio)Add to your editor's MCP config:
{
"mcpServers": {
"deepgram": {
"type": "stdio",
"command": "dg",
"args": ["mcp"]
}
}
}Install the Deepgram skills as folders in each AI coding assistant's skills folder.
dg skills status # Detect AI tools
dg skills setup # Interactive setup wizard
dg skills install --all # Install for all detected tools
dg skills update # Replace the folders deepctl installed
dg skills remove --all # Delete the folders deepctl installed| Tool | Skills folder |
|---|---|
| Claude Code | ~/.claude/skills |
| OpenAI Codex | ~/.agents/skills |
| Gemini CLI | ~/.gemini/skills |
| Cursor | ~/.cursor/skills |
| OpenCode | ~/.config/opencode/skills |
| Cline | ~/.cline/skills |
| Amazon Q Developer, Aider | none: deepctl prints where to get the skills |
deepctl replaces or deletes a folder only if skills.json records it for that tool, it is a real folder directly in that tool's skills folder, it holds deepctl's .deepctl-skill marker, and its contents are exactly what deepctl installed. So folders from npx skills add, and symlinked skill folders, are left alone.
These commands abort if the filesystem cannot provide locking or no-replace directory moves. Installed skill folders and skills.json stay as they were, though the tool's skills folder and ~/.deepctl/skills/skills.json.lock may already have been created. While another dg skills, dg login or dg plugin command is changing skills, the next one waits up to 30 seconds for it to finish. If another of these commands removes or changes a tool's skills while dg skills update or a plugin refresh is running, the refresh leaves that tool as the other command left it and prints a warning. That holds even for the same ref, because a branch such as main can move between two downloads. dg skills update run with --ref still applies its ref to a tool another command updated, but does not reinstall skills another command removed.
dg login offers to install the skills, and dg plugin install, update and remove refresh the installed ones, through the same path as dg skills install and update. A skills installation failure prints a warning on stderr and does not change those commands' exit codes. Ctrl-C still cancels the command.
If you edit a deepctl folder, or add a file or link to it, deepctl leaves it alone: update stops without changing anything and remove won't delete it. To get updates again, rename or move your edited copy, or delete it yourself. Opening a skill folder in Finder or Explorer can add .DS_Store, Thumbs.db or desktop.ini, which counts as an edit.
On macOS and Linux, once dg skills install or update (or dg login, or dg plugin install, update or remove) has installed a tool's skill folders, deepctl removes the files older deepctl wrote for that tool, and prints which ones on stderr: ~/.claude/commands/deepgram/*.md, ~/.cursor/rules/deepctl.mdc, ~/.cline/rules/deepctl.md, and the section between the <!-- BEGIN deepctl CLI Reference and <!-- END deepctl CLI Reference --> lines in ~/.codex/instructions.md, ~/.gemini/GEMINI.md and ~/.opencode/agents.md. In those three files, everything between the two marker lines is removed, including anything you changed there; the rest of the file is kept, apart from the blank line deepctl added before its section. Deepctl keeps the original file next to it as .deepctl-kept-v03-*; compare it for any late write from an open editor, then delete it if you do not need it.
deepctl removes a file only if its content is exactly a deepgram/skills version that older deepctl copied, even if you made that copy yourself. It keeps a file you edited, a link, a file in a folder reached through a link (such as a dotfiles ~/.claude), and a section that is incomplete, repeated or in a read-only or locked file, and warns once about each file 0.3.x recorded. An I/O failure, such as permission denied, is retried on the next install or update, with a warning for files 0.3.x recorded. Amazon Q Developer and Aider files (~/.amazonq/rules/deepctl.md, ~/.deepctl/skills/deepctl-conventions.md) are kept, because those tools have no skill folders; if you delete Aider's, also remove its entry under read: in ~/.aider.conf.yml.
On Windows, deepctl leaves this 0.3.x content untouched because a parent folder could become a junction during cleanup; remove it yourself if you do not need it. While deepctl works on a file on macOS or Linux, it moves it to .deepctl-v03-<name> in the same folder. If deepctl is interrupted, the next install or update puts the file back and says so. If both the file and its .deepctl-v03-<name> are there, as after you saved the file while deepctl was editing it, deepctl changes neither and names both on each run until you compare them and delete the .deepctl-v03-<name> copy; it does the same if .deepctl-v03-<name> is a link or folder deepctl didn't make. A .deepctl-v03-*.tmp file is an unused draft; delete it.
Scaffold a new project from Deepgram templates.
dg init --list # Browse templates
dg init node-live-transcription # Clone and set upEvery 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 -m aura-2-asteria-en
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 yamlIn CI, in AI coding tools, and in any fully non-interactive environment with
no terminal attached (cron, systemd, docker run without -t), the CLI
detects the context and automatically switches to structured JSON output with
plain-text status messages. A plain pipe on its own does not trigger this —
dg projects | jq from an interactive shell still gets the human-readable
table, so pass -o json explicitly when you are piping by hand.
Since 0.3.0, dg exits non-zero when a command fails — branch on the exit
code, not on parsing output:
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Error — a failed command, a crash, or a usage error (bad flag, unknown command) |
2 |
Cancelled by the user (Ctrl-C, or declining a confirmation prompt) |
Note that dg reports 2 for an interrupt rather than the shell's
conventional 130, so the code is the same whether the cancellation came from
Ctrl-C or from declining a prompt.
Human-readable status and error messages go to stderr, and stdout carries the
result. With an explicit structured-output mode, authentication-guard failures
and commands that return an error result write a payload with "status": "error" to stdout — authentication failures, dg ffprobe, and dg debug audio included. Usage errors and handler-raised exceptions report on stderr
and can leave stdout empty. Branch on the exit code rather than on whether
stdout parsed. If a CI step relied on dg always exiting 0 (every command
did, before 0.3.0), it will now fail where it previously passed silently.
Three explicit ways to skip every prompt and run with defaults — useful from a real terminal where auto-detection wouldn't otherwise trigger:
# Global flag (before any command, or after a leaf command)
dg --non-interactive listen recording.wav
dg listen --non-interactive recording.wav
# Environment variable (good for whole scripts)
CI=1 dg listen recording.wavAlso recognised: --agent-friendly (alias intended for AI coding tools — same
effect plus JSON metadata output). dg also detects AI coding agents from the
variables they set (AI_AGENT, CLAUDECODE, CODEX_SANDBOX, GEMINI_CLI
and others). dg help agent-mode prints the full table with its sources,
what your shell matched, and how to turn it off. DG_AGENT=1 forces agent
mode and DG_AGENT=0 turns it off for output and prompts; it doesn't change
the config file rules for agent sessions (see dg help agent-mode).
NO_COLOR only turns color off.
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> # RemoveCreate your own — see the plugin example.
A plugin can't replace a built-in command such as login or debug audio
(or its hidden alias debug-audio). dg runs the built-in without loading the
plugin. The warning that names the plugin's package shows whenever dg looks
for plugins: on dg --help, dg plugin list and command names dg doesn't
know. Use dg plugin list to see refused or shadowing plugins.
A plugin whose entry point is named like a built-in command is skipped before
it's imported, so none of its code runs; give the entry point a different name.
To use a plugin's version anyway, list the command in the user config file
at its standard location (~/.config/deepctl/config.yaml on Linux, or
$XDG_CONFIG_HOME/deepctl/config.yaml when XDG_CONFIG_HOME is set;
~/Library/Application Support/deepctl/config.yaml on macOS;
%LOCALAPPDATA%\deepgram\deepctl\config.yaml on Windows):
plugins:
allow_override:
- login
- debug audiodg reads this setting only from that file, never from deepgram.yaml or a
--config file. Only allow a plugin you trust: it receives everything you
pass to that command, including API keys.
Priority: CLI flags > environment variables > project deepgram.yaml > user
config. A project deepgram.yaml is read after the user config, but it can set
only output.* settings and a regional Deepgram base_url (see below).
The API key is the exception: dg uses --api-key, then the key dg login saved
in your system keyring, then DEEPGRAM_API_KEY, then an api_key in the config
file (where dg login saves it when no keyring is available).
dg sends your API key only to Deepgram API hosts, to hosts you list in
api.allowed_hosts in your own config.yaml, or to DEEPGRAM_BASE_URL (not in
an AI agent session). Anything else is refused before a request is made. Hosts
must use https: plain http works only for localhost, 127.0.0.0/8 and [::1]. For
a proxy or self-hosted deployment, add its host (and port, to approve only that
port):
api:
allowed_hosts:
- my-proxy.example.com
- localhost:8080A project's deepgram.yaml can't set credentials, a project ID, a profile or a
non-Deepgram base_url, and can't approve hosts.
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 profileFor structured output, use --output json|yaml|table|csv after leaf commands
that do not define their own output option, or before any command as a global
flag: dg --output json <command>. dg speak --output FILE writes audio to
FILE, so use dg --output json speak ... for Speak's structured output.
This version of dg sends no telemetry: no error reports, usage data or other telemetry, whether a command succeeds or fails. dg still contacts the Deepgram API for the commands you run, and pypi.org to check for updates.
The DEEPCTL_TELEMETRY_DISABLED environment variable and the telemetry.enabled setting in config.yaml are still accepted, and the new --no-telemetry flag is accepted too, but none of them has an effect in this version. DEEPCTL_TELEMETRY_DSN is now ignored unless it points at the local machine, which is for tests. The last line of dg --help says that dg sends no telemetry.
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)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/ # Local stdio MCP server for deepctl: search Deepgram's documentation from AI editors
│ ├── 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/ # Error reporting for deepctl; this version sends no telemetry
├── tests/ # Integration tests
└── Makefile # Development tasks
| 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 |
Local stdio MCP server for deepctl: search Deepgram's documentation from AI editors |
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 |
| 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 |
Local stdio MCP server for deepctl: search Deepgram's documentation from AI editors |
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 |
Error reporting for deepctl; this version sends no telemetry |
Merging conventional commits to main
triggers release-please to open
a release PR. Every first-party package is versioned in lockstep: merging that
PR creates one tag and publishes every package at the same version to PyPI.
- Python 3.10+
- Cross-platform: Linux, Windows, macOS
- Fork the repository
uv sync --group devmake dev(formats, lints, tests)- Submit a pull request
See CONTRIBUTING.md for the contributor workflow.
MIT