TypeScript is a typed superset of JavaScript that compiles to plain JavaScript.

typescript

Today, you can't do anything in JavaScript without bumping into a CLI. 

Want to install a library? `yarn` add it. 
Want a React app? `create-react-app`. 
Want to format your JavaScript? `prettier --write`. 
Want your types checked? `tsc`. 
Bundling? Pick from `webpack`, `rollup`, or `parcel`. 
Deploying? `now` or `netlify deploy`. 

CLI's are everywhere, and even if you don't write them, sooner or later you'll have to debug them.

This workshop serves as a comprehensive survey of the state of the art of CLI tooling for everyone looking to make an impact in open source, across their company, and even in their own productivity.

Check out these [**community notes for this course on Github**](https://github.com/eggheadio-projects/build-custom-cli-tooling-with-oclif-typescript-notes).

Before you use any frameworks, you should know the fundamentals of what makes Node CLI's tick. Here we explain everything you need to know to write a complete Node.js CLI from scratch, parse arguments, publish it to NPM for users, and set up yarn symlinks for optimal developer experience.

node

Develop and Publish a Node.js CLI from Scratch

The fastest way to create a robust, cross-platform compatible Node.js CLI (optionally typed with TypeScript) is by running `npx oclif single mycli`. Here we explain what this means and how and why to integrate this with Yarn Workspaces for an ideal developer experience.

javascript

Create a Single-Command Node.js CLI with Oclif, TypeScript and Yarn Workspaces

Flags and Args are the standard means of user input into CLI's. Oclif helps you parse them and declaratively indicate requirements, but because they are a public API, some thought should be put into designing the user experience. When in doubt, Flags win Arguments.

Parse Flags and Args in Node.js CLIs with Oclif and TypeScript

Heavy duty CLI's like gatsby and npm do more than one thing. The convention is to namespace them with a command name after the CLI name, like `gatsby new` or `gatsby build` or `npm install` or `npm uninstall`. We should be comfortable converting our single purpose CLI's into multi command CLI's as our needs grow, as well as understand how to share logic between commands to keep code DRY.

Convert a Single Command CLI into a Multi Command CLI with Oclif and TypeScript

Sometimes you still want to support the API and quick developer experience of a single command, while still supporting multi commands in your CLI. This is handy when, for example, you want your user to do something useful with just `npx mycli`.

Here's a quick hack that lets you do that, while also deepening your understanding of how your CLI works with TypeScript, Node.js and Oclif under the hood.

Create a Hybrid Single-Multi Command Node.js CLI with Oclif and TypeScript

You're going to run into a lot of frustration writing Node CLI's unless you get good at debugging. (Even if you use TypeScript!) To understand code execution (particularly code you didn't write), you should be comfortable using the VS Code Debugger for its excellent step-through and watch features. But in case you don't know where the problem is (particularly for heavily nested codebases like React) or if you're looking for performance issues rather than code errors, you'll also want a robust logging solution. The `debug` module is best in class and is built into Oclif.

Debug Node.js CLIs with the VS Code Debugger and the `Debug` module

To be useful and trustworthy, your CLIs should be extraordinarily reliable. Investing in testing early will reap rewards in future. We show how to set up basic tests with Jest and Oclif's test helpers.

jest

Test Node.js CLIs with Jest and Oclif

Flags and arguments are only the most primitive ways of taking in user input. There is no opportunity to interactively prompt the user so they don't need to look up documentation or memorize your flags. Fortunately there are many libraries that help take in user input, however, there are also ways to do it badly and other ways to do them well. Enquirer is a great foundation to build Interactive CLIs that don't leak tokens and passwords, and make use of design affordances to offer beautiful and intuitive user prompts.

However, don't get overzealous with the prompting: remember your CLI's non-human users - Bots and Continuous Integration environments! We end with some advice on how to blend flags and prompting seamlessly.

Design Beautiful, Intuitive and Secure Node.js CLI User Input Experiences with Enquirer

Prompting is a nice patch over missing Flags and arguments, but what if your program is so complex that you have *too many options*? You will probably want to allow the user to specify config files. The conventions and user preferences over config file format are too numerous to manage, but that's fine because Cosmiconfig will help us manage them!

Config handling is one example of highly sharable business logic (just like authentication and backend syncing) - so we will also look at how to extract this out to a shared Base Command.

Create Highly Configurable Node.js CLIs with Cosmiconfig and Oclif

One of the killer apps of CLIs is with templating (or scaffolding). The `rails generate` and `ng generate` commands are famous for this. By immediately reducing the pain of boilerplate, you can also make it easy to write standardized code, with in-place reminders for comments and developer warnings (it is easier to delete generated code than write code, though of course one can overdo it). There is no standardized tooling for doing scaffolding, since you can use everything from the Express.js templating languages to writing your own, but we explore this problem space with the tiny `copy-template-dir` library to prove out the developer experience of adding scaffolding to your CLI.

Scaffold out Files and Projects from Templates in a Node.js CLI

CLI's gain an extra level of power when you realize they can start and manage other CLI's and run multiple concurrent child processes (great for farming out work on multi-core machines!). You can even use it to improve developer experience in really small ways. For example, create-react-app famously scaffolds out a React app for you, and *also* installs the relevant node_modules. We'll learn how to do this two ways: with execa and with a dedicated yarn-or-npm utility, because this is such a common usecase.

But before all that - we must learn and be comfortable with the raw Node.js child_process and I/O Stream API's. So that's where we begin.

Spawn and Manage Child Processes and Node.js Streams with execa

If your users globally install your CLI's, will they ever update them? How will they know about new features and patches? How do you check for updates without impacting performance? How do you respect user preferences to *ignore* your updates?

These are all solved problems with the wonderful `update-notifier` library.

Prompt Users to Update Your Node.js CLIs with Update-Notifier

Most Node.js CLIs merely execute scripts statelessly, deterministic based on inputs from flags and args and configs. However this understates the massive potential of CLIs given their location in your filesystem. Just like the Browser DOM is inherently stateful, remembering your past link visits and preserving your form data, CLIs are another form of user experience that can be enhanced greatly by adding memory, particularly when the same CLI is used across multiple projects. This isn't a surprising insight, it is just that there is no standardized tooling around this. (Although there is a spec for *where* to store your data while respecting the user's preferences and operating system, called the XDG spec)

The Conf library provides an unbelievably easy way to persist values to memory in an XDG compliant fashion. We will explore two practical examples of using it.

Store State on Filesystem in Node.js CLIs with Conf

In stateful interfaces, there's a tradeoff between recency and frequency, two seemingly similarly aligned goals for guessing user intent. Recency biases towards newer entries being more likely to be what you are looking to do. Frequency biases towards betting on you doing the same thing you've always done. Fortunately there is an established algorithm that trades off frequency and recency, and chances are you've already used it in Slack or other similar interfaces!

Create Node.js CLI's that Intelligently Adapt to Usage with Frecency

When all is said and done, the finishing touches to put on your world class CLI can make your experience visually stand out as much as the code underneath. Chalk helps add colors to draw the eye to console output, and Ora gives you all the spinners you could possibly want for communicating that important work is being done in the background or child process.

Build Custom Command Line Interface (CLI) Tooling with oclif and TypeScript

Shawn Wang

Course Content