-o json is not honoured by most commands: human output precedes JSON on stdout, breaking pipes

[GregHolmes]

Summary

For most commands, -o json appends JSON after the human-readable rendering instead of replacing it, and the status lines / Rich tables go to stdout rather than stderr. Any | jq pipeline against those commands therefore fails, even though the JSON is present further down the stream.

listen and speak behave correctly. Everything else I tested does not.

Reproduction

$ dg -o json projects 2>/dev/null | head -c 130
Fetching projects...
Found 1 project(s):
  • <name>
    ID: <uuid>

The JSON does eventually arrive — it just isn't first:

command	stdout bytes	JSON starts at byte	human text before it
dg -o json models	114,720	37,012	37 KB Rich table
dg -o json keys	2,255	1,252	Fetching API keys... + table
dg -o json usage	1,660	877	Fetching usage for current month... + summary
dg -o json projects	331	124	Fetching projects... + list
dg -o json read "good" --sentiment	—	after	Analyzing text..., Sentiment: positive (0.92)

Which commands are affected

honours -o json (JSON only on stdout)	does not
listen, speak	read, models, projects, keys, billing, usage, requests, members

dg -o json listen audio.mp3 \| jq '.results.channels[0].alternatives[0].transcript' works exactly as documented. The equivalent for projects, keys, models, etc. does not.

models additionally ignores the format entirely — -o json, -o yaml and -o csv all render the same table:

$ for f in json yaml csv; do dg -o $f models | head -c 30; done
   Deepgram Models   ...      (identical for all three)

Why it matters

This contradicts two promises made on cli.deepgram.com and in llms.txt:

Status messages always go to stderr to keep stdout clean.

Every command writes structured data to stdout and diagnostics to stderr. Switch formats with -o json or let it auto-switch when piped.

It also affects agent use: --agent-friendly and the auto-JSON-when-piped behaviour are advertised for scripting, and a polluted stdout defeats both. Note stdout was a pipe in every case above (piped to head), so the auto-switch didn't rescue it either.

Expected

With -o json (or when stdout is not a tty):

1. stdout carries only the serialised payload
2. status/progress/tables go to stderr
3. -o yaml / -o csv are likewise respected, including by models

Notes

• Found while validating the landing-page command examples (fix: correct web command examples, document Flux TTS/STT, and honor -o json across account commands #97).
• Not diagnosed further, but the split looks like commands that render via a shared human formatter before the result object is serialised — listen/speak return their result without that pre-render, which is why they behave.
• Environment: deepctl 0.2.27 (editable install from main @ 76ccdaf), macOS, Python 3.11.

[GregHolmes]

Re-tested against 0.3.0 (PyPI wheel, clean venv, real key). The reported behaviour is fixed — every command listed above now writes only the serialised payload to stdout, with status output on stderr:

command	stdout	whole stream parses as JSON	JSON starts at byte	status output
dg -o json models	77,708 B	yes	0	stderr
dg -o json projects	207 B	yes	0	stderr
dg -o json keys	1,003 B	yes	0	stderr
dg -o json usage	989 B	yes	0	stderr
dg -o json billing	1,857 B	yes	0	stderr
dg -o json members	309 B	yes	0	stderr
dg -o json requests	2,627 B	yes	0	stderr
dg -o json read "..." --sentiment	163 B	yes	0	stderr

The models format bug is fixed too — the three formats now produce genuinely different serialisations rather than the same table:

$ for f in json yaml csv; do dg -o $f models | wc -c; done
   77708      # json
   49112      # yaml
   56124      # csv

Closing as fixed. Two things raised in the "Why it matters" section survive, and I've split them out rather than leaving this open:

1. The failure path is still polluted — #104. The fix landed on the success path only. With -o json and an invalid key, dg projects --list writes three lines of English prose to stdout, exit 1, stderr empty. Root cause is deepctl_core/auth.py:19 declaring a bare Console(), which is the exact scenario get_status_console()'s docstring warns about. Five commands reproduce.

2. The auto-JSON-when-piped promise on cli.deepgram.com is inaccurate. This issue quoted:

Switch formats with -o json or let it auto-switch when piped.

That doesn't hold, and it isn't a regression — it describes behaviour the CLI has never had. JSON auto-selection is gated on is_agentic(), which needs a score of 3; a non-tty stdout scores 1:

$ env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT -u CI TERM=xterm dg projects | head -c 30
Found 1 project(s):

Worth noting for anyone re-testing this: the auto-switch does fire under Claude Code, Codex, or CI=true, because those are hard signals in is_agentic(). My first attempt at the check above looked like it passed for exactly that reason. A plain cmd | jq in an ordinary shell does not trigger it.

That one is a copy fix on the launch site rather than a CLI change, so I haven't opened a CLI issue for it. The equivalent claim has been corrected on developers.deepgram.com in deepgram/deepgram-docs#1128.