The sade npm package is a lightweight command-line interface (CLI) library for building command-line applications in Node.js. It provides a simple and fluent API to define commands, options, and their associated actions. Sade allows developers to easily parse command-line arguments, manage sub-commands, and create user-friendly CLI tools.
Command Definition
This feature allows you to define a command with required and optional arguments. The 'describe' method is used to provide a description for the command, and the 'option' method is used to define options. The 'action' method is where the functionality for the command is implemented.
const sade = require('sade');
const prog = sade('mycli <input>').
describe('Process the input file.').
option('-o, --output', 'Specify output file').
action((input, opts) => {
console.log(`Processing ${input} with output ${opts.output}`);
});
prog.parse(process.argv);Sub-commands
This feature demonstrates how to define sub-commands within a CLI application. Each sub-command can have its own description and action handler.
const sade = require('sade');
const prog = sade('mycli').
version('1.0.0');
prog.command('build').
describe('Build the project.').
action(() => {
console.log('Building the project...');
});
prog.command('deploy').
describe('Deploy the project.').
action(() => {
console.log('Deploying the project...');
});
prog.parse(process.argv);Option Parsing
This feature shows how to parse options passed to the CLI. Options can be defined with a short and long version, and their presence can be checked within the action handler.
const sade = require('sade');
const prog = sade('mycli').
option('-v, --verbose', 'Enable verbose output').
action(opts => {
if (opts.verbose) {
console.log('Verbose mode is on.');
}
});
prog.parse(process.argv);Commander is one of the most popular CLI frameworks for Node.js. It offers a similar feature set to sade, including command and option parsing, but with a more extensive API and additional features like automated help generation and custom option processing.
Yargs is another well-known package for building CLI tools. It provides a rich set of features for argument parsing, including advanced option configuration, command chaining, and context-aware help menus. Yargs is more heavyweight compared to sade and is suitable for complex CLI applications.
Meow is a simpler alternative to sade, designed for creating lightweight CLI applications with minimal setup. It offers a concise API for option parsing and help text generation. Meow is less feature-rich than sade but is a good choice for simple scripts and smaller projects.
Smooth (CLI) Operator 🎶
Sade is a small but powerful tool for building command-line interface (CLI) applications for Node.js that are fast, responsive, and helpful!
It enables default commands, git-like subcommands, option flags with aliases, default option values with type-casting, required-vs-optional argument handling, command validation, and automated help text generation!
Your app's UX will be as smooth as butter... just like Sade's voice. 😉
$ npm install --save sade
Input:
#!/usr/bin/env node
const sade = require('sade');
const prog = sade('my-cli');
prog
.version('1.0.5')
.option('--global, -g', 'An example global flag')
.option('-c, --config', 'Provide path to custom config', 'foo.config.js');
prog
.command('build <src> <dest>')
.describe('Build the source directory. Expects an `index.js` entry file.')
.option('-o, --output', 'Change the name of the output file', 'bundle.js')
.example('build src build --global --config my-conf.js')
.example('build app public -o main.js')
.action((src, dest, opts) => {
console.log(`> building from ${src} to ${dest}`);
console.log('> these are extra opts', opts);
});
prog.parse(process.argv);
Output:
$ my-cli --help
Usage
$ my-cli <command> [options]
Available Commands
build Build the source directory.
For more info, run any command with the `--help` flag
$ my-cli build --help
Options
-v, --version Displays current version
-g, --global An example global flag
-c, --config Provide path to custom config (default foo.config.js)
-h, --help Displays this message
$ my-cli build --help
Description
Build the source directory.
Expects an `index.js` entry file.
Usage
$ my-cli build <src> [options]
Options
-o, --output Change the name of the output file (default bundle.js)
-g, --global An example global flag
-c, --config Provide path to custom config (default foo.config.js)
-h, --help Displays this message
Examples
$ my-cli build src build --global --config my-conf.js
$ my-cli build app public -o main.js
Define your global/program-wide version, options, description, and/or examples first.
Once you define a Command, you can't access the global-scope again.
Define all commands & options in the order that you want them to appear.
Sade will not mutate or sort your CLI for you. Global options print before local options.
Required arguments without values will error & exit
An Insufficient arguments! error will be displayed along with a help prompt.
Don't worry about manually displaying help~!
Your help text is displayed automatically... including command-specific help text!
Automatic default/basic patterns
Usage text will always append [options] & --help and --version are done for you.
Only define what you want to display!
Help text sections (example, options, etc) will only display if you provide values.
Subcommands are defined & parsed like any other command! When defining their usage, everything up until the first argument ([foo] or <foo>) is interpreted as the command string.
They should be defined in the order that you want them to appear in your general --help output.
Lastly, it is not necessary to define the subcommand's "base" as an additional command. However, if you choose to do so, it's recommended that you define it first for better visibility.
const prog = sade('git');
// Not necessary for subcommands to work, but it's here anyway!
prog
.command('remote')
.describe('Manage set of tracked repositories')
.action(opts => {
console.log('~> Print current remotes...');
});
prog
.command('remote add <name> <url>', 'Demo...')
.action((name, url, opts) => {
console.log(`~> Adding a new remote (${name}) to ${url}`);
});
prog
.command('remote rename <old> <new>', 'Demo...')
.action((old, nxt, opts) => {
console.log(`~> Renaming from ${old} to ${nxt}~!`);
});
Type: String
Returns: Program
The name of your bin/program. Returns the Program itself, wherein all other methods are available.
Create a new Command for your Program. This changes the current state of your Program.
All configuration methods (prog.describe, prog.action, etc) will apply to this Command until another Command has been created!
Type: String
The usage pattern for your current Command. This will be included in the general or command-specific --help output.
Required arguments are wrapped with < and > characters; for example, <foo> and <bar>.
Optional arguments are wrapped with [ and ] characters; for example, [foo] and [bar].
All arguments are positionally important, which means they are passed to your current Command's handler function in the order that they were defined.
When optional arguments are defined but don't receive a value, their positionally-equivalent function parameter will be undefined.
Important: You must define & expect required arguments before optional arguments!
sade('foo')
.command('greet <adjective> <noun>')
.action((adjective, noun, opts) => {
console.log(`Hello, ${adjective} ${noun}!`);
})
.command('drive <vehicle> [color] [speed]')
.action((vehicle, color, speed, opts) => {
let arr = ['Driving my'];
arr.push(color ? `${color} ${vehicle}` : vehicle);
speed && arr.push(`at ${speed}`);
opts.yolo && arr.push('...YOLO!!');
let str = arr.join(' ');
console.log(str);
});
$ foo greet beautiful person
# //=> Hello, beautiful person!
$ foo drive car
# //=> Driving my car
$ foo drive car red
# //=> Driving my red card
$ foo drive car blue 100mph --yolo
# //=> Driving my blue car at 100mph ...YOLO!!
Type: String
Default: ''
The Command's description. The value is passed directly to prog.describe.
Type: Object
Default: {}
Type: Boolean
Manually set/force the current Command to be the Program's default command. This ensures that the current Command will run if no command was specified.
Important: If you run your Program without a Command and without specifying a default command, your Program will exit with a
No command specifiederror.
const prog = sade('greet');
prog.command('hello');
//=> only runs if :: `$ greet hello`
// $ greet
//=> error: No command specified.
prog.command('howdy', '', { default:true });
//=> runs as `$ greet` OR `$ greet howdy`
// $ greet
//=> runs 'howdy' handler
// $ greet foobar
//=> error: Invalid command
Add a description to the current Command.
Type: String|Array
The description text for the current Command. This will be included in the general or command-specific --help output.
Internally, your description will be separated into an Array of sentences.
For general --help output, only the first sentence will be displayed. However, all sentences will be printed for command-specific --help text.
Note: Pass an
Arrayif you don't want internal assumptions. However, the first item is always displayed in general help, so it's recommended to keep it short.
Attach a callback to the current Command.
Type: Function
The function to run when the current Command is executed.
Its parameters are based (positionally) on your Command's usage definition.
All options, flags, and extra/unknown values are included as the last parameter.
Note: Optional arguments are also passed as parameters & may be
undefined!
sade('foo')
.command('cp <src> <dest>')
.option('-f, --force', 'Overwrite without confirmation')
.option('-c, --clone-dir', 'Copy files to additional directory')
.option('-v, --verbose', 'Enable verbose output')
.action((src, dest, opts) => {
console.log(`Copying files from ${src} --> ${dest}`);
opts.c && console.log(`ALSO copying files from ${src} --> ${opts['clone-dir']}`);
console.log('My options:', opts);
})
// $ foo cp original my-copy -v
//=> Copying files from original --> my-copy
//=> My options: { _:[], v:true, verbose:true }
// $ foo cp original my-copy --clone-dir my-backup
//=> Copying files from original --> my-copy
//=> ALSO copying files from original --> my-backup
//=> My options: { _:[], c:'my-backup', 'clone-dir':'my-backup' }
Add an example for the current Command.
Type: String
The example string to add. This will be included in the general or command-specific --help output.
Note: Your example's
strwill be prefixed with your Programs'sname.
Add an Option to the current Command.
Type: String
The Option's flags, which may optionally include an alias.
You may use a comma (,) or a space ( ) to separate the flags.
Note: The short & long flags can be declared in any order. However, the alias will always be displayed first.
Important: If using hyphenated flag names, they will be accessible as declared within your
action()handler!
prog.option('--global'); // no alias
prog.option('-g, --global'); // alias first, comma
prog.option('--global -g'); // alias last, space
// etc...
Type: String
The description for the Option.
Type: String
The default value for the Option.
Flags and aliases, if parsed, are true by default. See mri for more info.
Note: You probably only want to define a default
valueif you're expecting aStringorNumbervalue type.
If you do pass a String or Number value type, your flag value will be casted to the same type. See mri#options.default for info~!
The --version and -v flags will automatically output the Program version.
Type: String
Default: 0.0.0
The new version number for your Program.
Note: Your Program
versionis0.0.0until you change it.
Parse a set of CLI arguments.
Type: Array
Your Program's process.argv input.
Important: Do not
.slice(2)! Doing so will break parsing~!
Type: Object
Default: {}
Additional process.argv parsing config. See mri's options for details.
Important: These values override any internal values!
prog
.command('hello')
.option('-f, --force', 'My flag');
//=> currently has alias pair: f <--> force
prog.parse(process.argv, {
alias: {
f: ['foo', 'fizz']
},
default: {
abc: 123
}
});
//=> ADDS alias pair: f <--> foo
//=> REMOVES alias pair: f <--> force
//=> ADDS alias pair: f <--> fizz
//=> ADDS default: abc -> 123 (number)
Type: Boolean
Default: false
If true, Sade will not immediately execute the action handler. Instead, parse() will return an object of { name, args, handler } shape, wherein the name is the command name, args is all arguments that would be passed to the action handler, and handler is the function itself.
From this, you may choose when to run the handler function. You also have the option to further modify the args for any reason, if needed.
let { name, args, handler } = prog.parse(process.argv, { lazy:true });
console.log('> Received command: ', name);
// later on...
handler.apply(null, args);
Manually display the help text for a given command. If no command name is provided, the general/global help is printed.
Your general and command-specific help text is automatically attached to the --help and -h flags.
Note: You don't have to call this directly! It's automatically run when you
bin --help
Type: String
Default: null
The name of the command for which to display help. Otherwise displays the general help.
MIT © Luke Edwards
FAQs
Smooth (CLI) operator 🎶
The npm package sade receives a total of 3,000,485 weekly downloads. As such, sade popularity was classified as popular.
We found that sade demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.