Node-Flags

A flexible and easy-to-use command-line flag parsing library for Node.js applications.

Features

• Define flags across multiple files
• Support for various data types (string, boolean, integer, number, string list, multi-string)
• Easy-to-use API for defining and accessing flags
• Customizable flag validation
• Built-in help text generation

Installation

Install using your favorite package manager:

npm install flg
# or
yarn add flg
# or
pnpm add flg

⚠️ Important Notice: This npm package was formerly known as flags and has been renamed to flg. Starting from version 3.0.0, all updates will be published under this new package name.

Migrate from flags to flg at your convenience to ensure you receive upcoming releases and avoid the deprecation notice of the previous name.

See below for details and migration steps.

Usage

Here's a quick example of how to use Node-Flags:

import * as flags from "flg";

// Define flags
flags.defineString("name", "Anonymous", "Your name");
flags.defineInteger("age", 21, "Your age in years");
flags.defineNumber("height", 1.8, "Your height in meters");
flags.defineStringList("pets", [], "List of your pets");
flags.defineMultiString("hobby", [], "Your hobbies");

// Parse command-line arguments
flags.parse();

// Access flag values
const info = [
  `Name: ${flags.get("name")}`,
  `Age: ${flags.get("age")}`,
  `Height: ${flags.get("height")}m`,
  `Pets: ${flags.get("pets").join(", ")}`,
  `Hobbies:\n  ${flags.get("hobby").join("\n  ")}`,
];

console.log(info.join("\n"));

Run your script with flags:

node example.js --name="John Doe" --age=30 --height=1.75 --pets=dog,cat --hobby=reading --hobby=gaming

Defining Flags

Node-Flags provides several methods to define flags:

• defineString(name, defaultValue, description)
• defineBoolean(name, defaultValue, description)
• defineInteger(name, defaultValue, description)
• defineNumber(name, defaultValue, description)
• defineStringList(name, defaultValue, description)
• defineMultiString(name, defaultValue, description)

Each method returns a Flag object that allows further configuration:

flags
  .defineString("api-key")
  .setDefault("your-default-key")
  .setDescription("API key for authentication")
  .setValidator((value) => {
    if (value.length < 10) {
      throw new Error("API key must be at least 10 characters long");
    }
  })
  .setSecret(true);

Passing Flags

• Use double dashes for flag names: --flagname
• Separate values with an equal sign or space: --flagname=value or --flagname value
• Quote complex string values: --message="Hello, World!"
• Use -- to separate flags from additional arguments: --flag1 value1 -- arg1 arg2

Querying Flag Values

Access flag values using flags.get(flagName) or flags.FLAGS.flagName.get().

Flag objects also provide properties like name, defaultValue, currentValue, and isSet.

Help Text

Node-Flags automatically generates help text. Access it by running your script with the --help flag.

Testing

For testing, you can pass predefined arguments to flags.parse():

flags.parse(["--flag1", "--noflag2", "--flag3=value"]);

Reset flags between test cases:

flags.reset();

Package name update

The original release of flags version 0.2.2 has been republished as flg version 3.0.0. This change was made to ensure consistency and avoid potential naming conflicts.

All existing releases under the original flags name are still intact, so existing applications will not break.

Migrate to flg to ensure you receive future releases.

Migration Guide

To upgrade your project to use the new flg package:

1. Uninstall the old flags package:

    npm uninstall flags

2. Install the new flg package:

    npm install flg

3. Update all references in your code from flags to flg:

   // before
   import * as flags from "flags";
   
   // after
   import * as flags from "flg";

Versioning

The new versioning starts from 3.0.0 to reflect the continuity of the flags package while aligning with semantic versioning best practices.

Release history

| Version | Date | | ---------------------------------------------------------- | ------------------------ | | flg@3.0.0 | New name going forward | | flags@0.2.2 | 2024-09-16T17:32:20.498Z | | flags@0.2.1 | 2024-09-14T00:38:28.225Z | | flags@0.2.0 | 2024-09-13T23:04:51.567Z | | flags@0.1.3 | 2015-02-27T02:29:55.285Z | | flags@0.1.2 | 2014-04-18T01:55:57.093Z | | flags@0.1.1 | 2011-11-02T19:53:15.783Z | | flags@0.1.0 | 2011-04-04T14:58:55.383Z |

License

This project is licensed under the MIT License. See the LICENSE file for details.