We want to

share patterns

that help us build good CLIs.

These patterns emerged from

concepts we discovered

the hard way.

For years

we have been building tools

to assist our project.

Some of the tools are

used by people

to simplify development.

Some of the tools are

used by tools

to delegate responsibility.

While building the tools, we

found CLI qualities

that we think are useful.

So we have

hand picked four

to share with you today.

And we'll explain

how to implement each

of these in Node.

But remember

these are suggestions

not requirements.

A command-line interface should be testable.

For a long long time

we struggled to test

the command-line interface.

Originally we

tested by shell execution

but tests were slow and vague.

What we really want are

programmatic tests

for the command-line interface.

Turns out, we can do this by

treating the CLI as a module

instead of an executable script.

First, we have to

slim down the bin/

to proxy into the CLI module.

Second, the

CLI should be a module

that consumes the main library.

This allows us to

test the CLI as a module

by faking process.argv.

Lastly, the CLI module

should only have CLI logic

keeping it focused.

Allowing us to

mock the main library

and keep tests running fast.

And with that

we have a testable CLI

without doing anything fancy.

A command-line interface should be helpful.

The fact is

people are using your tool

not omniscient gods.

We need to have

meaningful help output

to assist people with the tool.

And while it is really

convenient to hard-code

those helpful messages.

It results in

ugly strings

buried deep in the code.

That we

forget to update

because it's out of sight.

But thankfully

we can do better

with something very obvious.

We can

use text files

that are easy to read and edit.

And we can write code to

find, read, and regurgitate

the files from given commands.

And when

plain text isn't good enough

use templating and markup libraries.

A command-line interface should be bipolar.

Sometimes it's nice to have

a verbose tool

when something goes wrong.

Sometimes it's nice to have

a quiet tool

when everything goes right.

But when the CLI is decoupled

how do we implement this

into the tool?

We have found

event emitters work well

and add no extra dependencies.

The idea is that the

main library is verbose

like a chatty kid.

And the

CLI module can subscribe

or unsubscribe to the chatty kid.

So now we have

detailed messages

that can be toggled on or off.

A command-line interface should be interoperable.

Our parents always said it's

important to play nice

with the other kids.

It's not uncommon for

tools to use tools

to build better tools.

But this is only possible with

good communication

between the tools.

In other words,

exit codes

are important.

We may also want

consumable output

for other tools to parse.

And don't forget about

playing nice on Windows

the kid that's always picked last.

Try to

avoid hard-coding paths

into your code.

Remember to

use environment variables

for the details.

And thankfully

npm is Windows-friendly

scripts add binaries to PATH.

And that's it.

We hope those

four simple suggestions

help improve your CLI.

Thanks!

@filmaj & @mwbrooks

michaelbrooks.ca/deck/node-brigade-2013