What does good CLI output look like?

[hackergrrl]

ipget should aim to be transparent: exposing its inner workings as needed to users. (but only as needed)

usage

All good programs dump a block of helpful text when invoked without arguments:

Usage: ipget IPFS_PATH [-o]

ipget - retrieve and save IPFS objects

ipget is a tool for non-interactive downloading of files or objects from IPFS to the 
user's filesystem, similar to wget or curl. It supports /ipfs and /ipns paths. ipget
is meant to be used in scripts and pipelines.

Arguments:
  IPFS_PATH=""   the IPFS object path

Options:
  -o, --output=""   output file path

necessary information

Output MUST always include, at the minimum (--quiet):

1. whether the download succeeded
2. the resultant fs path to the downloaded file(s), if success

The next tier of verbosity should include

1. the size of the downloaded file(s)
2. the transport (ephemeral node, local daemon, public gateway, bluetooth)

Finally, maximum verbosity (--verbose) could much much more (how many peers we bootstrapped to, the resolved /ipfs path, resolved IP of the public gateway, progress bar of the download). The goal here is to make human troubleshooting easier.

typical use

Here's what an average successful invocation of ipget ought to look like:

$ ipget /ipfs/QmWrUZ42cb34SezHLA4xZkPGGTfdcKpnMuAxEXD9yJAeiw/go-multihash.git
Downloading from IPFS.. ..succeeded
Saved to QmWrUZ42cb34SezHLA4xZkPGGTfdcKpnMuAxEXD9yJAeiw/go-multihash.git [519kb]

A really common UX pain is when the IPFS node can't find the hash. It should timeout after some reasonable time (user configurable), and let the user know it's fallen back to another option:

$ ipget /ipfs/QmWrUZ42cb34SezHLA4xZkPGGTfdcKpnMuAxEXD9yJAeiw/go-multihash.git
Downloading from local daemon.. ..failed
Downloading from IPFS.. ..failed
Downloading from public gateway (ipfs.io).. ..succeeded
Saved to QmWrUZ42cb34SezHLA4xZkPGGTfdcKpnMuAxEXD9yJAeiw/go-multihash.git [519kb]

And of course, sometimes your hash just can't be found:

$ ipget /ipfs/QmWrUZ42cb34SezHLA4xZkPGGTfdcKpnMuAxEXD9yJAeiw/go-multihash.git
Downloading from local daemon.. ..failed
Downloading from IPFS.. ..failed
Downloading from public gateway (ipfs.io).. ..failed
Unable to locate QmWrUZ42cb34SezHLA4xZkPGGTfdcKpnMuAxEXD9yJAeiw/go-multihash.git

verbose / quiet output

It's *really not fun when you can't debug a failure any further than this. Unlike HTTP, there's a lot more that can go wrong. Having a -v/--verbose flag will let savvy users get deeper insight into possible failure causes.

$ ipget -v /ipfs/QmWrUZ42cb34SezHLA4xZkPGGTfdcKpnMuAxEXD9yJAeiw/go-multihash git
Downloading via IPFS..
Bootstrapping           DONE (9/9)
Resolving path          DONE (/ipfs/QmV4XiZEWAL6JDNxfP6PNtGm2MtxviPaGnaGhP9yV5p2ik)
Downloading             TIMEOUT (300kb/519kb)
..failed

Downloading from public gateway (ipfs.io)..
Resolving               DONE (104.236.176.52)
Downloading             NOT FOUND (404)
..failed

Unable to locate QmWrUZ42cb34SezHLA4xZkPGGTfdcKpnMuAxEXD9yJAeiw/go-multihash.git

Inversely, like most ipfs commands, there should be a -q/--quiet flag for terseness:

$ ipget /ipfs/QmWrUZ42cb34SezHLA4xZkPGGTfdcKpnMuAxEXD9yJAeiw/go-multihash.git
QmWrUZ42cb34SezHLA4xZkPGGTfdcKpnMuAxEXD9yJAeiw/go-multihash.git

This is optimal for scripts: they can use POSIX exit codes to determine whether the download succeeded.

---

cc @jbenet @whyrusleeping @lgierth
cc @substack too, who may have some unixy program design wisdom