ulivz / cac Goto Github PK

Command And Conquer, the queen living in your command line, is a minimalistic but pluggable CLI framework.

yarn add cac

• Usage
  • No-command app
• Friends
• Documentation
  • cli.option(name, [option])
  • cli.command(name, [option], [handler])
    • command
      • command.option(name, [option])
  • cli.parse([argv], [option])
  • cli.showHelp()
  • cli.use(plugin)
  • cli.argv
  • Events
    • error
    • parsed
• FAQ
  • Why not commander.js yargs caporal.js or meow?
  • How is the name written and pronounced?
• Contributing
• Author

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.
• 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

• name: string
• option: object string (string is used as desc)
  • desc: string description
  • alias: string Array<string> command name alias
• handler: function command handler
  • input: Array<string> cli arguments
  • flags: object cli flags

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 to process.argv.slice(2)
• option
  • run: boolean Defaults to true Run command after parsed argv.

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

Commander.js and Caporal.js do not allow unknown options, Commander.js does not support chaining option.

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.

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

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

cac © egoist, Released under the MIT License.
Authored and maintained by egoist with help from contributors (list).

egoist.moe · GitHub @egoist · Twitter @_egoistlily