cac

To help you get started, we've collected the most common ways that cac is being used within popular public projects.

egoist / poi / packages / poi / bin / main.js View on Github

const cac = require('cac')
const updateNotifier = require('update-notifier')
const Poi = require('../lib')
const isPath = require('../lib/utils/isPath')
const pkg = require('../package')

require('loud-rejection')()

updateNotifier({ pkg }).notify()

// To start Poi, we will need to know which `command` you're calling
// And you can also supply options via CLI flags
const { input, flags } = cac.parse(process.argv.slice(2))

// Handle `--version` before starting Poi
if (flags.version || flags.v) {
  console.log(require('../package').version)
  process.exit()
}

// Get command from CLI input
// When there's no input or the first element of input is a file path
// We think you're in the `develop` command
// Otherwise you're in the `input[0]` command
// And the rest of input becomes the webpack `entry`
let command
let entry
if (!input[0] || isPath(input[0])) {
  command = 'develop'

View more ways to use cac

Introduction

Command And Conquer is a JavaScript library for building CLI apps.

Features

• Super light-weight: No dependency, just a single file.
• Easy to learn. There're only 4 APIs you need to learn for building simple CLIs: cli.option cli.version cli.help cli.parse.
• Yet so powerful. Enable features like default command, git-like subcommands, validation for required arguments and options, variadic arguments, dot-nested options, automated help message generation and so on.
• Developer friendly. Written in TypeScript.

Table of Contents

• Install
• Usage
  • Simple Parsing
  • Display Help Message and Version
  • Command-specific Options
  • Dash in option names
  • Brackets
  • Negated Options
  • Variadic Arguments
  • Dot-nested Options
  • Default Command
  • Supply an array as option value
  • Error Handling
  • With TypeScript
  • With Deno
• Projects Using CAC
• References
  • CLI Instance
    • cac(name?)
    • cli.command(name, description, config?)
    • cli.option(name, description, config?)
    • cli.parse(argv?)
    • cli.version(version, customFlags?)
    • cli.help(callback?)
    • cli.outputHelp()
    • cli.usage(text)
  • Command Instance
    • command.option()
    • command.action(callback)
    • command.alias(name)
    • command.allowUnknownOptions()
    • command.example(example)
    • command.usage(text)
  • Events
• FAQ
  • How is the name written and pronounced?
  • Why not use Commander.js?
• Project Stats
• Contributing
• Author

Install

yarn add cac

Usage

Simple Parsing

Use CAC as simple argument parser:

// examples/basic-usage.js
const cli = require('cac')()

cli.option('--type ', 'Choose a project type', {
  default: 'node',
})

const parsed = cli.parse()

console.log(JSON.stringify(parsed, null, 2))

Display Help Message and Version

// examples/help.js
const cli = require('cac')()

cli.option('--type [type]', 'Choose a project type', {
  default: 'node',
})
cli.option('--name ', 'Provide your name')

cli.command('lint [...files]', 'Lint files').action((files, options) => {
  console.log(files, options)
})

// Display help message when `-h` or `--help` appears
cli.help()
// Display version number when `-v` or `--version` appears
// It's also used in help message
cli.version('0.0.0')

cli.parse()

Command-specific Options

You can attach options to a command.

const cli = require('cac')()

cli
  .command('rm <dir>', 'Remove a dir')
  .option('-r, --recursive', 'Remove recursively')
  .action((dir, options) =&gt; {
    console.log('remove ' + dir + (options.recursive ? ' recursively' : ''))
  })

cli.help()

cli.parse()

A command's options are validated when the command is used. Any unknown options will be reported as an error. However, if an action-based command does not define an action, then the options are not validated. If you really want to use unknown options, use command.allowUnknownOptions.

Dash in option names

Options in kebab-case should be referenced in camelCase in your code:

cli
  .command('dev', 'Start dev server')
  .option('--clear-screen', 'Clear screen')
  .action((options) => {
    console.log(options.clearScreen)
  })

In fact --clear-screen and --clearScreen are both mapped to options.clearScreen.

Brackets

When using brackets in command name, angled brackets indicate required command arguments, while square bracket indicate optional arguments.

When using brackets in option name, angled brackets indicate that a string / number value is required, while square bracket indicate that the value can also be true.

const cli = require('cac')()

cli
  .command('deploy ', 'Deploy a folder to AWS')
  .option('--scale [level]', 'Scaling level')
  .action((folder, options) => {
    // ...
  })

cli
  .command('build [project]', 'Build a project')
  .option('--out <dir>', 'Output directory')
  .action((folder, options) =&gt; {
    // ...
  })

cli.parse()

Negated Options

To allow an option whose value is false, you need to manually specify a negated option:

cli
  .command('build [project]', 'Build a project')
  .option('--no-config', 'Disable config file')
  .option('--config </dir></dir>