ipfs cli output consistency
- Dominant language
- Go
- Stars
- 17.1k
- Forks
- 3.2k
- Avg merge
- 3d 18h
- Merged PRs (30d)
- 11
Description
Notes & discussion fodder on two `ipfs` usage points.
## subcommand discoverability
Some commands have subcommands. Some will output those subcommands when invoked without arguments. However, others will not, and must have `--help` provided:
```
$ ipfs
```
(shows all subcommands)
```
$ ipfs object
$ ipfs name
$ ipfs swarm
```
(shows all subcommands)
```
$ ipfs block
$ ipfs file
$ ipfs pin
$ ipfs repo
$ ipfs dht
$ ipfs diag
$ ipfs config
```
(no subcommands, just a terse summary)
Worse, some commands hide their subcommands! :(
```
$ ipfs bootstrap
(my peers)
```
```
$ ipfs bootstrap --help
(oh hey, there's 'list', 'add', and 'rm' subcommands!)
```
We can enhance discoverability greatly here by always outputting the subcommand listing when invoked.
Q: should `ipfs bootstrap` show peers, or show subcommand help? I lean toward the latter. It's a nice shortcut to avoid typing `ipfs bootstrap list`, but I'd rather have an alias on the first subcommand (e.g. `ipfs bs list`)
## show short-help (usage) docs automatically when a command is invoked incorrectly
e.g.
```
stephen // ~ $ ipfs block get
Error: Argument 'key' is required
Use 'ipfs block get --help' for information about this command
```
99% of users probably ran this command this way because they don't know how to use it yet. It seems very likely that they will then immediately issue:
```
stephen // ~ $ ipfs block get --help
ipfs block get - Get a raw IPFS block.
ARGUMENTS:
- The base58 multihash of an existing block to get.
DESCRIPTION:
'ipfs block get' is a plumbing command for retrieving raw ipfs blocks.
It outputs to stdout, and is a base58 encoded multihash.
```
Let's make this (usage output) the default when a bad invocation occurs.
---
cc @whyrusleeping, @diasdavid
Contributor guide
Assessment
This issue has not been assessed yet.