seeli ( C. L. I. )

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.

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`
  , `${cli.bold("Usage:")} ${cli.config('name')} world --name=john`
  , `${cli.bold("Usage:")} ${cli.config('name')} world --name=john --name=marry --name=paul -v screaming`
  ]

, 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 )
  • 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 )
  • Seeli.config( opts `` )
    • Config Options
  • Seeli.config( key `` )
• Package Configuration
• Auto Help
• Asyncronous
• Showing Progress
• Events

API

Seeli.Command(``)

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.

Command Options

Flag Options

Nested Flags

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

// 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]
  }
}

cmd Shape

Functions will often be passed the cmd 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:

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:

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.

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 )

Sets a single configuration value (see Config Options).

Seeli.config( opts `` )

Set multiple configuration values using a single object.

Config Options

• color `` - The chalk color to use when outputting help text. default green
• name `` - the name of the primary command that is used in generated help. If this is not set, the filename is used.
• exitOnError `` - Seeli will forcefully exit the current process when an error is encountered. default false
• exitOnContent `` - Seeli will forefully exit the current process when it is passed output content from a command. default true
• plugins |[] - A list of plugins to load and execute. A plugin may be either a function, or a module id to be required. If it is a module id, the module must export a single function which will be passed the seeli instance when called.
• help `` - a file path or module name to a custom help command. This will be passed to require and must export a single command instance
  • seeli.config('help', '/path/to/help/command')

Seeli.config( key `` )

A config value to look up. Can be a dot separated key to look up nested values

Package Configuration

Alternatively, initial configuration may be provided via package.json in a top-level key - seeli. However, this is mostly for importing plugin packages that are published to a registry.

{
  "seeli": {
    "color": "blue",
    "name": "whizbang",
    "plugins": [
      "@myscope/simple-command"
    ]
  }
}

Auto Help

Seeli will generate help from the usage string and flags. You can help as a command seeli help or as a flag seeli --help

Asyncronous

Your defined run function can be an async function, or a function that returns a Promise. This allows you to do complex async operations and I/O. If an error is thrown, it will be displayed. Otherwise, the content returned from your run function will be output to stdout ( if it returned a String).

Showing Progress

Your command's run function has access to an instance of ora available in this.ui, allowing you to display progress indicators and helpful messages while you perform other work. Optionally, if this is out of scope, you may also use the instance directly from seeli. See the README in the ora repository for more info.

const cli = require('seeli')

// Inside of Command
this.ui.fail('Some error message')
this.ui.text('Update the status bar')
this.ui.info('Informational text here')

// Outside of Command
function something() {
  cli.ui.success('My function was called!')
}

Events

Instances of the seeli Command or Commands that inherit from it as also instances of the EventEmitter class. By default any flag that has its event option set to true will emit an event with the value of the flag before the run function is executed.

var EventCommand = new cli.Command({
  args:[ '--one', '--no-two']
, flags:{
    one:{
      type:Boolean
    , event:true
    }
  , two:{
      type:Boolean
    , event:true
    }
  }
, run: async function( cmd, data ){
    return data.one && data.two
  }
});

EventCommand.on('one', function( value ){
  assert.equal( true, value );
});

EventCommand.on('two', function( value ){
  assert.equal( false, value )
});

EventCommand.on('content', function( value ){
  assert.equal( false, value );
});

EventCommand.run( null );