How to write documentation for CLI app that requires stdin?

Question

I am writing CLI program that can accept very long strings. For this reason I decided to pipe the data into the program as I would hit limitation of the shell / OS.

1. How should these CLI program display documentation? When I launch it, it waits for input so I have no way of displaying to the user what should be done.
2. I could detect that program was run with -h/--help flag and perhaps display the documentation. What is the idiomatic format of stdin arguments for programs that accept stdin as their required argument.

• James McLeod: Why not check what other programs that use the same input method do?

Answer 1

Requiring stdin is a bit limiting. A common practice is to let the user specify a file that the application will read. Example:

gzip -c /tmp/file1
pv /tmp/file1
sha1sum /tmp/file1

Now, if the user wants to use stdin, nothing prevents him from using - syntax, such as:

cat /tmp/file1 | curl -X POST -d @- http://example.com/

Answer 2

After looking at manpages for wc and grep I've come to conclusion that there is no standardized way of documenting if program allows for reading via standard input.

The most common pattern, if the program allows for it, is to accept file(s) and then mention possibility of consuming data via standard in. Example:

wc [-clmw] [file ...]
 DESCRIPTION
 [...] and bytes contained in each input file, or standard input (if no file is specified) 

So I will probably modify my program to accept file(s) as well and use similar description.