Introduction to Caporal

Caporal is a powerful and flexible CLI framework for Node.js, designed to build performant and user-friendly command-line interfaces (CLI). It offers a smooth way to handle commands, arguments, options, and subcommands, while providing rich documentation functionality.

Installation

  npm install caporal

Basic Usage

Here’s a basic example to create a simple CLI application using Caporal:

  const { program } = require("caporal");

  program
    .version("1.0.0")
    .description("A simple CLI example")
    .argument("", "Your name")
    .action(({ args }) => {
      console.log(`Hello, ${args.name}!`);
    });

  program.parse(process.argv);

Handling Commands

Caporal makes it easy to handle multiple commands:

  program
    .command("greet", "Greets the user")
    .argument("", "Name of the user")
    .action(({ args }) => {
      console.log(`Hello, ${args.name}`);
    });

  program
    .command("bye", "Farewell message")
    .argument("", "Name of the user")
    .action(({ args }) => {
      console.log(`Goodbye, ${args.name}`);
    });

  program.parse(process.argv);

Using Options

You can use options to provide additional functionality to your commands:

  program
    .command("greet", "Greets the user")
    .argument("", "Name of the user")
    .option("--shout", "Shout the greeting")
    .action(({ args, options }) => {
      let message = `Hello, ${args.name}`;
      if (options.shout) {
        message = message.toUpperCase();
      }
      console.log(message);
    });

  program.parse(process.argv);

Subcommands

Caporal supports subcommands for complex CLI applications:

  program
    .command("user", "User management")
    .command("add", "Add a new user")
    .argument("", "Username of the new user")
    .action(({ args }) => {
      console.log(`Adding user: ${args.username}`);
    })
    .parent();

  program
    .command("list", "List all users")
    .action(() => {
      console.log("Listing users...");
    });

  program.parse(process.argv);

Creating a Real-World Example App

Let’s create a to-do list CLI app using the aforementioned APIs:

  const { program } = require("caporal");

  const tasks = [];

  program
    .command("task", "Task management")
    .command("add", "Add a new task")
    .argument("", "Name of the task")
    .action(({ args }) => {
      tasks.push(args.name);
      console.log(`Task '${args.name}' added`);
    })
    .parent()
    .command("list", "List all tasks")
    .action(() => {
      console.log("Tasks:");
      tasks.forEach((task, index) => {
        console.log(`${index + 1}. ${task}`);
      });
    });

  program.parse(process.argv);

This example illustrates how Caporal can be used to manage tasks with commands, subcommands, and options, providing a robust structure for CLI applications.

For detailed documentation, visit the Caporal official website.

Hash: b4f754ba37601327e7fbbc17a2b4be4c202ee18e70a2fb4d6c0441650f5033df