Command And Conquer, the queen living in your command line, is a minimalistic but pluggable CLI framework.
yarn add cac
Use ./examples/simple.js
as example:
const cac = require('cac')
const cli = cac()
// Add a default command
const defaultCommand = cli.command('*', {
desc: 'The default command'
}, (input, flags) => {
if (flags.age) {
console.log(`${input[0]} is ${flags.age} years old`)
}
})
defaultCommand.option('age', {
desc: 'tell me the age'
})
// Add a sub command
cli.command('bob', {
desc: 'Command for bob'
}, () => {
console.log('This is a command dedicated to bob!')
})
// Bootstrap the CLI app
cli.parse()
Then run it:
And the Help Documentation is ready out of the box:
In many cases your app is small and doesn't even need a command:
const cli = require('cac')()
// Use default command symbol '*'
cli.command('*', option, runMyApp)
cli.parse()
Instead of using a default command, you can skip adding and running command by:
const cli = require('cac')()
// cli.argv is a getter
// bascially it's the return value of cli.parse(null, { run: false })
const { input, flags } = cli.argv
runMyApp(input, flags)
Projects that use CAC:
- SAO: ⚔️ Futuristic scaffolding tool.
- Poi: ⚡️ Delightful web development.
- bili: 🥂 Schweizer Armeemesser for bundling JavaScript libraries.
- lass: 💁🏻 Scaffold a modern package boilerplate for Node.js.
- Feel free to add yours here...
Register an option globally, i.e. for all commands
- name:
string
option name - option:
object
string
- desc:
string
description - alias:
string
Array<string>
option name alias - type:
string
option type, valid values:boolean
string
- default:
any
option default value
- desc:
- name:
string
- option:
object
string
(string
is used asdesc
)- desc:
string
description - alias:
string
Array<string>
command name alias
- desc:
- handler:
function
command handler- input:
Array<string>
cli arguments - flags:
object
cli flags
- input:
const command = cli.command('init', 'init a new project', (input, flags) => {
const folderName = input[0]
console.log(`init project in folder ${folderName}`)
})
cli.command
returns a command instance.
Same as cli.option but it adds options for specified command.
- argv:
Array<string>
Defaults toprocess.argv.slice(2)
- option
- run:
boolean
Defaults totrue
Run command after parsed argv.
- run:
Display cli helps, must be called after cli.parse()
- plugin:
Plugin
Array<Plugin>
Apply a plugin to cli instance:
cli.use(plugin(options))
function plugin(options) {
return cli => {
// do something...
}
}
A getter which simply returns cli.parse(null, { run: false })
Error handler for errors in your command handler:
cli.on('error', err => {
console.error('command failed:', err)
process.exit(1)
})
Emit after CAC parsed cli arguments:
cli.on('parsed', (command, input, flags) => {
// command might be undefined
})
- required-option - Mark an option as required for specific command.
CAC
is simpler and less opinionated comparing to commander.js
yargs
caporal.js
.
Commander.js does not support chaining option which is a feature I like a lot. It's not really actively maintained at the time of writing either.
Yargs has a powerful API, but it's so massive that my brain trembles. Meow is simple and elegant but I have to manully construct the help message, which will be annoying. And I want it to support sub-command too.
And none of them are pluggable.
So why creating a new thing instead of pull request?
I would ask me myself why there's preact
instead of PR to react
, and why yarn
instead of PR to npm
? It's obvious.
CAC is kind of like a combination of the simplicity of Meow and the powerful features of the rest. And our help log is inspired by Caporal.js, I guess it might be the most elegant one out there?
CAC, not Cac or cac, Pronounced /kɑk/
.
And this project is dedicated to our lovely C.C. sama. Maybe CAC stands for C&C as well :P
- Fork it!
- Create your feature branch:
git checkout -b my-new-feature
- Commit your changes:
git commit -am 'Add some feature'
- Push to the branch:
git push origin my-new-feature
- Submit a pull request :D
cac © egoist, Released under the MIT License.
Authored and maintained by egoist with help from contributors (list).
egoist.moe · GitHub @egoist · Twitter @_egoistlily