Introduction
tsargp is a command-line argument parsing library that helps you write clean code.
Features
| Usability-wise | Functionality-wise | Presentation-wise |
|---|---|---|
| Zero-dependency | Word completion | Help message formatting |
| Fully declarative | Option validation | Text wrapping/alignment |
| Type-checked | Option requirements | Paragraphs and lists |
| Highly configurable | Value constraints | Custom error phrases |
| Browser-compatible | Name suggestions | SGR  colors and styles |
| 30KB minified | Subcommands | Option grouping/hiding |
| ESM-native | Asynchronous callbacks | Usage strings |
| Online documentation | GNU’s short-options |
Motivation
Why use this library when there are already many good argument parsers on npm?
One of the most distinctive features is the declarative API. Very few libraries that we know of support this (at the time of writing, it’s worth mentioning meow , yargs  and oclif ). Most others have either an imperative or a fluent interface, whereas tsargp offers a way to declare all of your command-line options in a single object.
Moreover, by relying on TypeScript, it ensures that values resulting from argument parsing have accurate data types, i.e., they reflect the attributes specified in the options’ definitions. In particular, an option’s value will be a union literal if you declare a choice constraint in its definition. Even JSDoc comments are preserved in IntelliSense!
Installation
Node.js
npm add tsargpQuick Start
Define folder structure
By convention, we keep command-line options separate from the main script which uses them. Assuming your application name is cli, here’s a possible folder structure for the related source code:
- cli.options.spec.ts
- cli.options.ts
- cli.ts
Define command-line options
You should define the available options and export them by default as a single object. Below is an example. In the documentation, you will learn about the different option types and their attributes.
import { type Options /*...*/ } from 'tsargp';
export default {
// definitions go here...
} as const satisfies Options;Parse arguments in main script
There are multiple ways to parse the command-line arguments. Below is just an example. The documentation shows how to parse them into an existing object or class instance, specify parsing flags, and emit warnings.
#!/usr/bin/env node
import { parse } from 'tsargp';
import options from './cli.options.js';
try {
const values = await parse(options);
// do something with the options' values...
} catch (err) {
if (err instanceof Error) {
console.error(`${err}`); // genuine errors
process.exitCode = 1;
} else {
console.log(`${err}`); // help message, version or completion words
}
}Validate options in test script
You should check the validity of command-line options during development. The documentation also shows how to check for inconsistencies in option naming, among other things.
import { validate } from 'tsargp';
import options from './cli.options.js';
describe('cli', () => {
it('should have valid options', () => {
expect(validate(options)).resolves.toEqual({}); // no errors or warnings
// ...or you can ignore warnings that are not important to your application
});
});Enable word completion (optional)
You can configure shell completion to use the main script as a source of completion words. This is handled automatically by the library. You just need to register it with the completion builtins.
Bash
complete -o default -C <path_to_main_script> cli