add -r should suggest next steps

[autonome]

We should add a short message that suggests what's possible, or eases next steps to view the added data, eg:

"Recursive add complete! You can preview on the public gateway at https://..."

Location

ipfs add -r .

Description

From https://macwright.org/2019/06/08/ipfs-again.html:

[Stebalien]

As he admits, this is simply how CLI tools work. Instead of trying to make the go-ipfs CLI something it isn't, we should:

1. Recommend ipfs-desktop.
2. Show users how to add files via ipfs desktop.

We should still offer the CLI tool as an option but CLI users generally don't expect fancy messages.

[autonome]

What is the downside to a short helpful message? How would that minor string addition turn go-ipfs into something it is not?

Why are we limiting the options to an abstract common denominator of "cli tools", which historically are considered terribly unhelpful except to the most proficient users?

[Stebalien]

My two concerns are:

1. Not annoying the user.
2. Keeping the output parsable.

Having a nice and friendly "you did a thing!" message is useful for (some) new users running the command for the first time but is really annoying for everyone else running the command for the hundredth time. These commands are meant to be run over and over so they're optimized for that use-case.

Also note, as with most unix commands, the output of ipfs add -r is designed to be parsed. We have to be careful about changing the output:

ipfs add -r foobar | while read event cid path; do
  # do something...
done

On the other hand, commands like ipfs daemon and ipfs add do spit out a bunch of helpful information because these commands (a) are meant to be run infrequently and (b) aren't generally meant to be have their output parsed.

---

Given these constraints, we can implement this as follows:

1. Only spit out the message the first time, recording which commands have been run in some dot file. Sudo has a feature like this (called "lecture").
2. Have a config option for disabling these help messages.
3. Send the message to STDERR instead of STDOUT so we don't break users trying to parse output. This is how commands like curl deal with status messages.
4. Skip all this logic if the command isn't being run interactively. On Linux, this can be detected by checking for a TTY.

In this case, the help message would be:

added QmFoo myDir

  Congratulations! You've added your first file to IPFS.... { dynamic help text that may need to tell the user to start the daemon, etc. }

[hsanjuan]

My take here is that given that we can build nice UIs on top of IPFS (desktop), we should avoid bloating the CLIs to make them user-friendly for people that are not used to work with CLI interfaces. However, that should not be a excuse for not having awesome CLI documentation. In this case ipfs add --help is pretty good and detailed imho.

Note that CLIs are effecitvely APIs (more so in go-ipfs since it matches 1to1 with the HTTP API). I disagree that CLIs are historically unhelpful. They are the best for what they do: an interoperable text interface (not only to humans but to other programs).