🦈 shargs (shell args) is a library for building command-line argument parsers.

[![node version][shield-node]][node] [![npm version][shield-npm]][npm-package] [![license][shield-license]][license] [![PRs Welcome][shield-prs]][contribute] [![linux unit tests status][shield-unit-tests-linux]][actions] [![macos unit tests status][shield-unit-tests-macos]][actions] [![windows unit tests status][shield-unit-tests-windows]][actions]

Features

Compose functions to build highly customizable command-line argument parsers.
35+ opt-in features, e.g. (multiple) subcommands, spelling mistake detection, default values, and (best guess) casting.
Synchronous and Promise-based asynchronous modes with async/await support.
Automatic usage documentation generation with fine-grained control over layouts and styles.
Easily extensible with your own custom parser stages and custom usage layouts.
Extensively documented and very well tested (800+ unit and integration tests).
Modular library layout with zero runtime dependencies.

Installation

Install as a bundle (recommended):

<pre> npm install --save <a href="https://github.com/Yord/shargs">shargs</a> </pre>

Install as modules:

<pre> npm install --save <a href="https://github.com/Yord/shargs-core">shargs-core</a> # core functions like <a href="#the-parsersync-function">parserSync</a> (in bundle: shargs/core or shargs) npm install --save <a href="https://github.com/Yord/shargs-opts">shargs-opts</a> # a DSL for <a href="#command-line-options">command-line options</a> (in bundle: shargs/opts) npm install --save <a href="https://github.com/Yord/shargs-parser">shargs-parser</a> # collection of <a href="#command-line-parsers">parser functions</a> (in bundle: shargs/parser) npm install --save <a href="https://github.com/Yord/shargs-usage">shargs-usage</a> # collection of <a href="#automatic-usage-documentation-generation">usage functions</a> (in bundle: shargs/usage) npm install --save <a href="https://github.com/Yord/shargs-repl">shargs-repl</a> # <a href="#building-repls-with-shargs">build REPLs</a> powered by shargs (not in bundle) </pre>

The documentation assumes the bundle is installed, but the only difference between the bundle and modules installation is how functions are imported: The bundle uses require('shargs/opts'), while require('shargs-opts') is used by modules (note the use of / vs. -). Read installing as bundle or modules for more details.

Getting Started

<details> <summary> Describe your command and its options:

const opts = [
  stringPos('question', {desc: 'Ask a question.', required: true}),
  number('answer', ['-a', '--answer'], {desc: 'The answer.', defaultValues: [42]}),
  flag('help', ['-h', '--help'], {desc: 'Print this help message and exit.'})
]

const deepThought = command('deepThought', opts, {desc: 'Ask the Ultimate Question.'})

</summary>

The deepThought command has three command-line options:

A required string positional argument named question.
An answer number option specified with -a or --answer that should default to 42 if not given.
A help command-line flag given by -h or --help.

You may use the shargs-opts module to get a nice DSL for describing our options. However, you could have also written them out as objects yourself or could have used a different DSL.

Read up on the details in the command-line options section.

</details> <details> <summary> Declare your own command-line parser:

const parser = parserSync({
  argv: [splitShortOpts],
  opts: [setDefaultValues, requireOpts, cast],
  args: [flagsAsBools]
})

</summary>

Shargs gives you fine-grained control over how the options are parsed. By using the shargs-core and shargs-parser modules, we have build the following parser:

splitShortOpts: Short option groups like -cvzf are transformed to -c -v -z -f.
setDefaultValues: Options with default values that were not provided are set.
requireOpts: It is verified that all required options have been given.
cast: Strings are cast to other types, like numbers or booleans.
flagsAsBools: Command-line flags are transformed to booleans.

Note that you did not tell parser how exactly to do those things. Everything is nice and declarative, and the details are hidden away in the parser stages.

The parserSync function and command-line parsers sections have all the details.

</details> <details> <summary> Layout a usage documentation:

const docs = usage([synopsis, space, optsList, space, desc])

const style = {
  line: [{width: 80}],
  cols: [{width: 25}, {width: 55}]
}

</summary>

You may use shargs-usage to automatically generate a usage documentation based on a command definition (e.g. deepThought from before). The module provides all components generally found in usage documentations, like:

A synopsis, summarizing available options: e.g. deepThought (<question>) [-a|--answer] [-h|--help].
An options list (optsList), describing option details in a tabular format.

Note that shargs-usage is declarative: You only specify what components our usage documentation should have. The details on how exactly those components transform command-line options into text is hidden away.

See the automatic usage documentation generation and style sections.

</details> <details> <summary> Use the parser and the usage documentation in your program:

const argv = process.argv.slice(2)
const {errs, args} = parser(deepThought)(argv)

errs.forEach(err => console.log(err.msg))

const help = docs(deepThought)(style)
if (args.help) console.log(help)

</summary>

The command-line option DSL, the parser DSL, and the usage documentation DSL combined give you a very flexible way to write command-line programs.

Find out more in the building command-line parsers with shargs section.

</details> <details> <summary> Run your command with <code>node ./deepThought --help</code>:

deepThought (<question>) [-a|--answer] [-h|--help]                              
                                                                                
<question>               Ask a question. [required]                             
-a, --answer=<number>    The answer. [default: 42]                              
-h, --help               Print this help message and exit.                      
                                                                                
Ask the Ultimate Question.

</summary>

The automatic usage documentation generation and building command-line parsers with shargs sections have more.

</details>

Tutorials

[Beginners: Implementing a git-like interface.][shargs-tutorial-git]

Examples

[An asynchronous version of deepThought.][shargs-example-async-deepthought]
[A synchronous version of deepThought.][shargs-example-sync-deepthought]
[deepThought with three layers of configuration: A config file, environment variables, and command-line arguments.][shargs-example-sync-deepthought-config-env-argv]
[A command-line arguments SQL parser.][shargs-example-sync-sql]
[A REPL (Real Eval Print Loop) build with shargs-repl.][shargs-example-repl]

Documentation

This documentation encompasses the following shargs modules:

[shargs-opts][shargs-opts] is documented in command-line options.
[shargs-core][shargs-core] is documented in the parserSync function.
[shargs-parser][shargs-parser] is documented in command-line parsers.
[shargs-usage][shargs-usage] is documented in automatic usage documentation generation.
[shargs-repl][shargs-repl] is documented in building REPLs with shargs.

Command-line Options

Command-line options are the most important concept in shargs. They are the basis for its two main features: Command-line parsers and automatic usage documentation generation.

Shargs defines many different types of command-line options represented by objects with the following interfaces:

<table> <tr> <th>                          Type                          </th> <th>                            Interface                            </th> <th>Description</th> </tr> <tr name="flag-option"> <td><a href="#flag-option">Flag Option</a></td> <td><code>{<a href="#key">key</a>,

Shargs

Install / Use

README

Features

Installation

Getting Started

Tutorials

Examples

Documentation

Command-line Options