Summary
The landing page tells readers that output auto-switches to JSON when stdout is piped. It doesn't. JSON auto-selection is gated on is_agentic(), and a plain pipe doesn't reach the threshold. The page contradicts itself: the agent-mode section describes the behaviour correctly, the pipes section does not.
Affected copy
web/src/pages/index.astro:
- :672 — "… auto-switch when piped. Plays nicely with every UNIX tool you already know."
- :676 —
['JSON / YAML / table / CSV', 'Explicit output format, or auto-JSON when piped.']
- :677 —
['Errors to stderr', 'Clean stdout channel. No surprises in pipes.']
Why it's wrong
deepctl_core/output.py:26-68. Hard signals return True immediately (--non-interactive, --agent-friendly, CI, CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, CODEX_SANDBOX, Aider vars). Otherwise a score is accumulated and 3 points are required:
| signal |
points |
| stdin not a tty |
1 |
| stdout not a tty |
1 |
TERM unset or dumb |
1 |
NO_COLOR set |
1 |
cmd \| jq in an ordinary shell scores 1 (stdout not a tty), or 2 if stdin is also redirected. TERM is set in any normal terminal, so the third point doesn't arrive. Verified on 0.3.0:
$ env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT -u CI TERM=xterm dg projects | head -c 30
Found 1 project(s):
Human-readable output, into a pipe, with -o absent.
⚠️ Testing note: the auto-switch does fire under Claude Code, Codex, Aider, or CI=true, because those are hard signals. Testing this from an agent shell or CI job will appear to confirm the promise. Unset those vars to see the real behaviour — my own first check gave a false pass for exactly this reason.
What's already correct — please leave these
- :645 — "Auto-detects Claude Code, Aider, and Codex. Disables prompts, routes status to stderr, switches to JSON — no flags needed." Accurate: it attributes JSON to agent detection.
web/public/llms.txt:34 — same correct framing.
web/public/llms-full.txt has no matching copy.
Suggested fix
Attribute the switch to agent/CI detection rather than piping, e.g.:
- :672 — "… auto-switches to JSON in agent and CI environments."
- :676 —
'Explicit output format, or auto-JSON in agent and CI contexts.'
For :677, note that "Clean stdout channel. No surprises in pipes." is also currently overstated — see #104, where an auth failure writes English prose to stdout with -o json. Either soften it now or land #104 first and keep the claim.
Context
Same class as the command-example corrections in #97. Found while correcting the equivalent claim on developers.deepgram.com, which stated "When stdout is a pipe, the CLI automatically switches to JSON" and has now been fixed (deepgram/deepgram-docs#1128). Related: #98 (closed, success-path stdout pollution), #104 (failure-path stdout pollution).
Summary
The landing page tells readers that output auto-switches to JSON when stdout is piped. It doesn't. JSON auto-selection is gated on
is_agentic(), and a plain pipe doesn't reach the threshold. The page contradicts itself: the agent-mode section describes the behaviour correctly, the pipes section does not.Affected copy
web/src/pages/index.astro:['JSON / YAML / table / CSV', 'Explicit output format, or auto-JSON when piped.']['Errors to stderr', 'Clean stdout channel. No surprises in pipes.']Why it's wrong
deepctl_core/output.py:26-68. Hard signals returnTrueimmediately (--non-interactive,--agent-friendly,CI,CLAUDECODE,CLAUDE_CODE_ENTRYPOINT,CODEX_SANDBOX, Aider vars). Otherwise a score is accumulated and 3 points are required:TERMunset ordumbNO_COLORsetcmd \| jqin an ordinary shell scores 1 (stdout not a tty), or 2 if stdin is also redirected.TERMis set in any normal terminal, so the third point doesn't arrive. Verified on 0.3.0:Human-readable output, into a pipe, with
-oabsent.CI=true, because those are hard signals. Testing this from an agent shell or CI job will appear to confirm the promise. Unset those vars to see the real behaviour — my own first check gave a false pass for exactly this reason.What's already correct — please leave these
web/public/llms.txt:34— same correct framing.web/public/llms-full.txthas no matching copy.Suggested fix
Attribute the switch to agent/CI detection rather than piping, e.g.:
'Explicit output format, or auto-JSON in agent and CI contexts.'For :677, note that "Clean stdout channel. No surprises in pipes." is also currently overstated — see #104, where an auth failure writes English prose to stdout with
-o json. Either soften it now or land #104 first and keep the claim.Context
Same class as the command-example corrections in #97. Found while correcting the equivalent claim on developers.deepgram.com, which stated "When stdout is a pipe, the CLI automatically switches to JSON" and has now been fixed (deepgram/deepgram-docs#1128). Related: #98 (closed, success-path stdout pollution), #104 (failure-path stdout pollution).