Stream downloads to stdout with --output -

[arcaputo3]

Closes #7. Stacked on #12 (review the last commit only).

Before

$ quartr transcripts download 2133368 --format raw > f.json
$ cat f.json
Saved transcripts-2133368.json
$ ls
f.json  transcripts-2133368.json      # the document is in the file you didn't ask for

After

$ quartr transcripts download 2133368 --output - > f.json
$ wc -c f.json
1062439 f.json
$ head -c 80 f.json
{"version": "1.0.0", "event_id": 382915, "company_id": 4742, "transcript": {"te
$ ls
f.json                                # nothing else

And the default path no longer pollutes a redirect either:

$ quartr transcripts download 2133368 > redirect.txt 2> stderr.txt
$ wc -c < redirect.txt
0
$ cat stderr.txt
Saved transcripts-2133368.json

Change

• --output - streams the document to stdout and prints nothing else.
• The Saved <path> confirmation goes to stderr unconditionally. Both halves are needed: --output - serves people who want a pipe, stderr serves everyone who redirects without knowing the flag exists.
• --help for every download-capable resource now spells out all three behaviours, since "downloads always write a file" was the part nobody knew.

I went with the explicit - rather than auto-detecting a non-TTY stdout. Auto-detection would mean the same command writes a file when run interactively and no file when redirected, which is a surprising thing to debug; the stderr move already fixes the reported damage for people who never read the flag.

While in there: the output file is now closed explicitly with its error reported. A failed flush on a 1 MB transcript was silently swallowed by the deferred Close, so a truncated download could exit 0.

Tests

--output - puts the exact bytes on stdout, leaves stderr empty, and writes no file to the working directory; the default path leaves stdout empty and reports the path on stderr.

🤖 Generated with Claude Code