Object oriented, flexible CLI tools
npm install seeli
!package dependancies
Object orientated, event driven , Interactive CLI module. Seeli aims to give you the tools to compose
A command line interface the way you want it, and otherwise, stays out of your way.
!gif
``js
const os = require('os')
const cli = require('seeli')
cli.config({
exitOnError: true
, color: 'green'
, name: 'hello'
})
const Hello = new cli.Command({
description:"displays a simple hello world command"
, name: 'world'
, ui: 'dots'
, usage: [
${cli.bold("Usage:")} ${cli.config('name')} world --interactive
,
,
]
, flags: {
name: {
type: [ String, Array ]
, shorthand: 'n'
, description: 'The name of the person to say hello to'
, required: true
}
, 'nested:value' : {
type: Number
, shorthand: 'nv'
, description: 'A nested value'
, name: 'nested'
}
, excited: {
type:Boolean
, shorthand: 'e'
, description: 'Say hello in a very excited manner'
, default:false
}
, volume:{
type: String
, choices: ['normal', 'screaming']
, description: 'Will yell at each person'
, default: 'normal'
, shorthand: 'v'
}
}
, onContent: (content) => {
// command success
// content is the final output from run function
// If a string is returned by run, it will print automatically. If it's a data
// structure, then this method can be used to display it however.
console.log(content.join(os.EOL))
}
, run: async function(cmd, data) {
const out = []
this.ui.start('processing names')
var names = Array.isArray( data.name ) ? data.name : [ data.name ]
for (var x = 0; x < names.length; x++) {
this.ui.text = (processing ${names[x]})
await new Promise((resolve) => {
setTimeout(() => {
let value = "Hello, " + names[x]
if( data.excited ){
value += '!'
}
out.push(data.volume === 'screaming' ? value.toUpperCase() : value)
resolve(true)
}, 1000 * x + 1)
})
}
this.ui.succeed('names processed successfully')
// Anything returned from run is emitted from the content event.
// Strings will automatically be written to stdout.
return out
}
})
cli.use(Hello)
cli.run()
`
now you will have a fully functional hello world command with help and an interactive walk through
`
node ./cli help world
node ./cli world --help
node ./cli world --interactive
node ./cli world --name=Mark --name=Sally --no-excited
- seeli ( C. L. I. )
- API
- Seeli.Command()
- Command Options
- Flag Options
- Nested Flags
- cmd Shape
- Seeli.run( )
- Seeli.list
- [Seeli.use( \[name ,\] cmd )](#seeliuse-name-string-cmd-command-)
- Seeli.bold( text )
- Seeli.green( text )
- Seeli.blue( text )
- Seeli.red( text )
- Seeli.yellow( text )
- Seeli.cyan( text )
- Seeli.magenta( text )
- Seeli.redBright( text )
- Seeli.blueBright( text )
- Seeli.greenBright( text )
- Seeli.yellowBright( text )
- Seeli.cyanBright( text )
- Seeli.config( key , value
)A constructor for creating a command, including its flags and run method to be executed by Seeli.run(). See Command Options on how to configure a command.
name | type | default | description
-----|:-----:|--------|-------------
description | String | "" | Used to render help outputBoolean
strict | | false | When true, commands will error when the receive unknown flagsArray
args | | null | if supplied, agrs will be used instead of process.argv
interactive | | true | If set to false, the command will not offer interactive modeString
usage | / Array | "" | A string or array of strings used to generate help textObject
flags | | {} | key value pairs used to control the command where keys are the name of the flag and the values is a configuration object for the flagArray
requires_one | | undefined | Specify the flag names where one of their values must be enteredString
ui | | dots | The kind of progress indicator your command should use. After instantiation, this becomes an instance of ora used to print output.Function
run | | no-op | An async function used as the body of the command. It will be passed a subcommand name if one was passed, and a data object containing the processed values from the command input.Command[]
commands | | [] | A list of additional command to utilize as sub commands.
| string |The type of input that is expected. Boolean types to not expect input. The present of the flag implies true. Additionally, boolean flags allow for --no- to enforce false. If you want to accept multiple values, you specify type as an array with the first value being the type you which to accept. For example [String, Array ] | string | A description of the flag in question. |
required | false | boolean | If set to true a RequiredFieldError will be emitted |
shorthand | false | string | An options short hand flag that will be expanded out to the long hand flag. |
interactive | false | boolean | If set to false the flag will omitted from interactive prompts
default | false | mixed | A value to return if the flag is omitted. |
mask | false | boolean | interactive mode only Sets the input type to masked input to hide values
choices | false | array | Used only during an interactive command. Restricts the users options only to the options specified |
multi | false | boolean | interactive mode only If choices is specified, and multi is true, this user will be presented a multi checkbox UI allowing them to pick multiple values. The return value will be an array
skip | false | boolean | interactive mode only - if set to true this flag will be omitted from the interactive command prompts |
event | false | boolean | If set to true the command will emit an event withe the same name as the flag with the value that was captured for that flag |
when | false | function | interactive mode only Receives the current user answers hash and should return true or false depending on whether or not this question should be asked.
validate | false | function | A synchronous function that receives the command object, which should return true or undefined if the value is valid. Otherwise, an error message (String) can be returned, and it will be rendered. If false is returned, a default error message is provided. Note: These are called in interactive mode as well, during which time, other flag values may not yet be present.
filter | false | function | Receives the user input and return the filtered value to be used inside the program. The value returned will be added to the Answers hash.
required_with | false | Array | A non-empty array which says that if the flag is set, then the specified other flags must also be set, i.e. "mutual inclusion."
required_without | false | Array | A non-empty array which says that if the flag is set, then none of the other specified flags may also be set, i.e. "mutual exclusion."$3
Flag names that contain a colon (
:) will be parsed as a nested value in the data that is return to you commands. You can Set arbitrarily deep values.
You can use this to automatically construct complex object. Array values are limited to primitive types`javascript
// cli --foo:bar:foobar=hello --foo:bar:baz=world --nested:array=1 --nested:array=2{
foo: {
bar: {
foobar: "hello"
, baz: "world"
}
}
, nested: {
array: [1, 2]
}
}
`$3
Functions will often be passed the
object for use inside the function. This object contains all of the user-inputted flags as well as internal fields from raw argument parsing (which can largely be ignored by the user).Example:
`js
const fs = require('fs')// ...snip
, validate: (cmd) => {
console.log('cmd contents', cmd)
// Clear the output file before each run
if (cmd.output_file) {
fs.rm(cmd.output_file, {force: true}, () => {})
}
}
`Output:
bash
cmd contents {
my_param1: 'hello',
my_param2: 'goodbye',
output_file: '/tmp/output.txt',
my_optional_param: undefined
argv: {
remain: [],
cooked: [],
original: []
},
interactive: false,
color: true,
}
`
Seeli.run( )
Executes The command line interface
Seeli.list
List of all top level registered commands
Seeli.use( [name
,] cmd )Registers a new command where the Command's
name will invoke the associated command.
Optionally, a different name can be passed as the first parameter which would override
the value of Command.name.`js
const cli = require('seeli')
const UnnamedCmd = new cli.Command()
const NamedCommand = new cli.Command({name: 'my_command'})cli.use('test', UnnamedCmd)
cli.use(NamedCommand)
cli.run()
`
Seeli.bold( text
)Wraps text in the ansi code for bold.
Seeli.green( text
)Wraps text in the ansi code for green.
Seeli.blue( text
)Wraps text in the ansi code for blue.
Seeli.red( text
)
Wraps text in the ansi code for red.Seeli.yellow( text
)Wraps text in the ansi code for yellow.
Seeli.cyan( text
)Wraps text in the ansi code for cyan.
Seeli.magenta( text
)Wraps text in the ansi code for magenta.
Seeli.redBright( text
)Wraps text in the ansi code for redBright.
Seeli.blueBright( text
)Wraps text in the ansi code for blueBright.
Seeli.greenBright( text
)Wraps text in the ansi code for greenBright.
Seeli.yellowBright( text
)Wraps text in the ansi code for yellowBright.
Seeli.cyanBright( text
)Wraps text in the ansi code for cyanBright.
Seeli.config( key
, value