tsargp

tsargp is a command-line argument parsing library that helps you write clean code.

Get started with the documentation.

Demo

Test it online or install it locally:

npm i -g tsargp && complete -C tsargp tsargp

tsargp -h         # print the help message
tsargp -v         # print the package version
tsargp            # view the options' default values
tsargp ...        # play with option values
tsargp hello ...  # test the hello command

See the source.

Quick 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:

• lib
  • cli.options.spec.ts
  • cli.options.ts
  • cli.ts

Define command-line options

You should define the options and export them by default as a single object. Below is an example.

import { type Options /*...*/ } from 'tsargp';

export default {
  // definitions go here...
} as const satisfies Options;

In the documentation, you will learn about the different option types and their attributes.

Parse arguments in main script

There are multiple ways to parse the command-line arguments. Below is an example.

#!/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
  }
}

The documentation also shows how to parse them into an existing object or class instance, specify parsing flags, and emit warnings.

Validate options in test script

You should check the validity of command-line options during development. Below is an example.

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
  });
});

The documentation also shows how to check for inconsistencies in option naming, among other things.

Enable completion (optional)

You can configure shell completion to use the main script as a source of completion words or suggestions. This is handled automatically by the library. You just need to register it with the completion engine.

complete -o default -C <path_to_main_script> cli

Build

curl -fsSL https://bun.sh/install | bash
bun install   # install dependencies
bun test      # run unit tests
bun publish   # publish to npm registry