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

handles commands and environment.

v0.0.11+:

ecmascript modules only. no commonjs support.

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 node ecmascript module project.

npm i --save-dev --save-exact @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.

command name overload

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

flag name overload

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

those issues might get addressed in the future.

Usage

first, define the cli file

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

const res = 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
})

console.log(res)

options / argv

argv mappings handle options and option aliases

using the cli file above

./bin.mjs -f1 arg1 arg2 -f2

resulting process.argv:

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

logged javascript object

{
  argv: { '--flag1': ['arg1', arg2], '--flag2': [] },
  args: { flag1: ['arg1', 'arg2'], flag2: [] },
  // ... other fields
}

commands

cli commands will be handled too.

// call
./bin.js cmd1

// results:
{
  commands: { cmd1: true },
  // ... other fields
}

help output

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

simple help message

// ./bin.mjs

import cli from '@magic/cli'

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

const argv = cli(args)

then run ./bin.mjs without arguments

./bin.mjs

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

import cli from '@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

import cli from '@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

import cli from '@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.

0.0.4

console help output now aligns nicely

0.0.5

node 12.4.0 does not have --experimental-node-modules fladg.

0.0.6

readd --experimental-node-modules flag for 13.1.0+

0.0.7

update dependencies bump node version

0.0.8

help is shown if cli has commands but none are given

0.0.9

update dependencies

0.0.10

update dependencies

0.0.11

• parsed.args added. is copy of argv, but using camelCased keys without leading --.
• no commonjs fallback, ecmascript modules all the way
• parsed does not return aliases. env, argv, args, commands. thats it.

0.0.12

add @magic/cases dependency

0.0.13

update deps

0.0.14

--help works for cli scripts without commands too

0.0.15

cli will always provide --help and -h flags to show help

0.0.16 - unreleased

...