What does good CLI output look like?
Opened this issue · 0 comments
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
):
- whether the download succeeded
- the resultant fs path to the downloaded file(s), if success
The next tier of verbosity should include
- the size of the downloaded file(s)
- 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