fix: model-catalog field mapping and legacy flags, global-option placement, and whoami source label

[darrenapfel]

This change was built by a coding agent working from a developer-experience review, and was validated as described at the end. It contains three independent fixes; they are separate commits and can be reviewed or split independently.

1. The models catalog rendered empty IDs and languages, dropped the canonical name, and presented legacy models without warning.

dg models read the API's uuid and language fields, but the Deepgram Python software development kit renames uuid to uuid_ in its generated response classes, and the API reports languages as a list — so every row displayed a blank ID and a blank language. The command also dropped canonical_name, which is the exact value a request's model parameter takes (the catalog showed "agathe" but a request needs "aura-2-agathe-fr"). This change reads both field spellings, joins the language list, and adds canonical name and architecture to the table and the JSON output.

Two related additions:

• The legacy models named conversationalai and 2-conversationalai are now flagged deprecated, with a note steering users to nova-3 and stating that no model named nova-3-conversational exists. Support data shows paying customers composing that nonexistent name; the legacy entry in the catalog is the plausible source of the composition. The API sends no deprecation field, so the flag is a small map inside the command — if the platform later adds deprecation metadata to GET /v1/models, the map should be replaced by it.
• When the API returns zero models in a requested category, the command now warns on the error stream instead of silently presenting half a catalog. We observed a live session in which the endpoint returned zero text-to-speech models; a user seeing that output had no way to tell it was an anomaly.

2. Global output options silently failed after the subcommand.

dg models -o json failed with "No such option '-o'" while dg -o json models worked, because the parser reads group-level options only before the subcommand name. Every generated command now carries pass-through copies of -o/--output, -q/--quiet, and -v/--verbose that apply the same effect from the subcommand position. A copy is added only when the command does not define that option itself — dg speak --output names an audio file and keeps its own meaning. For the global options that cannot safely pass through (--api-key, --profile, --timing, and the rest), the error now includes a hint naming the working placement. The published exit-code contract (1 = error, 2 = user interrupt) is unchanged and remains covered by the existing tests.

3. whoami labeled an environment-sourced key "config file", and corrupted JSON output.

The configuration loader copies DEEPGRAM_API_KEY into the active profile at load time, so whoami saw a profile key and reported "config file" for a key that came from the environment. The label now reports "DEEPGRAM_API_KEY (env)" when the profile key matches the environment value — which is also the key the authentication path actually uses in that state. Separately, whoami printed its human-readable block even in JSON output mode, breaking dg -o json whoami for scripts; the block is now guarded by the default output format, the same pattern pull request #97 applied to the other account commands.

Validation. The full test suite passes (1,109 passed, 6 skipped; the one failure, a file-timestamp test in deepctl-shared-utils, fails identically on unmodified main). Seventeen new unit tests cover the field mapping, the deprecation flags, the empty-category warning, the pass-through options and their collision rule, the placement hint, and the whoami label. ruff check, ruff format --check, and mypy pass on all 115 source files. Every changed behavior was also run live against api.deepgram.com on a test account: the catalog lists 441 speech-to-text and 102 text-to-speech models with IDs, languages, canonical names, and 7 deprecated-flagged entries; dg models -o json and dg models -t tts -o json parse cleanly; dg speak --help keeps its own --output; the misplaced-global hint renders; and dg whoami reports the environment source with clean JSON.

🤖 Generated with Claude Code