TypeScript: Building a Simple Command-Line Interface (CLI)

Written by

learnmodernjavascript

in

In the world of software development, command-line interfaces (CLIs) are incredibly powerful tools. They allow developers to interact with applications directly from their terminal, automating tasks, managing projects, and more. If you’ve ever used tools like Git, npm, or even just navigated your file system, you’ve used a CLI. In this tutorial, we’ll dive into building your own simple CLI using TypeScript. We’ll explore the core concepts, step-by-step implementation, and best practices to create a functional and user-friendly command-line application.

Why Build a CLI?

Before we jump into the code, let’s discuss why building a CLI is beneficial. CLIs offer several advantages:

  • Automation: Automate repetitive tasks, saving time and effort.
  • Efficiency: Provide a quick and direct way to interact with your application.
  • Flexibility: Offer powerful control and customization options.
  • Scripting: Enable scripting and integration with other tools.

Whether you’re building a tool for personal use, automating your development workflow, or creating a public utility, a CLI can be an invaluable asset. TypeScript, with its strong typing and modern features, is an excellent choice for building robust and maintainable CLIs.

Prerequisites

To follow this tutorial, you’ll need the following:

  • Node.js and npm (or yarn): You’ll need Node.js installed to run JavaScript code and npm (Node Package Manager) or yarn to manage project dependencies.
  • TypeScript: Make sure you have TypeScript installed globally or in your project. You can install it globally using `npm install -g typescript`.
  • A Code Editor: A code editor like Visual Studio Code, Sublime Text, or Atom will be helpful.
  • Basic JavaScript Knowledge: Familiarity with JavaScript concepts like variables, functions, and objects is recommended.

Setting Up Your Project

Let’s start by creating a new project directory and initializing it with npm. Open your terminal and run the following commands:

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

This will create a new directory named `my-cli`, navigate into it, and initialize a `package.json` file with default settings. Next, we’ll install TypeScript and some necessary packages:

npm install typescript --save-dev
npm install commander @types/node --save-dev

Here’s what each package does:

  • typescript: The TypeScript compiler.
  • commander: A library to help you create command-line interfaces. It simplifies parsing arguments and creating commands.
  • @types/node: Type definitions for Node.js.

Now, let’s create a `tsconfig.json` file to configure TypeScript. Run the following command:

npx tsc --init --rootDir src --outDir dist --module commonjs

This command generates a `tsconfig.json` file. We’ve added `–rootDir src` to tell TypeScript where our source files will be and `–outDir dist` to specify where the compiled JavaScript files will be placed. We also specified `–module commonjs` to tell the compiler to use the CommonJS module system, which is compatible with Node.js.

Project Structure

Before we start writing code, let’s define the project structure:

my-cli/
├── package.json
├── tsconfig.json
├── src/
│   └── index.ts
└── dist/
  • package.json: Contains project metadata and dependencies.
  • tsconfig.json: Configures the TypeScript compiler.
  • src/: Contains the TypeScript source code.
  • src/index.ts: The main entry point of our CLI.
  • dist/: Will contain the compiled JavaScript files.

Writing the CLI Code

Now, let’s write the code for our CLI. Open `src/index.ts` and add the following code:

import { program } from 'commander';

program
  .name('my-cli')
  .description('A simple CLI built with TypeScript')
  .version('1.0.0')
  .command('hello [name]', 'Say hello to someone')
  .action((name: string) => {
    const greeting = name ? `Hello, ${name}!` : 'Hello, world!';
    console.log(greeting);
  });

program.parse(process.argv);

Let’s break down this code:

  • `import { program } from ‘commander’;`: Imports the `program` object from the `commander` library.
  • `.name(‘my-cli’)`: Sets the name of your CLI, which will be used in help messages.
  • `.description(‘…’)`: Sets a description for your CLI.
  • `.version(‘1.0.0’)`: Sets the version of your CLI.
  • `.command(‘hello [name]’, ‘Say hello to someone’)`: Defines a command named ‘hello’. The `[name]` part indicates an optional argument. The second argument is a description for the command.
  • `.action((name: string) => { … })`: Defines the action to perform when the ‘hello’ command is executed. It takes an optional `name` argument.
  • `const greeting = …`: Creates the greeting message.
  • `console.log(greeting);`: Prints the greeting to the console.
  • `program.parse(process.argv);`: Parses the command-line arguments.

