Skip to content

A fast and ultra lightweight CLI argument parser.

License

Notifications You must be signed in to change notification settings

hypernym-studio/args

Folders and files

NameName
Last commit message
Last commit date

Latest commit

a14a6f0 Â· Feb 25, 2025

History

43 Commits
Feb 25, 2025
Feb 25, 2025
Sep 10, 2024
Feb 25, 2025
Feb 25, 2025
Sep 24, 2023
Sep 10, 2024
Sep 24, 2023
Sep 8, 2024
Sep 24, 2023
Feb 25, 2025
Feb 25, 2025
Feb 25, 2025
Sep 8, 2024
Feb 25, 2025
Feb 25, 2025
Sep 8, 2024
Sep 8, 2024

Repository files navigation

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.