@magic/cli

    0.0.34 • Public • Published

    @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

    NPM version Linux Build Status Windows Build Status Coverage Status Greenkeeper badge Known Vulnerabilities

    dependencies:

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

    ...

    Install

    npm i @magic/cli

    DownloadsWeekly Downloads

    112

    Version

    0.0.34

    License

    AGPL-3.0

    Unpacked Size

    57.4 kB

    Total Files

    17

    Last publish

    Collaborators

    • jascha
    • jaeh