How to create, publish and use cli util with nodejs commanderjs and typescript

Preface

Huge part of my daily routine is bound to some kind of manipulation with command line in terminal. And I constantly find myself that it would be cool to make cli util for this or for that.
So I decided to try create some tiny util for myself. I thought that may be I'll do it with python or may be I could try rust but for now I decided to stick with my current stack which is nodejs and you know what - it went pretty good.
I built small thing which is "how" command. It supposed to teach you first steps on how to use particular project. Source code is on github.
And here are some notes on how to make such cli utils easy peasy.

Develop

First let's bootstrap initial project:

copied bash

mkdir how2-cli
yarn init -y
yarn add typescript commander
npx tsc init

Now let's add some functionality:

copied bash

touch index.ts

We'll rely a lot on super awesome nodejs library called commander. Let's add some boilerplate code to our index.ts.

copied ts/tsx

#! /usr/bin/env node
// [0]
import { Command } from "commander"; // [1]

const program = new Command();
program.version("0.0.1");

program
  .option("-d, --debug", "output extra debugging")
  .option("-w, --welcome", "Welcome message"); // [2]

program.parse(process.argv); // [3]

const options = program.opts(); // [4]
if (options.debug) console.log(options);

if (options.welcome) {
  console.log(blue("Hello world!"));
}

First of all to mention we have #! /usr/bin/env node as the beginning of the file - this points the system to use node as env to run the command.
Here we import Command class from commander [1], then create some options [2] and use arguments from command line. Commader will parse them into instance's options under the hood and we'll fetch it from object via .opts() method.
Now we have to build the source file. Add the build and watch scripts to package.json:

copied json

  ...
  "scripts": {
    "build": "tsc",
    "watch": "tsc --watch"
  }
  ...

Build it and make it executable (chmod command needs to be triggered only once):

copied bash

yarn build && chmod +x index.js

We also can use yarn watch to not rebuild it manually all the time.
We now have our brand new index.js being created and we are ready to try it out. Next command should work.

copied bash

./index.js

Also to use this as a cli command we have to add bin section to package.json

copied json

...
  "bin": {
    "how": "./dist/index.js"
  }
...

Publish

And now let's install our util globally in our system:

copied bash

npm i -g
npm link
# and test it via
how
how -w

To make it publicly available we have to publish it to npm.

copied bash

# commit our changes
npm login
npm version patch
npm publish --access public

And now we can see our command on npmjs and we even can do npm install -g how2-cli