Configuration & environment
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.
--base-url defaults to https://api.deepgram.com.
-o,-q, and-valso work after the subcommand on most commands (dg read ... -o json). Ondg speak,-o/--outputafter the subcommand still sets the output file path but is deprecated; use--out-fileinstead. Ondg pluginanddg skillssubcommands, put-obefore the subcommand.- On the root
dg,-pmeans--profile; ondg loginand the account commands (dg keys,dg members,dg usage,dg billing,dg requests),-pmeans--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
deepgramdirectory into thedeepctldirectory automatically. dg -c PATHreads 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:
dg loginwritesactive_profile.update.check_frequencytakesdaily(the default),weekly, ornever;update.check_enabled: falseturns the check off.dg ffprobe --pathsetstools.ffprobe_path, anddg ffprobe --resetclears it.
Environment variables
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:
--api-key(global flag)- The active profile’s key in the system keyring
DEEPGRAM_API_KEY- The active profile’s key in
config.yaml(used only when no keyring is available, which is whendg loginstores 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)).