For command-line tools that take one input file and/or one output file, use stdin and/or stdout, respectively. This fits into the Unix philosophy of writing small, modular programs.

Allow overriding the input file using -i/--in (e.g. -i raw.txt) and overriding the output file using -o/--out (e.g. -o baked.txt)¹¹1 -i and -o are Common command-line options. . This is in addition to shell redirection (using < and >), for convenience.

For output, use stdout by default if the output is textual. If the output is non-textual, refuse to write to stdout if stdout is a TTY, or if -o/--out is not explicitly set to -. For example:

% my-data-gen --text
Bla bla bla
Ok

% my-data-gen --text > stuff.txt
Ok

% my-data-gen --binary
Error: Refusing to write binary data to implicit stdout (is a TTY)

% my-data-gen --binary > stuff.dat
Ok

% my-data-gen --binary --out -
[garbled data omitted]
Ok

For input, don’t use stdin if stdin is a TTY, or if -i/--in is not explicitly set to -. For example:

% my-read-tool
Error: Refusing to read from implicit stdin (is a TTY)

% my-read-tool < stuff.xt
Ok

% my-read-tool --in -
Ok

To do: What about multiple inputs? Multiple outputs?