ipfs / ipfs/kubo

ipfs cli output consistency

Open
#2,402 5 comments 0 reactions 0 assignees View on GitHub
need/community-input
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.