Introduction to Caporal

Caporal is a full-featured framework for building command-line applications in Node.js. It provides a simple API for defining commands, arguments, options, and interacting with users via the terminal. Caporal makes it easy to create powerful and user-friendly CLI tools.

Setting Up Caporal

 npm install @caporal/core 

Creating Your First Command

Let’s create a simple command that greets the user.

    const { program } = require('@caporal/core');
    program
      .command('greet', 'Greet a user')
      .argument('', 'User name')
      .action(({ args }) => {
        console.log(`Hello, ${args.name}`);
      });

    program.run();

Adding Options to Commands

Options allow users to customize the behavior of commands.

    program
      .command('greet', 'Greet a user')
      .argument('', 'User name')
      .option('--uppercase', 'Uppercase the name')
      .action(({ args, options }) => {
        let name = args.name;
        if (options.uppercase) {
          name = name.toUpperCase();
        }
        console.log(`Hello, ${name}`);
      });

    program.run();

Defining Multiple Commands

    program
      .command('greet', 'Greet a user')
      .argument('', 'User name')
      .action(({ args }) => {
        console.log(`Hello, ${args.name}`);
      });

    program
      .command('bye', 'Farewell a user')
      .argument('', 'User name')
      .action(({ args }) => {
        console.log(`Goodbye, ${args.name}`);
      });

    program.run();

Prompting for Input

Sometimes you need to prompt the user for input during the execution of a command.

    program
      .command('ask', 'Ask a question')
      .action(async () => {
        const response = await program.prompt('What is your name?');
        console.log(`Hello, ${response}`);
      });

    program.run();

Handling Errors

    program
      .command('error', 'Trigger an error')
      .action(() => {
        throw new Error("This is an error example");
      });

    program.run().catch(err => {
      console.error("An error occurred:", err.message);
    });

A Complete Example Application

Let’s put it all together and create a simple CLI application with multiple commands and options.

    const { program } = require('@caporal/core');

    program
      .command('greet', 'Greet a user')
      .argument('', 'User name')
      .option('--uppercase', 'Uppercase the name')
      .action(({ args, options }) => {
        let name = args.name;
        if (options.uppercase) {
          name = name.toUpperCase();
        }
        console.log(`Hello, ${name}`);
      });

    program
      .command('bye', 'Farewell a user')
      .argument('', 'User name')
      .action(({ args }) => {
        console.log(`Goodbye, ${args.name}`);
      });

    program
      .command('ask', 'Ask a question')
      .action(async () => {
        const response = await program.prompt('What is your name?');
        console.log(`Hello, ${response}`);
      });

    program
      .command('error', 'Trigger an error')
      .action(() => {
        throw new Error("This is an error example");
      });

    program.run().catch(err => {
      console.error("An error occurred:", err.message);
    });

Caporal provides many more features and customization options. Explore the documentation to learn more about creating complex CLI applications.

Hash: b4f754ba37601327e7fbbc17a2b4be4c202ee18e70a2fb4d6c0441650f5033df