Compiling and Running the CLI

Now, let’s compile our TypeScript code into JavaScript. In your terminal, run:

npx tsc

This command uses the TypeScript compiler to transpile your `.ts` files into `.js` files, placing the output in the `dist` directory. Now, to run your CLI, you have a few options.

  1. Directly using Node.js: 
    node dist/index.js hello
node dist/index.js hello John
  2. Adding a script to `package.json`:
    Open `package.json` and add the following script inside the `”scripts”` section:

    "scripts": {
  "start": "node dist/index.js"
},

    Then, you can run the CLI using:

    npm start hello
npm start hello John

You should see the following output:

Hello, world!
Hello, John!

Adding More Commands and Options

Our CLI is functional, but let’s make it more useful by adding more commands and options. We’ll add a command to display the current date and time.

Modify `src/index.ts` as follows:

import { program } from 'commander';

program
  .name('my-cli')
  .description('A simple CLI built with TypeScript')
  .version('1.0.0')
  .command('hello [name]', 'Say hello to someone')
  .action((name: string) => {
    const greeting = name ? `Hello, ${name}!` : 'Hello, world!';
    console.log(greeting);
  });

program
  .command('date', 'Display the current date and time')
  .action(() => {
    const now = new Date();
    console.log(now.toLocaleString());
  });

program.parse(process.argv);

Now, compile your code using `npx tsc` and run the following commands:

npm start hello
npm start hello John
npm start date

You should see the current date and time displayed in your console.

Adding Options

Options allow you to customize the behavior of your commands. Let’s add an option to the ‘hello’ command to specify the greeting language.

Modify `src/index.ts` as follows:

import { program } from 'commander';

program
  .name('my-cli')
  .description('A simple CLI built with TypeScript')
  .version('1.0.0')
  .command('hello [name]', 'Say hello to someone')
  .option('-l, --language ', 'Specify the language')
  .action((name: string, options) => {
    let greeting = name ? `Hello, ${name}!` : 'Hello, world!';
    if (options.language === 'fr') {
      greeting = name ? `Bonjour, ${name}!` : 'Bonjour, le monde!';
    } else if (options.language === 'es') {
      greeting = name ? `Hola, ${name}!` : 'Hola, mundo!';
    }
    console.log(greeting);
  });

program
  .command('date', 'Display the current date and time')
  .action(() => {
    const now = new Date();
    console.log(now.toLocaleString());
  });

program.parse(process.argv);

Here, we’ve added the `.option()` method to the ‘hello’ command. The first argument is the option’s flag (e.g., `-l` or `–language`), and the second is a description. Inside the `action` function, the `options` object contains the values of the specified options. Compile and test:

npx tsc
npm start hello John
npm start hello John --language fr
npm start hello John -l es

You should see the greeting in the specified language.

Handling Errors

Error handling is crucial for creating a robust CLI. Let’s add a simple example of error handling. We’ll add a command that simulates fetching data from a remote API and handle potential errors.

Modify `src/index.ts` as follows (you’ll need to install `node-fetch`):

npm install node-fetch

import { program } from 'commander';
import fetch from 'node-fetch';

program
  .name('my-cli')
  .description('A simple CLI built with TypeScript')
  .version('1.0.0')
  .command('hello [name]', 'Say hello to someone')
  .option('-l, --language ', 'Specify the language')
  .action((name: string, options) => {
    let greeting = name ? `Hello, ${name}!` : 'Hello, world!';
    if (options.language === 'fr') {
      greeting = name ? `Bonjour, ${name}!` : 'Bonjour, le monde!';
    } else if (options.language === 'es') {
      greeting = name ? `Hola, ${name}!` : 'Hola, mundo!';
    }
    console.log(greeting);
  });

program
  .command('date', 'Display the current date and time')
  .action(() => {
    const now = new Date();
    console.log(now.toLocaleString());
  });

