@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/types: case checking library (CamelCase, snake_case, kebab-case)

@magic/log, @magic/cases 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.jsimport{cli}from'@magic/cli'constres=cli({commands: [['cmd1','cmd1alias'],'cmd2'],options: [['--flag1','-f1'],['--flag2','-f2'],],default: {'--default-key': 'default-value',},required: ['--default-key'],single: ['--default-key'],env: [[['--production','--prod','--p','-p'],'NODE_ENV','production']],pure: true,// do neither change process.argv nor process.envpureArgv: true,// do not change process.argvpureEnv: true,// do not change process.env})console.log(res)

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','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.jscmd1// 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.jsimportclifrom'@magic/cli'constargs={commands: [['magic','m']],options: [['--spell','-s']],env: [[['dev','development'],'NODE_ENV','development']],help: 'custom help text',}constargv=cli(args)

then run ./bin.js without arguments

./bin.js
// help output
`@magic/cli wrapped cli.custom help textcli commandsmagic - 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

importclifrom'@magic/cli'constargs={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'],},}constargv=cli(args)// running./bin.js// without arguments// help output`cli namecustom help textcommands:magic - aliases: ["m"]flags:--spell - aliases: ["-s"]environment switches:dev: set process.NODE_ENV to development - aliases ["development"]`

clean

some cli arguments will be expected to return a string instead of a list of arguments.

this can be achieved using the single array

constargs={options: [['--single','-s']],single: ['--single'],}constres=cli(args)console.log(res)

required

some cli arguments will be required.

this can be achieved using the required array.

if a required field is missing, a error message and the help will be shown.

constargs={options: [['--required','-r']],required: ['--required'],}constres=cli(args)console.log(res)

configuration

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

pure

constargs={pure: false,// set to true to prevent changes to process.argv and process.envpureEnv: false,// set to true to prevent changes to process.envpureArgv: false,// set to true to prevent changes to process.argv}cli(args)

prepend/append

process.argv values can be prepended and appended

importclifrom'@magic/cli'constargs={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

importclifrom'@magic/cli'constargs={options: [['--default-key'],],default: {'--default-key': 'default-value',},}constargv=cli(args)// returns{argv: {'--default-key': 'default-value',},}

Changelog

0.0.1

first release

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

• args can be set to be single now, making them return a .join(' ')ed string instead of an array
• args can be set to be required now, making the cli error and show the help if they are not.

0.0.17

required args can now be an array. this allows '--a' or '--b' to be required. errors if both are given.

0.0.18

• the command cli-name all now automagically sets all available commands to true.
• command keys will always be set to a boolean, return false if task is supposed to not be active.

0.0.19

regression: calling cli that has commands without commands will show help again.

0.0.20

regression: make commands only have keys for active commands again

0.0.21

finally get rid of the command regressions

0.0.22

• add cli.prompt to get user input.
• do not error if args.options is empty
• exec and spawn now are separate functions corresponding to node builtins

0.0.23

• cli.prompt: change call signature, remove PasswordStream

0.0.24

• fix required node version
• update dependencies

0.0.25

• prompt now has a yesDefault option
• prompt will add y/N or Y/n to the prompt message if it is missing

0.0.26

• default help arguments are now output by default.

0.0.27

nicer output for prompt messages

0.0.28

bump required node version to 14.2.0

0.0.29

update dependencies

0.0.30

• update dependencies

0.0.31

• bump required node version to 14.15.4
• update dependencies

0.0.32

update dependencies

0.0.33

update dependencies

0.0.34

update dependencies

0.0.35

• parse now can get an opts object as third argument to overwrite child_process.exec options
• help.argToHelp now errors if the first argument is not an array, before errors only got triggered by falsy arg.
• exec now uses @magic/error for errors.
• exec does not trim() the result.
• findLongestString sorts by length and then alphabetically
• export execFile
• update dependencies

0.0.36

update dependencies

0.0.37

update dependencies

0.0.38

update dependencies

0.0.39

• update devdependencies
• parse.argv does not error if args do not have a length

0.0.40

update dependencies

0.0.41

update dependencies

0.0.42

update dependencies

0.0.43

update dependencies

0.0.44

• update dependencies
• add colors to default arg output

0.0.45

• help.example can be an array
• update dependencies
• cli.prompt - msg can be an array

0.0.46

• cli.exec allows stderrToStdout redirect config option
• update dependencies

0.0.47

• rename .mjs to js
• add more tests
• update dependencies

0.0.48

• types changed to allow correct props when calling /src/index.js cli function

0.0.49

• update dependencies

0.0.50

• remove empty test file
• types: add single to ParseProps
• update dependencies

0.0.51

• exec and execFile options are correctly typed

0.0.52

• actually publish the types from 0.0.51.

0.0.53

• export exec, execFile and spawn option types

0.0.54

• update types
• update dependencies

0.0.55

• update dependencies

0.0.56 - unreleased

• ...