@magic/cli
v0.0.46
Published
declarative command line interfaces with aliasing, commands and environment sanitization
Downloads
1,574
Readme
@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.
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.mjs
import { cli } from '@magic/cli'
const res = 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.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"]
`
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
const args = {
options: [['--single', '-s']],
single: ['--single'],
}
const res = 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.
const args = {
options: [['--required', '-r']],
required: ['--required'],
}
const res = cli(args)
console.log(res)
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.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 - unreleased
- ...