Getting Started

Build your own CLI

Welcome to the start of our journey! If you’ve ever wanted to build a minimal, aesthetically pleasing, and highly functional Command Line Interface (CLI) tool, you are in the right place.

This page provides step-by-step guidance on exactly how we started building the something-cli. We’ll walk you through initialization, installing dependencies, and creating your very first entry file.

1. Initialization: We started by creating a brand new directory for our project. Open your terminal and run:

   mkdir my-awesome-cli
   cd my-awesome-cli
   npm init -y

   Your directory should now look like this:

   • package.json

2. Installing Dependencies: To make our CLI powerful and colorful, we installed a few essential tools: typescript (for type safety), commander (for handling terminal arguments), and chalk (for beautiful colors).

   npm install chalk commander
   npm install -D typescript @types/node

   Your directory now includes the node_modules folder and lock file:

   • Directorynode_modules/

     • …
   • package-lock.json
   • package.json

3. Setting up TypeScript: We initialized a tsconfig.json file to compile our TypeScript code into JavaScript.

   npx tsc --init

   Your directory tree:

   • Directorynode_modules/

     • …
   • package-lock.json
   • package.json
   • tsconfig.json

4. Creating the Entry File & The Shebang: Next, we created a src folder and an index.ts file inside it. At the very top of src/index.ts, we added a “shebang” line:

   #!/usr/bin/env node

   This tells your operating system terminal to execute the file using Node.js instead of treating it like a standard bash script.

   Your final directory structure for the setup phase:

   • Directorysrc/

     • index.ts
   • Directorynode_modules/

     • …
   • package-lock.json
   • package.json
   • tsconfig.json

5. The Magic bin Field: Finally, to tell the operating system that our package contains an executable command, we added the bin field to package.json:

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

   What does this do? It maps the command name somethingzz to the compiled JavaScript file (which will be generated in a dist folder when we build the code).

6. Adding Your First Command with Commander: We used the commander library to define our very first command: hello. Inside src/index.ts, we set up Commander to parse arguments and execute code:

   import { Command } from 'commander';
   import chalk from 'chalk';
   
   const program = new Command();
   
   program
       .command('hello')
       .description('print hello world')
       .action(() => {
           // This is where the magic happens!
           console.log(chalk.hex('#FFC0CB')('hello world!'));
       });
   
   // Don't forget to parse the arguments at the very end of the file!
   program.parse();

   How Commander works:

   • .command('hello') defines the word the user types (e.g., somethingzz hello).
   • .description(...) adds a helpful description when the user types somethingzz --help.
   • .action(...) defines the function that actually runs when the command is triggered.

7. Linking and Testing: To test the CLI locally without publishing it to npm, we used the npm link command. This creates a global shortcut on your computer.

   npm run build
   npm link

   Now we can test our newly built command! Here is how the output looks in the terminal:

   somethingzz hello
   
   # Output:
   # hello world! (in beautiful pink color!)

Now that you’ve seen how the foundation was built, check out the Installation & Setup page to see how to run our finished CLI on your own machine!