cli.parse()
`

$3

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.

$3

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()
`

$3

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()
`

$3

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()
`

$3

`bash
node cli.js --include project-a


The parsed options will be:

`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)
}
`

$3

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'
`

$3

`ts
import { cac } from 'https://unpkg.com/cac/mod.ts'

const cli = cac('my-program')
`

Projects Using CAC

Projects that use CAC:

- VuePress: :memo: Minimalistic Vue-powered static site generator.
- SAO: ⚔️ Futuristic scaffolding tool.
- DocPad: 🏹 Powerful Static Site Generator.
- Poi: ⚡️ Delightful web development.
- bili: 🥂 Schweizer Armeemesser for bundling JavaScript libraries.
- Lad: 👦 Lad scaffolds a Koa webapp and API framework for Node.js.
- Lass: 💁🏻 Scaffold a modern package boilerplate for Node.js.
- Foy: 🏗 A lightweight and modern task runner and build tool for general purpose.
- Vuese: 🤗 One-stop solution for vue component documentation.
- NUT: 🌰 A framework born for microfrontends
- Feel free to add yours here...

References

💁 Check out the generated docs from source code if you want a more in-depth API references.

Below is a brief overview.

$3

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.

$3

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.

$3

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

$3

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

$3

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, SAO and all my CLI apps. It's small, simple but powerful :P

Project Stats

!Alt

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, Released under the MIT License.

Authored and maintained by egoist with help from contributors (list).

> Website · GitHub @egoist · Twitter @\_egoistlily