Introduction to Caporal

Caporal is a powerful and versatile command-line interface (CLI) framework for Node.js. Designed with simplicity and efficiency in mind, it enables developers to build and manage complex CLI applications effortlessly. In this guide, we will explore a range of Caporal APIs and provide practical examples to help you get started.

Getting Started with Caporal

To begin using Caporal, install it via npm:

npm install @caporal/core

Here is an example of a basic Caporal application:

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

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

program.run();

Exploring Caporal APIs

Defining Commands and Arguments

With Caporal, you can define commands and their arguments easily:

program
  .command('sum', 'Calculate sum of two numbers')
  .argument('', 'First number', program.NUMBER)
  .argument('', 'Second number', program.NUMBER)
  .action(({ args }) => {
    console.log(`Sum: ${args.num1 + args.num2}`);
  });

Adding Options

You can add options to your commands to provide more functionality:

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

Handling Subcommands

Caporal supports subcommands for more complex CLI applications:

program
  .command('math', 'Mathematical operations')
  .command('add', 'Add numbers', { parent: 'math' })
  .argument('', 'First number', program.NUMBER)
  .argument('', 'Second number', program.NUMBER)
  .action(({ args }) => {
    console.log(`Result: ${args.num1 + args.num2}`);
  });

program.run();

Building a Complete CLI Application

Here is a complete example of a CLI application that uses the discussed APIs:

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

program
  .version('1.0.0')
  .description('A simple CLI app for demonstration')
  .command('greet', 'Greet the user')
  .argument('', 'User name')
  .option('--shout', 'Shout the greeting')
  .action(({ args, options }) => {
    let greeting = `Hello, ${args.name}!`;
    if (options.shout) {
      greeting = greeting.toUpperCase();
    }
    console.log(greeting);
  })
  
  .command('sum', 'Calculate the sum of two numbers')
  .argument('', 'First number', program.NUMBER)
  .argument('', 'Second number', program.NUMBER)
  .action(({ args }) => {
    console.log(`Sum: ${args.num1 + args.num2}`);
  })
  
  .command('math', 'Mathematical operations')
  .command('add', 'Add numbers', { parent: 'math' })
  .argument('', 'First number', program.NUMBER)
  .argument('', 'Second number', program.NUMBER)
  .action(({ args }) => {
    console.log(`Result: ${args.num1 + args.num2}`);
  });

program.run();

With Caporal, building powerful CLI applications is both easy and efficient. Use these APIs and examples to start creating your own CLI tools today.

Hash: b4f754ba37601327e7fbbc17a2b4be4c202ee18e70a2fb4d6c0441650f5033df