CLI basics. How to handle input requirements?

I’m trying build a basic cli app for the purpose of learning.

Lets say we are making a basic cli for counting words of one or more txt documents

The requirement of my app is as listed:

  • The program accepts as arguments a list of one or more file paths (e.g. ./wordcount file1.txt file2.txt …).
  • The program also accepts input on stdin (e.g. cat file1.txt | ./wordcount).

First of all here is my current working example of a cli escript app.

One of the things not listed that bothered me was the app would just hang if no input via args or sdtin was given.

I understand the app was just waiting for input from the terminal and if I typed it would read via, but I would think that it would be more helpful that I gave an error if no input was given and then just stop the app.

I didn’t realize that it’s a common thing for stdio to just wait there.

I guess at this point I’m at a loss for common bast practices.

  • should the app just hang expecting some form of stdin?
  • should the app be smart and see nothing is happening and report according?
  • should I have an explicit flag that denotes how I want to explicitly use the app?

Sorry for such a open ended question, its just that this was also a part of a tech challenge for a job interview that I completely tanked today. Not feeling very good about myself right now. I wish I had a better understanding of standards and this type of utility apps feels very foreign to me as primarily a web developer just starting to make phoenix apps.

It is very common for command line applications to just wait for input if no arguments are given.

For example: cat, grep, wc, sed, awk, sed and many others. Try these without a file argument and they will just hang there and wait for input. Use Ctrl-D to give eof

None of these applications warn if there is no standard input as that is the normal way they work and it is what make them easy to use in pipes.

Other command line applications have a flag or use dash - instead of the filename to specify that you want them to read from standard in. For example: xmllint, (I know there are many more but can’t think of one now). This way you can show them a help text indicating that they need to provide a filename or - for stdin if they haven’t provided any arguments.

It is also common to write things to standard out, or at least give an option to write to standard out instead of a file. For example wget allows you to specify and outfile with -O filename but the option to write to standard out with -O -. Funnily enough curl works the other way around where the default is to write to standard out but you can save to a file with -o filename.

As I almost exclusively work with command line applications I think a well behaved command line app should

  • Support reading and writing from stdin/stdout (if it makes sense for the application). I don’t mind if I have to provide a flag for this
  • Write errors and warnings to stderr
  • Return correct error codes 0 for success. non zero for failure.
  • Have a man page with good descriptions and examples. This is getting less common
  • Have a short hand help through -h or --help. I like this to be short and fit on a page. The rest is for man.
  • Have a non-interactive flag if normally interactive (so that things can get automated)
  • Likely more which I haven’t thought about :smiley:

So perhaps your cli app can do this (just an example).

$ ./wordcount
Usage: wordcount OPTION... [FILE]...
Counts words in each FILE and print to standard output

When FILE is -, read standard input.


  -i, --ignore=REGEX  Ignore words matching REGEX

$ ./wordcount --help
Usage: wordcount OPTION... [FILE]...
Counts words in each FILE and print to standard output

When FILE is -, read standard input.


  -i, --ignore=REGEX  Ignore words matching REGEX

$ ./wordcount hello.txt

$ cat hello.txt | ./wordcount -

$ ./wordcount hello.txt world.txt

That was very well written, thank you for this. It helps.

Even though @cmkarlsson already told that this is pretty much expected behaviour, I also want you to ask, if you read from stdin and want to print an error on “no input”, how would you distinguish “no input” from “delayed input”?

You can only distinguish those 2 after the input has been closed from the sender. On the terminal you usually do so by pressing Ctrl+D.

Using this, I have a programm that periodically prints data to its stdout piped into another program which reads and parses the input that comes in and then changes some data in a database. This were not easily possible with your proposal.