Getting started
By the end of this guide you’ll have dg installed and logged in, a transcript of one audio file printed in your terminal, one WAV file of generated speech on disk, and a starter app scaffolded by dg init with your API key in its .env.
The dg CLI transcribes files, streams live audio, synthesizes speech, analyzes text, and manages your Deepgram account from the terminal.
The Deepgram CLI command is dg; the PyPI package that installs it is deepctl, and it needs Python 3.10 or later. Install it with curl -fsSL https://deepgram.com/install.sh | sh, brew install deepgram/tap/deepgram, or pip install deepctl (also pipx install deepctl, uv tool install deepctl, and npm install -g @deepgram/cli). dg listen defaults to Nova-3 (nova-3); --model flux-general-en selects Flux STT on streaming input (--mic or stdin). dg speak defaults to the Flux TTS voice flux-alexis-en. On a standard install, dg --help lists 24 commands; installed plugins add their own. For voice agents, use the Voice Agent API or scaffold a starter with dg init --list --search voice-agent.
Prerequisites
- Python 3.10 or later
- A Deepgram API key (get one free)
Quick start
With recording.wav holding the spacewalk sample (https://dpgr.am/spacewalk.wav), dg listen prints a summary table and the transcript, and dg speak reports the saved file. Both exit 0; byte counts and timings vary per run:
Scaffold a starter app
dg init clones a template from the gallery at templates.dx.deepgram.com, writes your DEEPGRAM_API_KEY into the app’s .env, and can run its setup and start steps. The templates are finished apps from the deepgram-starters organization. dg init needs git, node, npm, make, and curl on your PATH; if any is absent, it prints Missing required tools: with one line per missing tool and exits 1 before cloning.
On a terminal, dg init prompts you to run the template’s setup (make init) and start it; answer the prompts, or pass --no-install and --no-start to skip them without being asked. Outside a terminal, including any AI-agent session, nothing can answer that prompt, so dg init needs an explicit flag before it runs setup or starts the app:
--yesconfirms setup only. It’s the only way to do this inside an AI-agent session.--installconfirms setup outside an AI-agent session (use--yesinside one).--startconfirms the start step; it doesn’t run on its own. Combine it with--yesor--installto both set up and start in one command:dg init node-transcription --yes --start.- Without one of these,
dg initexits1withconfirmation_requiredinstead of running setup or starting the app.
Other notes:
dg init --listprints the full set of available slugs, includingfastapi-transcription,node-live-transcription, andnode-voice-agent.--dirsets the target directory.- Re-running
dg initon a clone it already started resumes from where that attempt left off. - When setup is skipped, the CLI ends with
To set up: cd <dir> && make init. - Without a GitHub SSH key, the
make initthatdg initruns fails withHost key verification failedon starters whose.gitmodulesuse SSH URLs,frontend/andcontracts/stay empty, anddg initstill printsDone! ... is readyand exits0. Finish the checkout withgit -c url."https://github.com/".insteadOf="git@github.com:" submodule update --init --recursive, then runmake initagain. - An unknown slug exits
1withTemplate not found: <slug>. - Missing required tools exits
1before cloning, for example{"status": "error", "message": "Missing tools: node, npm, make", ...}.
Core workflows
Transcribe audio
Text-to-speech
-o/--output still works in place of --out-file on dg speak, but it’s deprecated and, unlike --out-file, overwrites an existing file without asking. Under a hard agent signal (see Agent-Friendly Mode below), dg speak only reads piped stdin when the text argument is literally -, and refuses to write audio into a pipe; both cases exit 1 with "code": "invalid_argument". The pipe-to-ffplay example above is for an interactive terminal; it doesn’t work under a hard agent signal.
Text intelligence
Account management
Key, member, usage, and billing commands act on one project: set it with dg projects --set-default <project-id> or export DEEPGRAM_PROJECT_ID. Without one they exit 1 with Project ID is required for this command. Account commands take the action as a flag. Run dg keys --help or dg projects --help for the full set.
Output formats
Output defaults to human-readable text. -o (--output) takes json, yaml, table, or csv:
dg listen is a partial exception: it prints a summary table and the transcript by default. -o json and -o yaml print the server’s prerecorded response body as sent, formatted as JSON or YAML; -o table and -o csv are no-ops on dg listen and print the same default summary instead. If you have a script that expects the older, SDK-parsed JSON shape (indented, with datetime-style timestamps), set DEEPCTL_LISTEN_JSON=sdk to restore it.
dg listen also takes a local text format for the transcript alone, and it goes after the subcommand: dg listen audio.mp3 -o text. It isn’t a valid value for the global -o placed before the subcommand (dg -o text listen audio.mp3 fails with Invalid value for '--output' / '-o').
-o works before the subcommand (dg -o json read ...) or after it on most commands (dg read ... -o json). On dg speak, -o/--output after the subcommand still sets the output file path but is deprecated; use --out-file instead (see Text-to-speech). On dg plugin and dg skills subcommands, put -o before the subcommand. The same placement rule covers -q (--quiet) and -v (--verbose). Configuration & Environment lists every global option.
In an AI-agent session, a prerecorded dg listen result over 64 KiB saves to a file under ~/.deepctl/results/ instead of printing, with a summary on stdout; pass --full-output to print the full payload to stdout anyway.
dg listen also takes --timeout for files and URLs (not the microphone or live stdin): seconds to wait at each step (connecting, sending, the response) before giving up, not a cap on the whole run. Default 300, minimum 1.
Agent-Friendly Mode, described below, selects JSON without -o. A piped stdout alone does not trigger it.
For dg -o json listen, parse errors and progress go to stderr, so redirecting stderr leaves the payload on stdout:
On most failures, -o json writes a JSON object to stdout and the command exits 1. Some errors write only to stderr and leave stdout empty, such as a missing project ID. The JSON object takes one of three shapes:
{"status": "error", "message": "..."}for most in-command errors, such as a missing input file.{"error": "...", "status": "error", "code": "...", "hint": "...", "next_step": ..., "schema_version": 1, "details": {...}}for most failures before the command runs or that the CLI can diagnose, such as an invalid API key or a bad argument.codeis a short, machine-readable reason (for exampleauth_invalidorinvalid_argument);hintandnext_stepsuggest a fix;schema_versionmarks the shape so scripts can tell it apart from the older one below.- The older, bare
{"error": "...", "status": "error"}shape, with nocode, still appears for some failures, though most cases that used to return it now return the coded shape above instead.
Branch on the exit code first, then read the reason with .message // .error (for example, jq -r '.message // .error'); that read degrades safely across all three shapes. Read .code too if a script needs to match on a specific failure rather than its message text. Treat empty stdout with a nonzero exit code as an error whose reason is on stderr.
Exit codes
Most command and usage outcomes use these exit codes, so scripts and CI steps can branch on them:
dg plugin remove, dg update, and dg skills install return 2 on cancel and 1 on failure.
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 start surfacing failures it swallowed before. dg listen --mic, dg listen reading live audio from stdin, and dg mcp handle Ctrl-C themselves and exit 0, so an interrupt exit code is unreliable for those three cases. One more exception: when dg login or dg init needs a confirmation it can’t get (no terminal, and no -f/--yes/--install), it exits 1 with confirmation_required rather than the exit 2 a declined confirmation would otherwise get.
Agent-Friendly Mode
When the CLI detects an AI agent or non-interactive environment, it:
- Disables interactive prompts
- Defaults to JSON output
It switches on for any one of these hard signals:
- The environment variables
CLAUDECODE,CLAUDE_CODE_ENTRYPOINT,CODEX_SANDBOX, orCODEX_SANDBOX_NETWORK_DISABLED,OR_APP_NAME=Aider, anOR_SITE_URLcontainingaider, orCI=trueorCI=1 - The
--non-interactiveor--agent-friendlyflag
It also switches on when any 3 of these soft signals hold: stdin is not a TTY, stdout is not a TTY, TERM is unset or dumb, NO_COLOR is set. A cron job, systemd unit, or docker run without -t can meet three soft signals and switch to JSON. A piped stdout alone does not trigger it.
This list isn’t exhaustive. For the complete, current signal table (every coding agent and CI system the CLI recognizes, including OpenCode, and the source each check comes from), run dg help agent-mode rather than relying on a hand-copied list.
To force the mode on:
On a subcommand, --agent-friendly prints that command’s parameter documentation as JSON and exits without running it. The JSON carries the fields command, description, agent_hints, examples, requires_auth, requires_project, non_interactive, output_formats, and parameters.
Command reference
On a standard install, dg --help lists 24 commands. dg transcribe is a hidden alias for dg listen.
What the CLI covers
- Installation: install the Deepgram CLI on macOS, Linux, and Windows, and keep it updated
- Authentication: log in, store keys, and manage profiles
- Configuration & Environment: global options, config files, environment variables, and precedence
- Speech-to-Text: transcribe audio files, URLs, microphone, and stdin
- Text-to-Speech: synthesize speech with Flux TTS and Aura-2
- Text Intelligence: analyze text for sentiment, topics, summaries, and intents
- Account Management: manage projects, API keys, team members, usage, and request history
- MCP Server: run
dg mcpas a local bridge to the docs MCP server - Skills: install the Deepgram skills into your coding agents
- Shell Completion: enable tab completion for bash, zsh, and fish
- Plugin System: extend the CLI with plugins, and build and publish your own
- Troubleshooting: error messages and the
dg debugdiagnostics
Next steps
- Install the CLI: more installation methods, including pip, pipx, uv, and Homebrew
- Authenticate: browser login, API keys, and profiles
- Speech-to-Text: full transcription reference
- Text-to-Speech: full text-to-speech reference