@hypernym/args

A fast and ultra lightweight CLI argument parser.

Repository | Package | Releases | Discussions

pnpm add @hypernym/args

Features

• TypeScript friendly
• Fully tree-shakeable
• No dependencies

Parser

Arguments

Unprefixed inputs are stored in an array.

$ arg

# => { _: ['arg'] }

$ arg-a arg-b arg-c

# => { _: ['arg-a', 'arg-b', 'arg-c'] }

Flags

Inputs with -- prefix are parsed as flags.

By default, standalone flags with no value are defined as true.

$ --flag

# => { _: [], flag: true, }

$ --flag value

# => { _: [], flag: 'value', }

$ --flag=value

# => { _: [], flag: 'value', }

Aliases

Inputs with - prefix are parsed as aliases.

By default, standalone aliases with no value are defined as true.

$ -alias

# => { _: [], alias: true, }

$ -alias value

# => { _: [], alias: 'value', }

$ -alias=value

# => { _: [], alias: 'value', }

Ignores

• Ignores standalone inputs -- and -
• Ignores argument inputs that include =

$ arg=value -- arg-b=value -

# => { _: [] }

Usage

$ hello world --foo bar -baz -cli demo --fuz

import { createArgs } from '@hypernym/args'

interface Args {
  foo?: string
  baz?: boolean
  cli?: string
  fuz?: boolean
}

const args = createArgs<Args>()

console.log(args)

/*
{
  _: ['hello', 'world'],
  foo: 'bar',
  baz: true,
  cli: 'demo',
  fuz: true
}
*/

Options

argv

Specifies an array of values to parse as arguments.

• Type: string[] | undefined
• Default: process.argv.slice(2)

import { createArgs } from '@hypernym/args'

createArgs({
  argv: process.argv.slice(2),
})

alias

Specifies an object of alias that will be added to the parsed output with matching values.

• Type: Record<string, string | string[]> | undefined
• Default: undefined

import { createArgs } from '@hypernym/args'

createArgs({
  alias: {
    config: ['conf', 'c'],
    help: 'h',
  },
})

defaults

Specifies an object of defaults that will be added to the parsed output regardless of CLI inputs.

• Type: (Record<string, unknown> & { _?: string[] }) | undefined
• Default: undefined

import { createArgs } from '@hypernym/args'

createArgs({
  defaults: {
    _: ['value'],
    a: true,
  },
})

exclude

Specifies an array of values that will be skipped when parsing arguments.

• Type: string[] | undefined
• Default: undefined

import { createArgs } from '@hypernym/args'

createArgs({
  exclude: ['arg', '--flag', '-alias'],
})

Community

Feel free to ask questions or share new ideas.

Use the official discussions to get involved.

License

Developed in 🇭🇷 Croatia, © Hypernym Studio.

Released under the MIT license.