https://github.com/hypernym-studio/args
A fast and ultra lightweight CLI argument parser.
https://github.com/hypernym-studio/args
alias args arguments argv cli commands esm flags node parser process
Last synced: 17 days ago
JSON representation
A fast and ultra lightweight CLI argument parser.
- Host: GitHub
- URL: https://github.com/hypernym-studio/args
- Owner: hypernym-studio
- License: mit
- Created: 2023-09-24T17:20:11.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-25T13:32:32.000Z (3 months ago)
- Last Synced: 2025-04-08T02:44:42.912Z (about 1 month ago)
- Topics: alias, args, arguments, argv, cli, commands, esm, flags, node, parser, process
- Language: TypeScript
- Homepage:
- Size: 141 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Codeowners: .github/codeowners
Awesome Lists containing this project
README
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.
```sh
$ arg
# => { _: ['arg'] }
```
```sh
$ 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`.
```sh
$ --flag
# => { _: [], flag: true, }
```
```sh
$ --flag value
# => { _: [], flag: 'value', }
```
```sh
$ --flag=value
# => { _: [], flag: 'value', }
```
### Aliases
Inputs with `-` prefix are parsed as _aliases_.
By default, standalone aliases with no value are defined as `true`.
```sh
$ -alias
# => { _: [], alias: true, }
```
```sh
$ -alias value
# => { _: [], alias: 'value', }
```
```sh
$ -alias=value
# => { _: [], alias: 'value', }
```
### Ignores
- Ignores standalone inputs `--` and `-`
- Ignores argument inputs that include `=`
```sh
$ arg=value -- arg-b=value -
# => { _: [] }
```
## Usage
```sh
$ hello world --foo bar -baz -cli demo --fuz
```
```ts
import { createArgs } from '@hypernym/args'
interface Args {
foo?: string
baz?: boolean
cli?: string
fuz?: boolean
}
const args = createArgs()
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)`
```ts
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 | undefined`
- Default: `undefined`
```ts
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[] }) | undefined`
- Default: `undefined`
```ts
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`
```ts
import { createArgs } from '@hypernym/args'
createArgs({
exclude: ['arg', '--flag', '-alias'],
})
```
## Community
Feel free to ask questions or share new ideas.
Use the official [discussions](https://github.com/hypernym-studio/args/discussions) to get involved.
## License
Developed in 🇭🇷 Croatia, © Hypernym Studio.
Released under the [MIT](LICENSE.txt) license.