Skip to navigation

Configuration & environment

Deepgram CLI configuration reference for global options, config.yaml paths, deepgram.yaml, environment variables, and precedence.

The dg CLI reads settings from global options, a user config file, an optional project file, and environment variables. This page lists each one and the order the CLI applies them in.

Global options

Global options go before the subcommand: dg -o json listen audio.mp3.

OptionShortDefaultEffect
--output-oHuman-readable textOutput format: json, yaml, table, or csv. On dg listen, json and yaml print the server’s real response body rather than an SDK-shaped one, table/csv are no-ops, and a dg listen-only text format (placed after the subcommand, not here) prints the transcript alone; see Speech-to-text
--quiet-qOffSuppress non-essential output
--verbose-vOffEnable verbose output
--profile-pThe active profileConfiguration profile to use
--config-cThe user config filePath to another configuration file
--base-urlnonehttps://api.deepgram.comAPI base URL; REST and WebSocket endpoints derive from it. Also set by DEEPGRAM_BASE_URL
--api-keynonenoneAPI key that overrides login, profile, and environment credentials
--timingnoneOffShow performance timing
--timing-detailednoneOffShow detailed performance timing
--non-interactivenoneOffSkip interactive prompts and use defaults

--base-url defaults to https://api.deepgram.com.

  • -o, -q, and -v also work after the subcommand 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. On dg plugin and dg skills subcommands, put -o before the subcommand.
  • On the root dg, -p means --profile; on dg login and the account commands (dg keys, dg members, dg usage, dg billing, dg requests), -p means --project-id.

Config file location

  • On Linux the file is ~/.config/deepctl/config.yaml; on macOS, ~/Library/Application Support/deepctl/config.yaml; on Windows, %LOCALAPPDATA%\deepgram\deepctl\config.yaml.
  • The CLI copies a config file from the older deepgram directory into the deepctl directory automatically.
  • dg -c PATH reads another file for one command.

Project file

A deepgram.yaml file in the working directory (or a file passed with a non-default -c/--config) is loaded after the user config, but it can only override a restricted subset of settings: an allowlisted set of output.* fields, the profiles section (itself filtered the same way), and base_url, and only when base_url is a regional Deepgram API URL. Credentials, a non-regional base_url, and any other key are dropped, each with its own WARN:/HINT: pair on stderr naming the rejected key (never its value); stdout stays clean. Keep API keys out of a deepgram.yaml you commit regardless; the system keyring, which dg login uses by default, is the place for keys.

Config schema

These are the keys the CLI reads:

# Profile used when no active profile is set
default_profile: default
# Profile used by every command until you switch; dg login writes it
active_profile: default
# One entry per profile
profiles:
default:
# Present only when no system keyring is available
api_key: YOUR_API_KEY
project_id: YOUR_PROJECT_ID
base_url: https://api.deepgram.com
# Automatic update check: daily (default), weekly, or never
update:
check_enabled: true
check_frequency: daily
# Set by dg ffprobe --path
tools:
ffprobe_path: /usr/bin/ffprobe
# Telemetry: unhandled-exception reports to a loopback DEEPCTL_TELEMETRY_DSN only
telemetry:
enabled: true
  • dg login writes active_profile.
  • update.check_frequency takes daily (the default), weekly, or never; update.check_enabled: false turns the check off.
  • dg ffprobe --path sets tools.ffprobe_path, and dg ffprobe --reset clears it.

Environment variables

VariableEffect
DEEPGRAM_API_KEYAPI key
DEEPGRAM_PROJECT_IDProject ID for key, member, usage, billing, and request commands
DEEPGRAM_PROFILESets default_profile; selects a profile only when no active profile is set
DEEPGRAM_BASE_URLAPI base URL
DEEPCTL_TELEMETRY_DISABLED1, true, or yes turns telemetry off
DEEPCTL_TELEMETRY_DSNSets the telemetry destination to a loopback address only (localhost or a loopback IP, for tests and local sinks); a non-loopback value is ignored, and with no DSN, telemetry sends nothing regardless of the other settings below
DEEPCTL_TELEMETRYlog writes a telemetry report to stderr instead of sending it; off disables it, the same as DEEPCTL_TELEMETRY_DISABLED=1
DO_NOT_TRACK1 disables telemetry
DEEPCTL_SKILLS_REFGit ref of deepgram/skills that dg skills installs
DEEPCTL_FORCEInstall scripts: reinstall even when the CLI is installed
DEEPCTL_VERSIONInstall scripts: install a specific version
CItrue or 1 turns on Agent-Friendly Mode and disables telemetry

DEEPGRAM_PROFILE selects a profile only when no active profile is set; dg login sets one. To choose a profile per command, pass --profile (-p); to change the active one, run dg profiles --switch <name>.

If DEEPGRAM_API_KEY, DEEPGRAM_PROFILE, DEEPGRAM_PROJECT_ID, or DEEPGRAM_BASE_URL still holds an unexpanded ${...} placeholder (for example, a CI template variable that was never substituted), the CLI ignores it rather than using the literal placeholder text, and prints WARN: dg ignored <VARIABLE>: it holds a placeholder that was never filled in (${…}). on stderr. The variable is then treated as unset, falling through to the next credential source.

Precedence

For the API key, the CLI uses the first source that holds one:

  1. --api-key (global flag)
  2. The active profile’s key in the system keyring
  3. DEEPGRAM_API_KEY
  4. The active profile’s key in config.yaml (used only when no keyring is available, which is when dg login stores it there)

An expired browser-login credential counts as absent at step 2 or 4; see Authentication. This order is unchanged from earlier releases, with one addition: off a terminal, a system keyring that doesn’t answer within 2 seconds is skipped at step 2, falling through to the next source, with WARN: The system keyring didn't answer within 2 s, so dg didn't use the key stored there. on stderr.

For the project ID, the order is -p (--project-id) on the command, then DEEPGRAM_PROJECT_ID, then the profile’s project_id.

dg whoami prints the key’s source (system keyring, config file, or DEEPGRAM_API_KEY (env)).