https://github.com/adhamu/arge
A tiny package to parse CLI flags and arguments into an object.
https://github.com/adhamu/arge
argparse argv cli flags node
Last synced: 3 months ago
JSON representation
A tiny package to parse CLI flags and arguments into an object.
- Host: GitHub
- URL: https://github.com/adhamu/arge
- Owner: adhamu
- License: mit
- Created: 2022-05-03T11:59:01.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-09-26T11:36:40.000Z (over 1 year ago)
- Last Synced: 2025-02-11T06:35:20.510Z (3 months ago)
- Topics: argparse, argv, cli, flags, node
- Language: TypeScript
- Homepage:
- Size: 357 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Arge
A tiny package to parse CLI flags and arguments into an object.
## Installation
```shell
yarn add arge
# or
npm i arge
```
## Usage
```javascript
const { arge } = require('arge')
// or
import { arge } from 'arge'
```
Then:
```javascript
const args = arge(process.argv)
```
This will return arguments parsed from `process.argv` like this:
```shell
node app.js --dry-run --mode=development --test=false --retries=100
```
...into an object similar to below:
```json
{
"dryRun": true,
"mode": "development",
"test": false,
"retries": 100
}
```
## Typescript
For type safety, `arge` will accept a generic for typing the resulting object.
### Example
```typescript
const { foo, bar } = arge(process.argv)
```
In the above scenario, `foo` and `bar` will report the following:
> Property 'foo' does not exist on type 'unknown'
> Property 'bar' does not exist on type 'unknown'
To address this, we can apply a generic:
```typescript
interface Args {
foo: string
bar: number
}
const { foo, bar } = arge(process.argv)
```
## API
### arge(flags, options?)
Returns a key-value pairs object of flags
#### flags
Type: `string[]`
#### options
Type: `object | undefined`
##### `isArgv`
Type: `boolean`
Default: `true`
By default, the `arge` function assumes that you have passed `process.argv`. It does this because:
> The first element will be process.execPath.
> The second element will be the path to the JavaScript file being executed
https://nodejs.org/docs/latest/api/process.html#processargv
This package will omit those two items from the output.
If you wanted to pass an arbitrary array of flags that don't come from `process.argv`, you can set this option to `false`.
For example
```typescript
const flags = [
'--dry-run',
'--mode=development',
'--test=false',
'--retries=100',
]
const args = arge(flags, { isArgv: false })
```
This would then output:
```json
{
"dryRun": true,
"mode": "development",
"test": false,
"retries": 100
}
```
##### `camelCaseKeys`
Type: `boolean`
Default: `true`
This converts hyphen separated keys into camel case. To prevent this behaviour, you can set this value to `false`.
```typescript
const flags = ['--dry-run']
const args = arge(flags, { camelCaseKeys: false })
```
This would then output:
```json
{
"dry-run": true
}
```