CLIs are user interfaces too (lightning talk)

A presentation at Linux.conf.au 2018 in January 2018 in Sydney NSW, Australia by Adam Brenecki

Slide 1

Slide 1

Command line interfaces are user interfaces too. Normally when we’re building a user interface, we put a lot of thought into how easy it is to use; if we’re lucky, we even have people or teams whose whole job it is to do that. How do we take that and apply it to command line tools?

Slide 2

Slide 2

Give things sensible names. It’s okay to give your tool itself a clever or silly name; if you’re writing Python it’s actually required by law. Things that are within your tool should have names that make their meaning obvious. That doesn’t mean that choosing the name is obvious. Trying to name things well can take hours.

Slide 3

Slide 3

Use consistent names. These three names all refer to the same thing in Git. Don’t be like Git.

Slide 4

Slide 4

Be consistent.

Slide 5

Slide 5

Be consistent between different parts of your own CLI.

Slide 6

Slide 6

TaskWarrior has tags, it has dynamic tags, and it has different places where tags are used. In every case, tags are denoted with a plus at the front. Be like TaskWarrior.

Slide 7

Slide 7

Different git subcommands have different ways to delete things. Don’t be like Git.

Slide 8

Slide 8

Here’s why. This will try to create a branch named ‘rm’. I do this all the time.

Slide 9

Slide 9

Be consistent with the ecosystem you’re in.

Slide 10

Slide 10

If you use the built-in argument parsing library in Go, it expects a single dash before every flag, rather than a double dash. That means everyone using your tool has to remember “oh, this is a weird Go thing, I need to use it differently to what I’m used to”. Use a library that lets you do what your users expect.

Slide 11

Slide 11

Don’t go overboard on consistency. Sometimes doing things a little differently actually makes sense for your users, if you’ve thought about it and you have a good reason for it.

Slide 12

Slide 12

This is a switch statement in Bash. What’s going on here? Why are there unbalanced parens? What the hell is an esac?

Slide 13

Slide 13

This is a switch statement in the Fish shell. It’s much easier to understand. It’s also not POSIX compatible, but that’s okay. You don’t need to be all things to all people, especially if you’re sacrificing usability for it.

Slide 14

Slide 14

Have good defaults. you might not think of defaults as being part of your user interface, but they are.

Slide 15

Slide 15

Docker has sane defaults, so people don’t shoot themselves in the foot.

Because of Docker’s defaults, I don’t even need to understand namespaces or capabilities or all the things Jess talked about this morning to start using it, even though I can learn about them and adjust the dials later. This is why Docker is popular.

Be like Docker.

Slide 16

Slide 16

Firewalld in fedora ships with every incoming port over 1024 open by default. Users expect their firewall to block things by default, and this is the exact opposite. Don’t be like firewalld.

Slide 17

Slide 17

On a similar vein, configuration files are also part of your UI.

Slide 18

Slide 18

Use a common format that’s clear and widely understood, so that your users only have to think about the actual configuration they’re doing, rather than your crazy custom syntax too.

Slide 19

Slide 19

Don’t ship a default configuration file with a million things in it; that just makes it hard for your users to keep track of what they’ve changed. When your default config is an empty file, your users can also roll back to default by just deleting everything. Your sane defaults should kick in for a particular option if it’s missing.

Slide 20

Slide 20

Document everything. Command line options, config files, interactive-mode behaviour. Use lots of examples. Writing good docs is an art in an of itself. If you do nothing else, do this.

Slide 21

Slide 21

Why should we care about CLI user interfaces anyway? These things are for developers and operators! They’re Computer People! They can just figure it out!

Slide 22

Slide 22

No.

Slide 23

Slide 23

We do not have infinite memory. The less I have to understand and remember about your tool in order to use it, the better.

Slide 24

Slide 24

We did not emerge from our mothers’ wombs with an intricate understanding of Git’s underlying data model. The easier your tool is to use, the less time it takes to learn, the more time your users can spend on important things.