Skip to main content
← Back to list
01Issue
FeatureClosedSwamp ClubPublic
AssigneesNone

Relationships

#2267 Docs: cli-output.md does not state the stdout-is-value / stderr-is-interaction contract

Opened by skunk-ape · 9/17/2026

Gap

The manual page content/manual/reference/cli-output.md (swamp-club/swamp-club repo) describes output modes but says nothing about which stream carries what. There is a real contract here, and today it is only discoverable by reading the source.

stdout is the command output: prose in log mode, JSON in --json mode, and for a few commands a bare value a caller pipes, captures or redirects (swamp invite link, swamp first-rule, swamp vault read-secret). For those, stdout is byte-exact — #1768 removed even the trailing newline from a secret.

stderr is interaction and diagnostics: the spinner, the remote-execution indicator line, and (after #2260) every interactive prompt.

Two bugs landed because this was unwritten: #2254 (log records on stdout under -v, breaking swamp invite link piped to pbcopy) and #2260 (the confirmation prompt landing in a redirected swamp vault read-secret).

Suggested content

A short section in cli-output.md stating the rule, listing the value-on-stdout commands, and showing the scripting pattern it enables — redirecting read-secret into a key file, piping invite link into the clipboard.

Worth stating explicitly that prompts go to stderr, so silencing stderr on an interactive command hides the question rather than skipping it; --yes / -y is how you skip a confirmation non-interactively.

Related: #2259 (route log-mode output to stderr by default) may change the wording for ordinary prose commands; the value-on-stdout half of the rule is stable either way.

Filed from triage of #2260.

02Bog Flow
OPENTRIAGEDIN PROGRESSCLOSED

Closed

9/18/2026, 4:20:28 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

stack72 commented 9/18/2026, 4:20:27 PM

Added the stdout/stderr stream contract section to cli-output.md, covering value-on-stdout commands, scripting patterns, and prompt behaviour. Fixed in #1234.

Sign in to post a ripple.