A flexible and easy-to-use command-line flag parsing library for Node.js applications.
- 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
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 asflags
and has been renamed toflg
. Starting from version3.0.0
, all updates will be published under this new package name.Migrate from
flags
toflg
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.
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
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);
- 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
Access flag values using flags.get(flagName)
or flags.FLAGS.flagName.get()
.
Flag objects also provide properties like name
, defaultValue
, currentValue
, and isSet
.
Node-Flags automatically generates help text. Access it by running your script with the --help
flag.
For testing, you can pass predefined arguments to flags.parse()
:
flags.parse(["--flag1", "--noflag2", "--flag3=value"]);
Reset flags between test cases:
flags.reset();
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.
To upgrade your project to use the new flg
package:
-
Uninstall the old
flags
package:npm uninstall flags
-
Install the new
flg
package:npm install flg
-
Update all references in your code from
flags
toflg
:// before import * as flags from "flags"; // after import * as flags from "flg";
The new versioning starts from 3.0.0
to reflect the continuity of the flags
package while aligning with semantic versioning best practices.
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 |
This project is licensed under the MIT License. See the LICENSE file for details.