![\"2017-07-26](\"https://user-images.githubusercontent.com/8784712/28623641-373450f4-7249-11e7-854d-1b076dab274d.png\")
\n\n[](https://npmx.dev/package/cac) [](https://npmx.dev/package/cac) [](https://circleci.com/gh/cacjs/cac/tree/master) [](https://codecov.io/gh/cacjs/cac) [](https://github.com/egoist/donate) [](https://packagephobia.now.sh/result?p=cac)\n\n## Introduction\n\n**C**ommand **A**nd **C**onquer is a JavaScript library for building CLI apps.\n\n## Features\n\n- **Super light-weight**: No dependency, just a single file.\n- **Easy to learn**. There're only 4 APIs you need to learn for building simple CLIs: `cli.option` `cli.version` `cli.help` `cli.parse`.\n- **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.\n- **Developer friendly**. Written in TypeScript.\n\n## Install\n\n```bash\nnpm i cac\n```\n\n## Usage\n\n### Simple Parsing\n\nUse CAC as simple argument parser:\n\n```js\n// examples/basic-usage.js\nimport cac from 'cac'\nconst cli = cac()\n\ncli.option('--type ![\"2018-11-26](\"https://user-images.githubusercontent.com/8784712/48981576-2a871000-f112-11e8-8151-80f61e9b9908.png\")
\n\n### Display Help Message and Version\n\n```js\n// examples/help.js\nimport cac from 'cac'\nconst cli = cac()\n\ncli.option('--type [type]', 'Choose a project type', {\n default: 'node',\n})\ncli.option('--name ![\"2018-11-25](\"https://user-images.githubusercontent.com/8784712/48979012-acb20d00-f0ef-11e8-9cc6-8ffca00ab78a.png\")
\n\n### Command-specific Options\n\nYou can attach options to a command.\n\n```js\nimport cac from 'cac'\nconst cli = cac()\n\ncli\n .command('rm ![\"command](\"https://user-images.githubusercontent.com/8784712/49065552-49dc8500-f259-11e8-9c7b-a7c32d70920e.png\")
\n\n### Dash in option names\n\nOptions in kebab-case should be referenced in camelCase in your code:\n\n```js\ncli\n .command('dev', 'Start dev server')\n .option('--clear-screen', 'Clear screen')\n .action((options) => {\n console.log(options.clearScreen)\n })\n```\n\nIn fact `--clear-screen` and `--clearScreen` are both mapped to `options.clearScreen`.\n\n### Brackets\n\nWhen using brackets in command name, angled brackets indicate required command arguments, while square bracket indicate optional arguments.\n\nWhen 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`.\n\n```js\nimport cac from 'cac'\nconst cli = cac()\n\ncli\n .command('deploy ![\"2018-11-25](\"https://user-images.githubusercontent.com/8784712/48979056-47125080-f0f0-11e8-9d8f-3219e0beb0ed.png\")
\n\n### Dot-nested Options\n\nDot-nested options will be merged into a single option.\n\n```js\nimport cac from 'cac'\nconst cli = cac()\n\ncli\n .command('build', 'desc')\n .option('--env ![\"2018-11-25](\"https://user-images.githubusercontent.com/8784712/48979771-6ada9400-f0fa-11e8-8192-e541b2cfd9da.png\")
\n\n### Default Command\n\nRegister a command that will be used when no other command is matched.\n\n```js\nimport cac from 'cac'\nconst cli = cac()\n\ncli\n // Simply omit the command name, just brackets\n .command('[...files]', 'Build files')\n .option('--minimize', 'Minimize output')\n .action((files, options) => {\n console.log(files)\n console.log(options.minimize)\n })\n\ncli.parse()\n```\n\n### Supply an array as option value\n\n```bash\nnode cli.js --include project-a\n# The parsed options will be:\n# { include: 'project-a' }\n\nnode cli.js --include project-a --include project-b\n# The parsed options will be:\n# { include: ['project-a', 'project-b'] }\n```\n\n### Error Handling\n\nTo handle command errors globally:\n\n```js\ntry {\n // Parse CLI args without running the command\n cli.parse(process.argv, { run: false })\n // Run the command yourself\n // You only need `await` when your command action returns a Promise\n await cli.runMatchedCommand()\n} catch (error) {\n // Handle error here..\n // e.g.\n console.error(error.stack)\n process.exit(1)\n}\n```\n\n### With TypeScript\n\nFirst you need `@types/node` to be installed as a dev dependency in your project:\n\n```bash\nnpm i @types/node --dev\n```\n\nThen everything just works out of the box:\n\n```js\nimport { cac } from 'cac'\n```\n\n### With Deno\n\n```ts\nimport { cac } from 'jsr:@cac/cac'\n\nconst cli = cac('my-program')\n```\n\n## Projects Using CAC\n\nProjects that use **CAC**:\n\n- [Vite](https://github.com/vitejs/vite): ⚡️ Next generation frontend tooling. It's fast!\n- [Vitest](https://github.com/vitest-dev/vitest) - Next generation testing framework powered by Vite.\n- [tsdown](https://github.com/rolldown/tsdown) - The elegant bundler for libraries powered by Rolldown.\n- [VuePress](https://github.com/vuejs/vuepress): :memo: Minimalistic Vue-powered static site generator.\n- [DocPad](https://github.com/docpad/docpad): ???? Powerful Static Site Generator.\n- [bili](https://github.com/egoist/bili): ???? Schweizer Armeemesser for bundling JavaScript libraries.\n- [Lad](https://github.com/ladjs/lad): ???? Lad scaffolds a Koa webapp and API framework for Node.js.\n- [Lass](https://github.com/lassjs/lass): ???????? Scaffold a modern package boilerplate for Node.js.\n- [Foy](https://github.com/zaaack/foy): ???? A lightweight and modern task runner and build tool for general purpose.\n- [Vuese](https://github.com/vuese/vuese): ???? One-stop solution for vue component documentation.\n- [NUT](https://github.com/nut-project/nut): ???? A framework born for microfrontends.\n- [Taze](https://github.com/antfu-collective/taze): ???? A modern cli tool that keeps your deps fresh.\n- Feel free to add yours here...\n\n## References\n\n**???? Check out [API reference](https://npmx.dev/package-docs/cac) from source code if you want a more in-depth API references.**\n\nBelow is a brief overview.\n\n### CLI Instance\n\nCLI instance is created by invoking the `cac` function:\n\n```js\nimport cac from 'cac'\nconst cli = cac()\n```\n\n#### cac(name?)\n\nCreate 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]`.\n\n#### cli.command(name, description, config?)\n\n- Type: `(name: string, description: string) => Command`\n\nCreate a command instance.\n\nThe option also accepts a third argument `config` for additional command config:\n\n- `config.allowUnknownOptions`: `boolean` Allow unknown options in this command.\n- `config.ignoreOptionDefaultValue`: `boolean` Don't use the options's default value in parsed options, only display them in help message.\n\n#### cli.option(name, description, config?)\n\n- Type: `(name: string, description: string, config?: OptionConfig) => CLI`\n\nAdd a global option.\n\nThe option also accepts a third argument `config` for additional option config:\n\n- `config.default`: Default value for the option.\n- `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`.\n\n#### cli.parse(argv?)\n\n- Type: `(argv = process.argv) => ParsedArgv`\n\n```ts\ninterface ParsedArgv {\n args: string[]\n options: {\n [k: string]: any\n }\n}\n```\n\nWhen this method is called, `cli.rawArgs` `cli.args` `cli.options` `cli.matchedCommand` will also be available.\n\n#### cli.version(version, customFlags?)\n\n- Type: `(version: string, customFlags = '-v, --version') => CLI`\n\nOutput version number when `-v, --version` flag appears.\n\n#### cli.help(callback?)\n\n- Type: `(callback?: HelpCallback) => CLI`\n\nOutput help message when `-h, --help` flag appears.\n\nOptional `callback` allows post-processing of help text before it is displayed:\n\n```ts\ntype HelpCallback = (sections: HelpSection[]) => void\n\ninterface HelpSection {\n title?: string\n body: string\n}\n```\n\n#### cli.outputHelp()\n\n- Type: `() => CLI`\n\nOutput help message.\n\n#### cli.usage(text)\n\n- Type: `(text: string) => CLI`\n\nAdd a global usage text. This is not used by sub-commands.\n\n### Command Instance\n\nCommand instance is created by invoking the `cli.command` method:\n\n```js\nconst command = cli.command('build [...files]', 'Build given files')\n```\n\n#### command.option()\n\nBasically the same as `cli.option` but this adds the option to specific command.\n\n#### command.action(callback)\n\n- Type: `(callback: ActionCallback) => Command`\n\nUse a callback function as the command action when the command matches user inputs.\n\n```ts\ntype ActionCallback = (\n // Parsed CLI args\n // The last arg will be an array if it's a variadic argument\n ...args: string | string[] | number | number[],\n // Parsed CLI options\n options: Options\n) => any\n\ninterface Options {\n [k: string]: any\n}\n```\n\n#### command.alias(name)\n\n- Type: `(name: string) => Command`\n\nAdd an alias name to this command, the `name` here can't contain brackets.\n\n#### command.allowUnknownOptions()\n\n- Type: `() => Command`\n\nAllow unknown options in this command, by default CAC will log an error when unknown options are used.\n\n#### command.example(example)\n\n- Type: `(example: CommandExample) => Command`\n\nAdd an example which will be displayed at the end of help message.\n\n```ts\ntype CommandExample = ((name: string) => string) | string\n```\n\n#### command.usage(text)\n\n- Type: `(text: string) => Command`\n\nAdd a usage text for this command.\n\n### Events\n\nListen to commands:\n\n```js\n// Listen to the `foo` command\ncli.addEventListener('command:foo', () => {\n // Do something\n})\n\n// Listen to the default command\ncli.addEventListener('command:!', () => {\n // Do something\n})\n\n// Listen to unknown commands\ncli.addEventListener('command:*', () => {\n console.error('Invalid command: %s', cli.args.join(' '))\n process.exit(1)\n})\n```\n\n## FAQ\n\n### How is the name written and pronounced?\n\nCAC, or cac, pronounced `C-A-C`.\n\nThis project is dedicated to our lovely C.C. sama. Maybe CAC stands for C&C as well :P\n\n![](\"http://i.giphy.com/v3FeH4swox9mg.gif\")
\n\n### Why not use Commander.js?\n\nCAC 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.\n\n_And maybe more..._\n\nBasically 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\n\n## Contributing\n\n1. Fork it!\n2. Create your feature branch: `git checkout -b my-new-feature`\n3. Commit your changes: `git commit -am 'Add some feature'`\n4. Push to the branch: `git push origin my-new-feature`\n5. Submit a pull request :D\n\n## Author\n\n**CAC** © [EGOIST](https://github.com/egoist), Released under the [MIT](./LICENSE) License.\nAuthored and maintained by egoist with help from contributors ([list](https://github.com/cacjs/cac/contributors)).\n\n> [Website](https://egoist.dev) · GitHub [@egoist](https://github.com/egoist) · Twitter [@\\_egoistlily](https://twitter.com/_egoistlily)\n","_attachments":{},"homepage":"https://github.com/cacjs/cac#readme","bugs":{"url":"https://github.com/cacjs/cac/issues"},"license":"MIT"}