Security News
The Push to Ban Ransom Payments Is Gaining Momentum
Ransomware costs victims an estimated $30 billion per year and has gotten so out of control that global support for banning payments is gaining momentum.
clipanion
Advanced tools
Package description
The clipanion npm package is a powerful library for building command-line interfaces (CLIs) in Node.js. It provides a rich set of features for defining commands, parsing arguments, validating input, and generating help messages.
Command Definition
Clipanion allows you to define commands as classes, which can then be registered with a CLI instance. Each command can have its own execute method that contains the logic to be run when the command is invoked.
class MyCommand extends Command {
execute() {
console.log('Command executed!');
}
}
const cli = new Cli();
cli.register(MyCommand);
cli.runExit(process.argv.slice(2));
Argument Parsing
Clipanion provides a declarative way to define command arguments using class properties. These arguments are automatically parsed and made available within the command's execute method.
class MyCommand extends Command {
myArgument = Option.String();
execute() {
console.log(`Argument value: ${this.myArgument}`);
}
}
const cli = new Cli();
cli.register(MyCommand);
cli.runExit(process.argv.slice(2));
Input Validation
Clipanion includes built-in validation for command arguments. You can specify whether an argument is required, and Clipanion will automatically enforce this when the command is run.
class MyCommand extends Command {
myArgument = Option.String({ required: true });
execute() {
console.log(`Argument value: ${this.myArgument}`);
}
}
const cli = new Cli();
cli.register(MyCommand);
cli.runExit(process.argv.slice(2));
Help Generation
Clipanion can automatically generate help messages for your commands. You can provide descriptions, detailed information, and usage examples that will be displayed when the help command is invoked.
class MyCommand extends Command {
static usage = Command.Usage({
description: 'My command description',
details: 'Detailed information about my command',
examples: [['Example usage', 'my-cli my-command']]
});
execute() {
console.log('Command executed!');
}
}
const cli = new Cli();
cli.register(MyCommand);
cli.runExit(process.argv.slice(2));
Commander is one of the most popular CLI frameworks for Node.js. It offers a simple and expressive API for creating command-line applications. Compared to clipanion, commander has a more imperative style and does not use classes to define commands.
Yargs is another widely-used library for building CLIs. It provides a fluent interface for defining options and commands. Yargs focuses on parsing command-line arguments and generating help text, similar to clipanion, but with a different API design.
Inquirer.js is a library for creating interactive command-line user interfaces. It is often used in conjunction with other CLI libraries to gather user input through a series of questions. While it does not handle command definition or parsing like clipanion, it complements these features with its interactive prompts.
Readme
Type-safe CLI library with no runtime dependencies
⚠️ Important: This documentation is about Clipanion 3, which is still in development and hasn't been published to the npm registry yet. For Clipanion 2, please check the following document, which shows the decorator syntax you might have seen before.
yarn add clipanion@arcanis/clipanion
yarn workspaces list
)--
(for example yarn dlx eslint --fix
)Clipanion is used in Yarn with great success.
Check the website for our documentation: mael.dev/clipanion.
Commands are declared by extending from the Command
abstract base class, and more specifically by implementing its execute
method which will then be called by Clipanion. Whatever exit code it returns will then be set as the exit code for the process:
class SuccessCommand extends Command {
async execute() {
return 0;
}
}
Commands can also be exposed via one or many arbitrary paths using the paths
static property:
class FooCommand extends Command {
static paths = [[`foo`]];
async execute() {
this.context.stdout.write(`Foo\n`);
}
}
class BarCommand extends Command {
static paths = [[`bar`]];
async execute() {
this.context.stdout.write(`Bar\n`);
}
}
Options are defined as regular class properties, annotated by the helpers provided in the Option
namespace. If you use TypeScript, all property types will then be properly inferred with no extra work required:
class HelloCommand extends Command {
// Positional option
name = Option.String();
async execute() {
this.context.stdout.write(`Hello ${this.name}!\n`);
}
}
Option arguments can be validated and coerced using the Typanion library:
class AddCommand extends Command {
a = Option.String({required: true, validator: t.isNumber()});
b = Option.String({required: true, validator: t.isNumber()});
async execute() {
this.context.stdout.write(`${this.a + this.b}\n`);
}
}
Copyright © 2019 Mael Nison
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
FAQs
Type-safe CLI library / framework with no runtime dependencies
The npm package clipanion receives a total of 1,199,977 weekly downloads. As such, clipanion popularity was classified as popular.
We found that clipanion demonstrated a healthy version release cadence and project activity because the last version was released less than 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
Ransomware costs victims an estimated $30 billion per year and has gotten so out of control that global support for banning payments is gaining momentum.
Application Security
New SEC disclosure rules aim to enforce timely cyber incident reporting, but fear of job loss and inadequate resources lead to significant underreporting.
Security News
The Python Software Foundation has secured a 5-year sponsorship from Fastly that supports PSF's activities and events, most notably the security and reliability of the Python Package Index (PyPI).