docs: fix dg listen examples and drop deprecated dg transcribe references#53
Merged
lukeocodes merged 1 commit intomainfrom May 4, 2026
Merged
Conversation
…nces Three doc bugs surfaced by Hasan during launch-blog end-to-end testing. 1. dg transcribe references on cli.deepgram.com, root README, and AGENTS.md. dg transcribe is a hidden, deprecated alias for the unified dg listen command and still works for backwards compat, but the documented examples should use dg listen. Earlier commit 4676d34 did partial cleanup; this finishes it. 2. -o/--output is defined on the cli group, not on subcommands, so `dg listen audio.mp3 -o json` is rejected by Click. The flag has to come before the subcommand: `dg -o json listen audio.mp3`. Examples in the listen --help text, README, AGENTS.md, and landing page all had the flag in the wrong position. 3. The example in dg listen --help used jq path `.full_result.results.channels[0]...`, but the JSON output (see listen command.py output_result) writes result.full_result directly to stdout, so the actual top level is `.results.channels[0]...`. The bogus `.full_result.` prefix returned null when run verbatim. Files touched: - README.md: 4 example snippets - AGENTS.md: 1 flow example, plus the command-catalog row (replaced the dg transcribe row with the canonical dg listen row, noting the alias) - web/src/pages/index.astro: 6 examples spanning the JSON-LD FAQ, hero, CLI catalog, and the "JSON pipeline" demo strip - packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py: the examples list entry and the agent_help string No code-logic changes. Lint clean: ruff format --check, ruff check, mypy --strict against src/ + packages/*/src all pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three doc bugs surfaced during Hasan's end-to-end command testing for the launch blog.
dg transcribereferences in user-facing docsweb/src/pages/index.astro,README.md,AGENTS.md4676d34replaced somedg transcribereferences withdg listenbut missed several.dg transcribeis now a hidden, deprecated alias fordg listen(kept for backwards compat) and shouldn't be advertised.dg listen ... -o jsonrejected by ClickREADME.md,dg listen --helpexamples, listenagent_helptext-o/--outputis defined on the cli group atsrc/deepctl/main.py:127, not on subcommands. Correct invocation isdg -o json listen audio.mp3. The wrong-position form 401s with "no such option: -o".jq '.full_result.results.channels[0]...'returnsnulldg listen --helpexamplecommand.py:1062) writesresult.full_resultdirectly to stdout, so the actual top level is.results.channels[0].... The.full_result.prefix in the example was wrong.Bugs (2) and (3) compound: running the example verbatim (
dg listen audio.mp3 -o json | jq '.full_result.results...') fails twice. Click rejects-oat the subcommand position, jq parses the failure output and returns null, and the user concludes the CLI is broken.What changes
README.md— 4 example snippets (dg transcribe→dg listen,-o jsonrepositioned)AGENTS.md— 1 flow example. Catalog row updated: replaced thedg transcriberow with the canonicaldg listenrow, with a note thatdg transcribeis a hidden deprecated alias.web/src/pages/index.astro— 6 examples across the JSON-LD FAQ, hero, CLI command catalog, and JSON-pipeline demo strip.packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py— the entry inexamples(jq path + flag position) and theagent_helpstring (-o jsonrepositioned, alias deprecation note clarified).No code-logic changes. The fix is purely the documented invocations and jq path.
Verification
ruff format --check src/ packages/*/srccleanruff check src/ packages/*/srccleanmypy --strict src/ packages/*/srcclean (112 source files)dg transcribereturns only intentional alias-documentation lines (the catalog row noting the alias, theagent_helpstring mentioning the alias, the listen module's docstring noting transcribe is registered as an alias)listen ... -o jsonreturns nothing in the wrong-position formOut of scope
The listen command's JSON output structure is what it is, but worth flagging for a future pass: when
result.full_resultis set we strip the wrappingListenResultmodel and emit the raw Deepgram response. Whenfull_resultisNone(e.g. live caption mode after streaming) we emit the wrapping model. So the JSON shape isn't 100% consistent across modes. Not changing here, but worth tracking.Companion follow-up
The
dg transcribepackage (deepctl-cmd-transcribe) remains in the repo as a deprecated, hidden alias. We can drop it in a future major release. Not part of this PR.