Command Line Interface Guidelines

Contents

Command Line Interface Guidelines

An open-source guide to help you write better command-line programs, taking traditional UNIX principles and updating them for the modern day.

Authors

Aanand Prasad

Engineer at Squarespace, co-creator of Docker Compose.

@aanandprasad

Ben Firshman

Co-founder of Replicate, co-creator of Docker Compose.

@bfirsh

Carl Tashian

Offroad Engineer at Smallstep, first engineer at Zipcar, co-founder Trove.

tashian.com @tashian

Eva Parish

Technical Writer at Squarespace, O’Reilly contributor.

evaparish.com @evpari

Design by Mark Hurrell. Thanks to Andreas Jansson for early contributions, and Andrew Reitz, Ashley Williams, Brendan Falk, Chester Ramey, Dj Walker-Morgan, Jacob Maine, James Coglan, Michael Dwan, and Steve Klabnik for reviewing drafts.

Join us on Discord if you want to discuss the guide or CLI design.

Foreword

In the 1980s, if you wanted a personal computer to do something for you, you needed to know what to type when confronted with C:\> or ~$.<br>Help came in the form of thick, spiral-bound manuals.<br>Error messages were opaque.<br>There was no Stack Overflow to save you.<br>But if you were lucky enough to have internet access, you could get help from Usenet—an early internet community filled with other people who were just as frustrated as you were.<br>They could either help you solve your problem, or at least provide some moral support and camaraderie.

Forty years later, computers have become so much more accessible to everyone, often at the expense of low-level end user control.<br>On many devices, there is no command-line access at all, in part because it goes against the corporate interests of walled gardens and app stores.

Most people today don’t know what the command line is, much less why they would want to bother with it.<br>As computing pioneer Alan Kay said in a 2017 interview, “Because people don&rsquo;t understand what computing is about, they think they have it in the iPhone, and that illusion is as bad as the illusion that &lsquo;Guitar Hero&rsquo; is the same as a real guitar.”

Kay’s “real guitar” isn’t the CLI—not exactly.<br>He was talking about ways of programming computers that offer the power of the CLI and that transcend writing software in text files.<br>There is a belief among Kay’s disciples that we need to break out of a text-based local maximum that we’ve been living in for decades.

It’s exciting to imagine a future where we program computers very differently.<br>Even today, spreadsheets are by far the most popular programming language, and the no-code movement is taking off quickly as it attempts to replace some of the intense demand for talented programmers.

Yet with its creaky, decades-old constraints and inexplicable quirks, the command line is still the most versatile corner of the computer.<br>It lets you pull back the curtain, see what’s really going on, and creatively interact with the machine at a level of sophistication and depth that GUIs cannot afford.<br>It’s available on almost any laptop, for anyone who wants to learn it.<br>It can be used interactively, or it can be automated.<br>And, it doesn’t change as fast as other parts of the system.<br>There is creative value in its stability.

So, while we still have it, we should try to maximize its utility and accessibility.

A lot has changed about how we program computers since those early days.<br>The command line of the past was machine-first: little more than a REPL on top of a scripting platform.<br>But as general-purpose interpreted languages have flourished, the role of the shell script has shrunk.<br>Today&rsquo;s command line is human-first: a text-based UI that affords access to all kinds of tools, systems and platforms.<br>In the past, the editor was inside the terminal—today, the terminal is just as often a feature of the editor.<br>And there’s been a proliferation of git-like multi-tool commands.<br>Commands within commands, and high-level commands that perform entire workflows rather than atomic functions.

Inspired by traditional UNIX philosophy, driven by an interest in encouraging a more delightful and accessible CLI environment, and guided by our experiences as programmers, we decided it was time to revisit the best practices and design principles for building command-line programs.

Long live the command line!

Introduction

This document covers both high-level design philosophy, and concrete guidelines.<br>It’s heavier on the guidelines because our philosophy as practitioners is not to philosophize too much.<br>We believe in learning by example, so we’ve provided plenty of those.

This guide doesn’t cover full-screen terminal programs like emacs and vim.<br>Full-screen programs are niche projects—very few of us will ever be in the position to design one.

This guide is also agnostic about programming languages and tooling in general.

Who is this guide for?

If you are creating a CLI program and you are looking for principles and concrete best practices for its...