@magic/cli

@magic/cli

declarative cli sanitization and execution for @magic

sanitizes cli flags from aliases to default names

rewrites process.argv accordingly

provides autogenerated --help output (that can be customized)

also handles commands and environment for you

html-docs

• dependencies
• install
• caveats
• usage
• argv
• commands
• help
• config
• pure
• append / prepend
• default

dependencies:

• @magic/log: console.log wrapper with loglevels
• @magic/types: type checking library

@magic/log and @magic/types have no dependencies.

install

be in a nodejs project.

npm i --save-dev @magic/cli

caveats

there are some quirks that need some careful consideration when designing a cli api depending on your requirements, these caveats should seldomly apply.

last argument

• if your last argument does not have a corresponding flag, it will still be assigned to the last flag prior to it.

• if one of your options gets an argument that is equal to a command, this command will be executed

• cli arguments that start with a - will always be treated as flags, not values.

those issues might get addressed in the future.

Usage

full api:

first we have to define the cli.mjs file in a commonjs file:

// ./bin.js
#!/usr/bin/env node
const path = require('path')
const spawn = require('@magic/cli')

const cmd = path.join(process.cwd(), 'path', 'to', 'your', 'bin.mjs')
const args = ['--array', 'of', 'flags', cmd]
const executable = 'node' // node is default value
spawn(args, [executable])

then we can write the bin.mjs file:

// ./bin.mjs
import { cli } from '@magic/cli/src/index.mjs'

const { argv, env, commands } = cli({
  commands: [
    ['cmd1', 'cmd1alias'],
    'cmd2',
  ],
  options: [
    ['--flag1', '-f1'],
    ['--flag2', '-f2'],
  ],
  default: [
    ['--default-key', 'default-value'],
  ],
  env: [[['--production', '--prod', '--p', '-p'], 'NODE_ENV', 'production']],
  pure: true, // do neither change process.argv nor process.env
  pureArgv: true, // do not change process.argv
  pureEnv: true, // do not change process.env
})

options / argv

argv mappings handle options and option aliases

using the cli file above

bin.js -f1 arg1 arg2 -f2

resulting process.argv:

process.argv = [
  '/path/to/bin/node',
  '/path/to/bin.js',
  '--flag1'
  'arg1',
  'arg2',
  '--flag2',
]

resulting javascript object
```javascript
argv === { '--flag1': ['arg1', arg2], '--flag2': []}

commands

cli commands can be handled too.

const cli = require('@magic/cli')

const args = {
  commands: [
    ['dev', 'development', 'start'],
    'serve',
  ],
}

const argv = cli(args)

// call
./bin.js dev serve

// results:
{
  cmds: ['dev', 'serve'],
  commands: ['dev', 'serve'],
}

help output

@magic/cli will parse your configuration and create a help text based on it.

simple help message

const cli = require('@magic/cli')

const args = {
  commands: [['magic', 'm']],
  options: [['--spell', '-s']],
  env: [[['dev', 'development'], 'NODE_ENV', 'development']],
  help: 'custom help text',
}

const argv = cli(args)

// running
./bin.js
// without arguments

// help output
`
@magic/cli wrapped cli.

custom help text

cli commands
magic - aliases: ["m"]


possible command line flags:
--spell - aliases: ["-s"]

environment switches:
dev: set NODE_ENV to development - aliases ["development"]
`

detailed help message

the help property will accept an object which maps to the args object

const cli = require('@magic/cli')

const args = {
  commands: [['magic', 'm']],
  options: [['--spell', '-s']],
  env: [[['dev', 'development'], 'NODE_ENV', 'development']],
  prepend: 'prepend',
  append: 'append',
  help: {
    name: 'cli name',
    text: 'custom help text',
    commands: {
      magic: 'magic info help text',
    },
    options: {
      '--spell': 'cast a simple spell',
    },
    env: ['dev', 'set environment to development'],
  },
}

const argv = cli(args)

// running
./bin.js
// without arguments

// help output
`
cli name

custom help text

commands:
magic - aliases: ["m"]

flags:
--spell - aliases: ["-s"]

environment switches:
dev: set process.NODE_ENV to development - aliases ["development"]
`

configuration

there are some configuration parameters that can be passed to the cli function

pure

const args = {
  pure: false,    // set to true to prevent changes to process.argv and process.env
  pureEnv: false, // set to true to prevent changes to process.env
  pureArgv: false, // set to true to prevent changes to process.argv
}

cli(args)

prepend/append

process.argv values can be prepended and appended

const cli = require('@magic/cli)

const args = {
  prepend: ['prepended']
  append: ['appended']
}

cli(args)

default

use this to set default process.argv key: value pairs that should be set if they are not

const cli = require('@magic/cli')

const args = {
  options: [
    ['--default-key'],
  ],
  default: [
    ['--default-key', 'default-value']
  ],
}

const argv = cli(args)

// returns
{
  argv: {
    '--default-key': 'default-value',
  },
}

Changelog

0.0.3

cli's should now correctly process.exit(1) on error of the spawned process.