Don’t Let Your Terminal Become a Script “Junkyard”
If you’re a DevOps or Backend engineer, you’re likely familiar with repeating tasks like cleaning databases or checking system health. Usually, we write a few lines of shell script or copy-paste long commands. This approach is fast at first but becomes extremely difficult to manage in the long run.
Previously, I used to run scripts with the node script.js command. As the number of parameters grew, manually handling process.argv became a disaster. You need a real framework to manage command structures and automate help documentation.
Three Ways to Build CLIs in the Node.js Ecosystem
Here are three popular methods I’ve experimented with across various projects:
1. Using process.argv (Vanilla Node.js)
This is the most primitive approach, involving parsing Node.js’s default parameter array.
- Pros: Runs immediately without installing libraries. Suitable for personal scripts under 20 lines of code.
- Cons: You have to write error-handling logic and usage instructions yourself. The code becomes very messy if you have 3 or more parameters.
2. Commander.js or Yargs
These two libraries are the go-to choices in the Node.js community.
- Pros: Handles flags (
-f,--force) very smoothly. Automatically generates beautiful help pages. - Cons: When your CLI grows with dozens of subcommands, the main file becomes massive and extremely hard to maintain.
3. Oclif (Open CLI Framework)
This is a heavyweight “weapon” from Salesforce, used to build the Heroku CLI. Unlike simple libraries, Oclif provides a strict directory architecture.
- Pros: Default TypeScript support, automatic file-based command loading, and a highly professional testing system.
- Cons: You’ll spend about 30 minutes initially getting used to its structure.
Why Oclif is the Top Choice for Real-World Projects?
In a recent project, my team built the itfz-cli tool to support 5 developers. Instead of remembering dozens of complex Docker or AWS commands, they just type itfz-cli deploy --stage=staging. As a result, the time to initialize a new environment dropped from 15 minutes to less than 30 seconds.
Oclif solves the scalability problem. Each command is a separate file in the src/commands directory. When you need to add a feature, you just create a new file without worrying about breaking existing logic that’s running smoothly.
Getting Started with Your First CLI
Step 1: Initialize the Project
Use npx
