# @jakubmazanec/args

> TypeScript-first library for parsing command line arguments.

Latest version **2.0.18** (published 2026-08-05) · LGPL-3.0-only license · 0 weekly downloads

## Install

```sh
npm install @jakubmazanec/args
pnpm add @jakubmazanec/args
yarn add @jakubmazanec/args
bun add @jakubmazanec/args
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 2.0.18 |
| Published | 2026-08-05 |
| First published | 2023-05-04 |
| Weekly downloads | 0 |
| License | LGPL-3.0-only |
| TypeScript types | none |
| Module format | ESM |
| Node | ^24.3.0 |
| Dependencies | 3 |
| Unpacked size | 195.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 2 |
| Author | Jakub Mazanec |
| Maintainers | jakubmazanec |

## Links

- npm: https://www.npmjs.com/package/@jakubmazanec/args
- Repository: https://github.com/jakubmazanec/tools
- Homepage: https://github.com/jakubmazanec/tools#readme
- Issues: https://github.com/jakubmazanec/tools/issues
- npm.io page: https://npm.io/package/@jakubmazanec/args

## Dependencies (3)

- [lodash](https://npm.io/package/lodash.md) ^4.18.1
- [@jakubmazanec/error](https://npm.io/package/@jakubmazanec/error.md) ^3.0.0
- [@jakubmazanec/ts-utils](https://npm.io/package/@jakubmazanec/ts-utils.md) ^3.0.0

## Recent versions

- 2.0.18 (latest) — 2026-08-05
- 2.0.19-unstable.72f063e3 (unstable) — 2026-08-13
- 2.0.18-next.c37a15f9 (next) — 2026-08-05
- 2.0.18-unstable.1ba662ab — 2026-08-05
- 2.0.18-next.1031336f — 2026-08-04
- 2.0.18-unstable.3883579b — 2026-08-04
- 2.0.18-unstable.8731a3c6 — 2026-08-04
- 2.0.18-unstable.0b259717 — 2026-08-04
- 2.0.18-unstable.b78aa229 — 2026-08-04
- 2.0.18-next.e190aac1 — 2026-08-03
- 2.0.18-unstable.c0c3b2d0 — 2026-08-03
- 2.0.18-next.9c9a8b78 — 2026-08-03
- 2.0.18-next.e659d093 — 2026-08-02
- 2.0.18-unstable.f507ff42 — 2026-08-02
- 2.0.18-unstable.f50b9d9c — 2026-08-02
- … 538 more at https://npm.io/package/@jakubmazanec/args/versions

## README

<!-- header -->
<div align="center">

# @jakubmazanec/args

TypeScript-first library for parsing command line arguments.
</div>
<!-- header -->

## Installation

```sh
npm install @jakubmazanec/args
```

⚠️ This is an [ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) package!
It cannot be required from a CommonJS module.

<!-- prerequisites -->

#### Prerequisites

- Node.js 24 or later
- TypeScript 6 or later

<!-- prerequisites -->

## Usage

Main purpose of this library is to parse command line arguments. Such command line can look like
this:

```
┌─ 1 ─┐ ┌─ 2 ──┐ ┌─── 3 ───┐ ┌─── 4 ───┐ ┌─ 5 ─┐ ┌ 6 ┐ ┌─── 7 ───┐    ┌─────── 8 ──────┐
binname do stuff --key value --key=value -key -K -aBCd foo bar baz -- --key value bar -B
└───────────────────────────────────────── 9 ──────────────────────────────────────────┘
```

1. Binary name. This is never passed to the parser.
2. Command name.
3. Option with a value. Option name can be in camel case or kebab case.
4. Another way to specify an option with a value.
5. Boolean options don't have to specify value to be true. Options can also be defined using a short
   option form.
6. Short options group; usually used for boolean options.
7. Parameters.
8. Rest arguments appear after the `--`; they are not parsed, but still included in the result.
9. The whole command line.

The parser is strict and returns fully typed result. You can use it by calling `parseArguments`
function with the list of arguments and parser configuration:

```TypeScript
import {parseArguments} from '@jakubmazanec/args';

let {command, parameters, options} = parseArguments(process.argv.slice(2), {
  commands: ['run', 'build'],
  parameters: [{
    description: 'File name',
    type: 'string',
    required: true,
  }],
  options: {
    help: {
      type: 'boolean'
    }
  }
});

console.log(command); // type of `command` is `'run' | 'build' | undefined`
console.log(parameters); // type of `parameters` is `[string | undefined]`
console.log(options); // type of `options` is `{help: boolean | undefined}`
```

See [`ParserConfig`](./docs/README.md#parserconfig) for more information about how to configure the
parser.

## Documentation

See [API reference](./docs) for auto-generated documentation.

## Contributing

If you want to contribute, see [CONTRIBUTING](./CONTRIBUTING.md) for details.

## License

This package is licensed under the GNU Lesser General Public License v3. See [LICENSE](./LICENSE.md)
for details.

---
_Source: https://npm.io/package/@jakubmazanec/args · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._