[](https://npmjs.com/package/cac) [](https://npmjs.com/package/cac) [](https://circleci.com/gh/cacjs/cac/tree/master) [](https://codecov.io/gh/cacjs/cac) [](https://github.com/egoist/donate) [](https://chat.egoist.moe) [](https://packagephobia.now.sh/result?p=cac) ## Introduction **C**ommand **A**nd **C**onquer 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](#install) - [Usage](#usage) - [Simple Parsing](#simple-parsing) - [Display Help Message and Version](#display-help-message-and-version) - [Command-specific Options](#command-specific-options) - [Dash in option names](#dash-in-option-names) - [Brackets](#brackets) - [Negated Options](#negated-options) - [Variadic Arguments](#variadic-arguments) - [Dot-nested Options](#dot-nested-options) - [Default Command](#default-command) - [Supply an array as option value](#supply-an-array-as-option-value) - [Error Handling](#error-handling) - [With TypeScript](#with-typescript) - [With Deno](#with-deno) - [Projects Using CAC](#projects-using-cac) - [References](#references) - [CLI Instance](#cli-instance) - [cac(name?)](#cacname) - [cli.command(name, description, config?)](#clicommandname-description-config) - [cli.option(name, description, config?)](#clioptionname-description-config) - [cli.parse(argv?)](#cliparseargv) - [cli.version(version, customFlags?)](#cliversionversion-customflags) - [cli.help(callback?)](#clihelpcallback) - [cli.outputHelp()](#clioutputhelp) - [cli.usage(text)](#cliusagetext) - [Command Instance](#command-instance) - [command.option()](#commandoption) - [command.action(callback)](#commandactioncallback) - [command.alias(name)](#commandaliasname) - [command.allowUnknownOptions()](#commandallowunknownoptions) - [command.example(example)](#commandexampleexample) - [command.usage(text)](#commandusagetext) - [Events](#events) - [FAQ](#faq) - [How is the name written and pronounced?](#how-is-the-name-written-and-pronounced) - [Why not use Commander.js?](#why-not-use-commanderjs) - [Project Stats](#project-stats) - [Contributing](#contributing) - [Author](#author) ## Install ```bash yarn add cac ``` ## Usage ### Simple Parsing Use CAC as simple argument parser: ```js // 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 ```js // 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. ```js const cli = require('cac')() cli .command('rm ', 'Remove a dir') .option('-r, --recursive', 'Remove recursively') .action((dir, options) => { 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`](#commandallowunknownoptions). ### Dash in option names Options in kebab-case should be referenced in camelCase in your code: ```js 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`. ```js 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 ', 'Output directory') .action((folder, options) => { // ... }) cli.parse() ``` ### Negated Options To allow an option whose value is `false`, you need to manually specify a negated option: ```js cli .command('build [project]', 'Build a project') .option('--no-config', 'Disable config file') .option('--config ', 'Use a custom config file') ``` This will let CAC set the default value of `config` to true, and you can use `--no-config` flag to set it to `false`. ### Variadic Arguments The last argument of a command can be variadic, and only the last argument. To make an argument variadic you have to add `...` to the start of argument name, just like the rest operator in JavaScript. Here is an example: ```js const cli = require('cac')() cli .command('build [...otherFiles]', 'Build your app') .option('--foo', 'Foo option') .action((entry, otherFiles, options) => { console.log(entry) console.log(otherFiles) console.log(options) }) cli.help() cli.parse() ``` ### Dot-nested Options Dot-nested options will be merged into a single option. ```js const cli = require('cac')() cli .command('build', 'desc') .option('--env ', 'Set envs') .example('--env.API_SECRET xxx') .action((options) => { console.log(options) }) cli.help() cli.parse() ``` ### Default Command Register a command that will be used when no other command is matched. ```js const cli = require('cac')() cli // Simply omit the command name, just brackets .command('[...files]', 'Build files') .option('--minimize', 'Minimize output') .action((files, options) => { console.log(files) console.log(options.minimize) }) cli.parse() ``` ### Supply an array as option value ```bash node cli.js --include project-a # The parsed options will be: # { include: 'project-a' } node cli.js --include project-a --include project-b # The parsed options will be: # { include: ['project-a', 'project-b'] } ``` ### Error Handling To handle command errors globally: ```js try { // Parse CLI args without running the command cli.parse(process.argv, { run: false }) // Run the command yourself // You only need `await` when your command action returns a Promise await cli.runMatchedCommand() } catch (error) { // Handle error here.. // e.g. // console.error(error.stack) // process.exit(1) } ``` ### With TypeScript First you need `@types/node` to be installed as a dev dependency in your project: ```bash yarn add @types/node --dev ``` Then everything just works out of the box: ```js const { cac } = require('cac') // OR ES modules import { cac } from 'cac' ``` ### With Deno ```ts import { cac } from 'https://unpkg.com/cac/mod.ts' const cli = cac('my-program') ``` ## Projects Using CAC Projects that use **CAC**: - [VuePress](https://github.com/vuejs/vuepress): :memo: Minimalistic Vue-powered static site generator. - [SAO](https://github.com/egoist/sao): ⚔️ Futuristic scaffolding tool. - [DocPad](https://github.com/docpad/docpad): 🏹 Powerful Static Site Generator. - [Poi](https://github.com/egoist/poi): ⚡️ Delightful web development. - [bili](https://github.com/egoist/bili): 🥂 Schweizer Armeemesser for bundling JavaScript libraries. - [Lad](https://github.com/ladjs/lad): 👦 Lad scaffolds a Koa webapp and API framework for Node.js. - [Lass](https://github.com/lassjs/lass): 💁🏻 Scaffold a modern package boilerplate for Node.js. - [Foy](https://github.com/zaaack/foy): 🏗 A lightweight and modern task runner and build tool for general purpose. - [Vuese](https://github.com/vuese/vuese): 🤗 One-stop solution for vue component documentation. - [NUT](https://github.com/nut-project/nut): 🌰 A framework born for microfrontends - Feel free to add yours here... ## References **💁 Check out [the generated docs](https://cac-api-doc.egoist.sh/classes/_cac_.cac.html) from source code if you want a more in-depth API references.** Below is a brief overview. ### CLI Instance CLI instance is created by invoking the `cac` function: ```js const cac = require('cac') const cli = cac() ``` #### cac(name?) Create a CLI instance, optionally specify the program name which will be used to display in help and version message. When not set we use the basename of `argv[1]`. #### cli.command(name, description, config?) - Type: `(name: string, description: string) => Command` Create a command instance. The option also accepts a third argument `config` for additional command config: - `config.allowUnknownOptions`: `boolean` Allow unknown options in this command. - `config.ignoreOptionDefaultValue`: `boolean` Don't use the options's default value in parsed options, only display them in help message. #### cli.option(name, description, config?) - Type: `(name: string, description: string, config?: OptionConfig) => CLI` Add a global option. The option also accepts a third argument `config` for additional option config: - `config.default`: Default value for the option. - `config.type`: `any[]` When set to `[]`, the option value returns an array type. You can also use a conversion function such as `[String]`, which will invoke the option value with `String`. #### cli.parse(argv?) - Type: `(argv = process.argv) => ParsedArgv` ```ts interface ParsedArgv { args: string[] options: { [k: string]: any } } ``` When this method is called, `cli.rawArgs` `cli.args` `cli.options` `cli.matchedCommand` will also be available. #### cli.version(version, customFlags?) - Type: `(version: string, customFlags = '-v, --version') => CLI` Output version number when `-v, --version` flag appears. #### cli.help(callback?) - Type: `(callback?: HelpCallback) => CLI` Output help message when `-h, --help` flag appears. Optional `callback` allows post-processing of help text before it is displayed: ```ts type HelpCallback = (sections: HelpSection[]) => void interface HelpSection { title?: string body: string } ``` #### cli.outputHelp() - Type: `() => CLI` Output help message. #### cli.usage(text) - Type: `(text: string) => CLI` Add a global usage text. This is not used by sub-commands. ### Command Instance Command instance is created by invoking the `cli.command` method: ```js const command = cli.command('build [...files]', 'Build given files') ``` #### command.option() Basically the same as `cli.option` but this adds the option to specific command. #### command.action(callback) - Type: `(callback: ActionCallback) => Command` Use a callback function as the command action when the command matches user inputs. ```ts type ActionCallback = ( // Parsed CLI args // The last arg will be an array if it's a variadic argument ...args: string | string[] | number | number[] // Parsed CLI options options: Options ) => any interface Options { [k: string]: any } ``` #### command.alias(name) - Type: `(name: string) => Command` Add an alias name to this command, the `name` here can't contain brackets. #### command.allowUnknownOptions() - Type: `() => Command` Allow unknown options in this command, by default CAC will log an error when unknown options are used. #### command.example(example) - Type: `(example: CommandExample) => Command` Add an example which will be displayed at the end of help message. ```ts type CommandExample = ((name: string) => string) | string ``` #### command.usage(text) - Type: `(text: string) => Command` Add a usage text for this command. ### Events Listen to commands: ```js // Listen to the `foo` command cli.on('command:foo', () => { // Do something }) // Listen to the default command cli.on('command:!', () => { // Do something }) // Listen to unknown commands cli.on('command:*', () => { console.error('Invalid command: %s', cli.args.join(' ')) process.exit(1) }) ``` ## FAQ ### How is the name written and pronounced? CAC, or cac, pronounced `C-A-C`. This project is dedicated to our lovely C.C. sama. Maybe CAC stands for C&C as well :P ### Why not use Commander.js? CAC is very similar to Commander.js, while the latter does not support dot nested options, i.e. something like `--env.API_SECRET foo`. Besides, you can't use unknown options in Commander.js either. _And maybe more..._ Basically I made CAC to fulfill my own needs for building CLI apps like [Poi](https://poi.js.org), [SAO](https://sao.vercel.app) and all my CLI apps. It's small, simple but powerful :P ## Project Stats  ## Contributing 1. Fork it! 2. Create your feature branch: `git checkout -b my-new-feature` 3. Commit your changes: `git commit -am 'Add some feature'` 4. Push to the branch: `git push origin my-new-feature` 5. Submit a pull request :D ## Author **CAC** © [EGOIST](https://github.com/egoist), Released under the [MIT](./LICENSE) License.
Authored and maintained by egoist with help from contributors ([list](https://github.com/cacjs/cac/contributors)). > [Website](https://egoist.sh) · GitHub [@egoist](https://github.com/egoist) · Twitter [@\_egoistlily](https://twitter.com/_egoistlily)