program
  .command('fetch-data ', 'Fetch data from a URL')
  .action(async (url: string) => {
    try {
      const response = await fetch(url);
      if (!response.ok) {
        throw new Error(`HTTP error! Status: ${response.status}`);
      }
      const data = await response.json();
      console.log(data);
    } catch (error: any) {
      console.error(`Error fetching data: ${error.message}`);
    }
  });

program.parse(process.argv);

Here’s what changed:

  • We added a new command `fetch-data` that takes a URL as an argument.
  • We use `node-fetch` to make an HTTP request to the provided URL.
  • We check if the response is successful using `response.ok`. If not, we throw an error.
  • We use a `try…catch` block to handle potential errors during the fetch operation.

Compile and test:

npx tsc
npm start fetch-data https://jsonplaceholder.typicode.com/todos/1
npm start fetch-data invalid-url

The first command should fetch and display the JSON data. The second should display an error message if the URL is invalid or if there’s an issue with the fetch operation.

Testing Your CLI

Testing is essential for ensuring your CLI works correctly. While this is a simple example, you can write unit tests using a testing framework like Jest or Mocha to test your CLI’s functionality. For example, you might test that the ‘hello’ command correctly displays the greeting or that the ‘fetch-data’ command handles errors appropriately.

Best Practices and Advanced Features

Here are some best practices and advanced features to consider when building CLIs:

  • Input Validation: Validate user input to prevent errors and unexpected behavior.
  • Configuration Files: Allow users to configure your CLI using configuration files (e.g., `.myclirc.json`).
  • Interactive Prompts: Use libraries like `inquirer` to create interactive prompts for collecting user input.
  • Progress Indicators: Use libraries like `ora` to display progress indicators for long-running tasks.
  • Help Messages: Ensure your CLI has clear and informative help messages. The `commander` library automatically generates help messages for your commands and options. You can access it by running `npm start –help` or `npm start hello –help`.
  • Subcommands: For complex applications, consider using subcommands to organize your CLI’s functionality (e.g., `git commit`, `git push`).
  • Color and Styling: Use libraries like `chalk` to add color and styling to your CLI’s output, improving readability and user experience.
  • Environment Variables: Use environment variables to configure your CLI (e.g., API keys, database connection strings).
  • Logging: Implement proper logging to help with debugging and monitoring.

Common Mistakes and How to Fix Them

Here are some common mistakes developers make when building CLIs and how to fix them:

  • Incorrect Argument Parsing: Ensure you are using the correct methods to parse arguments and options. Double-check your `commander` syntax.
  • Unhandled Errors: Always handle potential errors, especially when dealing with external resources (e.g., network requests, file I/O). Use `try…catch` blocks and provide informative error messages.
  • Lack of Input Validation: Always validate user input to prevent unexpected behavior. Use validation libraries or write custom validation logic.
  • Poor User Experience: Design your CLI with the user in mind. Provide clear help messages, informative output, and a consistent user interface. Consider using color and styling to improve readability.
  • Ignoring Testing: Write unit tests to ensure your CLI works correctly. Testing helps catch bugs early and ensures your CLI is robust.
  • Not Using TypeScript Effectively: Leverage TypeScript’s strong typing to catch errors at compile time and improve code maintainability. Define interfaces and types for your data structures and function parameters.

Summary / Key Takeaways

In this tutorial, we’ve covered the fundamentals of building a CLI with TypeScript. We’ve explored how to set up a project, define commands and options, handle arguments, and handle errors. By using libraries like `commander`, you can create powerful and user-friendly CLIs. Remember to follow best practices, such as input validation, error handling, and testing, to build robust and maintainable command-line applications. As you gain more experience, explore advanced features like interactive prompts, progress indicators, and color styling to enhance your CLI’s functionality and user experience. Building CLIs can significantly improve your productivity by automating tasks and providing a direct way to interact with your applications. Embrace the power of the command line, and start building your own CLI tools today!

This is just the beginning. The world of CLI development is vast, offering endless possibilities. You can extend this foundation to build more sophisticated CLIs tailored to your specific needs. With practice and exploration, you’ll become proficient in creating powerful and efficient command-line tools that streamline your workflow and boost your productivity.

More posts