Authentication
Interactive login
dg login opens a Deepgram sign-in page and shows a one-time code to confirm. It stores a time-limited Deepgram credential in your operating system keyring, or in the deepctl config file when no keyring is available.
The keyring entry is service com.deepgram.dx.deepctl, account api-key.<profile>, which helps when you troubleshoot a headless Linux machine.
After a successful login, dg login offers to install the Deepgram skills; see Skills.
Finish login from an agent session
dg login --complete finishes a browser device-flow login you started elsewhere: approve the sign-in in your browser, then run dg login --complete from an AI-agent session or script to pick up the resulting credential. This is a separate path from dg login --api-key below, with its own checks before it stores a key.
Credential expiry
- When the credential expires and no
--api-keyorDEEPGRAM_API_KEYsupplies another key, commands stop withYour Deepgram credential has expired. Run `dg login` again.; rundg loginto get a new credential. - When
DEEPGRAM_API_KEYis set, the CLI skips an expired browser credential and uses the environment key without the message. dg whoamiprints anExpires:line, anddg -o json whoamireportscredential_expires_at.- Upgrading from a CLI release before 0.4.0 needs one
dg loginfor browser-login sessions. - For CI, use
DEEPGRAM_API_KEY. Keys stored withdg login --api-keyand keys inDEEPGRAM_API_KEYcarry no CLI-side expiry; such a key lasts until it is deleted or reaches its own expiration date.
Store a key without the browser
On a machine with no browser, set DEEPGRAM_API_KEY as the next section shows; every command reads it, so nothing needs storing. To store a key with a profile instead, pass it to dg login:
A key typed on the command line stays in your shell history and is visible in process listings while the command runs.
A real key is accepted outright; -f (--force-write) is no longer needed just to get past a key-format check. The CLI checks the project ID against the key:
- If the API reports the project ID as not found,
dg loginprintsWarning: Project ID '<id>' not found. API key will still be stored., stores the key without the project ID, and exits0. Its summary still shows the ID you passed; rundg whoamito see the stored project ID. - If the key is invalid (
401) or cannot access the project (403), the login fails with exit code1and stores nothing.
If DEEPGRAM_API_KEY is already set in your shell, dg login --api-key stops instead of silently saving a profile that would be used ahead of it: it prints ERROR: DEEPGRAM_API_KEY is set, and logging in saves a profile that dg will use instead of it., exits 1 with confirmation_required, and stores nothing unless you add --yes.
On dg login, -p is --project-id and -k is --api-key; on the root dg, -p is --profile.
Environment variable
For scripts and CI/CD, set your API key as an environment variable:
API key flag
The global --api-key flag supplies a key for one command and overrides every other credential:
The flag leaves the key in your shell history and in process listings while the command runs. For a key you keep, use dg login or DEEPGRAM_API_KEY.
When more than one credential is present, the CLI picks one by a fixed order; Configuration & Environment lists it. dg whoami shows which credential the CLI is using and where it came from.
Named profiles
Use multiple API keys with named profiles:
Each profile holds its own keyring credential (when available) and configuration values. dg login --profile development also makes development the active profile, so later commands use it until you switch.
On a machine with no system keyring, dg profiles --switch stops with Error accessing credentials:; pass --profile <name> on each command instead.
dg profiles --list shows each profile that has a stored key by its last 4 characters (the same masking as dg whoami’s api_key_masked), never the raw value.
Log out
Run dg logout --help for each flag’s exact behaviour.
Check Auth Status
dg whoami reports the active profile (or the one --profile names), a masked API key, its credential source, and the configured project ID. The credential source is one of system keyring, config file, DEEPGRAM_API_KEY (env), or not set. dg -o json whoami returns the fields authenticated, profile, api_key_masked, key_source, project_id, base_url, and credential_expires_at.
CI/CD usage
Set DEEPGRAM_API_KEY from your CI secret store: