Security News
Namecheap Takes Down Polyfill.io Service Following Supply Chain Attack
Polyfill.io has been serving malware for months via its CDN, after the project's open source maintainer sold the service to a company based in China.
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 dependencies
yarn add clipanion
yarn workspaces list
)--
(for example yarn dlx eslint --fix
)Clipanion is used in Yarn with great success.
Note: This syntax assumes you have some way to compile decorators. TypeScript supports them via the experimentalDecorators
setting, and Babel via the @babel/plugin-proposal-decorators
plugin.
In essence you just need to declare a class that extends the Command
abstract class, and implement the execute
method. This function will then be called by Clipanion and its return value will be set as exit code by the engine (by default the exit code will be 0, which means success).
Options and command paths are set using the @Command
decorators, unless you're in an environment that doesn't support them (in which case check the next section to see how to use the fallback syntax). Because you're in a regular class, you can even set default values to your options as you would with any other property!
import {Cli, Command} from 'clipanion';
import * as yup from 'yup';
// greet [-v,--verbose] [--name ARG]
class GreetCommand extends Command {
@Command.Boolean(`-v,--verbose`)
public verbose: boolean = false;
@Command.String(`--name`)
public name?: string;
@Command.Path(`greet`)
async execute() {
if (typeof this.name === `undefined`) {
this.context.stdout.write(`You're not registered.\n`);
} else {
this.context.stdout.write(`Hello, ${this.name}!\n`);
}
}
}
// fibo <a> <b>
class FibonacciCommand extends Command {
@Command.String({required: true})
public a!: number;
@Command.String({required: true})
public b!: number;
@Command.Path(`fibo`)
async execute() {
// ...
}
static schema = yup.object().shape({
a: yup.number().integer(),
b: yup.number().integer(),
})
}
const cli = new Cli({
binaryLabel: `My Utility`,
binaryName: `bin`,
binaryVersion: `1.0.0`,
});
cli.register(GreetCommand);
cli.register(FibonacciCommand);
cli.runExit(process.argv.slice(2), {
...Cli.defaultContext,
});
In case the primary syntax isn't available (for example because you want to avoid any kind of transpilation), a fallback syntax is available:
class GreetCommand extends Command {
async execute() {
// ...
}
}
GreetCommand.addPath(`greet`);
GreetCommand.addOption(`boolean`, Command.Boolean(`-v,--verbose`));
GreetCommand.addOption(`name`, Command.String(`--name`));
Note that in this case the option variables never get assigned default values, so they may be undefined within the execute
block.
The optionNames
parameters all indicate that you should put there a comma-separated list of option names (along with their leading -
). For example, -v,--verbose
is a valid parameter.
@Command.Path(segment1?: string, segment2?: string, ...)
Specifies through which CLI path should trigger the command.
This decorator can only be set on the execute
function itself, as it isn't linked to specific options.
class RunCommand extends Command {
@Command.Path(segment1, segment2, segment3)
async execute() {
// ...
}
}
Generates:
run segment1 segment2 segment3
Note that you can add as many paths as you want to a single command. By default it will be connected on the main entry point (empty path), but if you add even one explicit path this behavior will be disabled. If you still want the command to be available on both a named path and as a default entry point (for example yarn
which is an alias for yarn install
), simply call the decorator without segments:
class YarnCommand extends Command {
@Command.Path(`install`)
@Command.Path()
async execute() {
// ...
}
}
Generates:
yarn install
# or
yarn
@Command.String({required?: boolean})
Specifies that the command accepts a positional argument. By default it will be required, but this can be toggled off.
class RunCommand extends Command {
@Command.String()
public foo?: string;
}
Generates:
run <ARG>
# => foo = ARG
Note that Clipanion supports required positional arguments both at the beginning and the end of the positional argument list (which allows you to build CLI for things like cp
).
class RunCommand extends Command {
@Command.String()
public foo?: string;
@Command.String({required: true})
public bar!: string;
}
Generates:
run value1 value2
# => foo = value1
# => bar = value2
run value
# => foo = undefined
# => bar = value
run
# invalid
@Command.String(optionNames: string, {tolerateBoolean?: boolean})
Specifies that the command accepts an option that takes an argument. Arguments can be specified on the command line using either --foo=ARG
or --foo ARG
.
class RunCommand extends Command {
@Command.String('--foo,-f')
public bar?: string;
}
Generates:
run --foo <ARG>
run --foo=<ARG>
run -f <ARG>
run -f=<ARG>
# => bar = ARG
Be careful, by default, options that accept an argument must receive one on the CLI (ie --foo --bar
wouldn't be valid if --foo
accepts an argument).
This behaviour can be toggled off if the tolerateBoolean
option is set. In this case, the option will act like a boolean flag if it doesn't have a value. Note that with this option on, arguments values can only be specified using the --foo=ARG
syntax.
class RunCommand extends Command {
@Command.String(`--inspect`, {tolerateBoolean: true})
public debug: boolean | string = false;
// ...
}
Generates:
run --inspect
# => debug = true
run --inspect=1234
# debug = "1234"
run --inspect 1234
# invalid
@Command.Boolean(optionNames: string)
Specifies that the command accepts a boolean flag as an option.
class RunCommand extends Command {
@Command.Boolean('--foo')
public bar: boolean;
// ...
}
Generates:
run --foo
# => bar = true
@Command.Array(optionNames: string)
Specifies that the command accepts a set of string arguments.
class RunCommand extends Command {
@Command.Boolean('--arg')
public values: string[];
// ...
}
Generates:
run --arg value1 --arg value2
# => values = [value1, value2]
Clipanion automatically adds support for the -h
option to all the commands that you define. The information printed will come from the usage
property attached to the class. For example, the following command:
class YarnAdd extends Command {
static usage = Command.Usage({
description: `remove dependencies from the project`,
details: `
This command will remove the specified packages from the current workspace. If the \`-A,--all\` option is set, the operation will be applied to all workspaces from the current project.
`,
examples: [[
`Remove a dependency from the current project`,
`$0 remove lodash`,
], [
`Remove a dependency from all workspaces at once`,
`$0 remove lodash --all`,
]],
});
}
Will generate something like this:
Note that the inline code blocks will be automatically highlighted.
Clipanion offers common optional command entries out-of-the-box, under the Command.Entries
namespace.
They have to be manually registered:
cli.register(Command.Entries.Help);
cli.register(Command.Entries.Version);
Paths:
-h
,--help
The Command.Entries.Help
command displays the list of commands available to the application, printing a block similar to the following.
Paths:
-v
,--version
The Command.Entries.Version
command displays the version of the binary provided under binaryVersion
when creating the CLI.
Commands can call each other by making use of their cli
internal property:
class FooCommand extends Command {
@Command.Path(`foo`)
async execute() {
this.context.stdout.write(`Hello World\n`);
}
}
class BarCommand extends Command {
@Command.Path(`bar`)
async execute() {
this.cli.run([`foo`]);
}
}
Commands share what is called a context. Contexts are a set of values defined when calling the run
function from the CLI instance that will be made available to the commands via this.context
. The default context contains properties for stdin
, stdout
, and stderr
, but you can easily define a custom context that extends the default one:
import {BaseContext, Command} from 'clipanion';
type MyContext = BaseContext & {
cwd: string;
};
class PwdCommand extends Command<MyContext> {
async execute() {
this.context.stdout.write(`${this.context.cwd}\n`);
}
}
const cli = Cli.from<MyContext>([
PwdCommands,
]);
cli.runExit(process.argv.slice(2), {
...Cli.defaultContext,
cwd: process.cwd(),
});
Note that the context must be fully defined when calling run
and runExit
on the main CLI instance, but can be omitted or only partially specified when using this.cli.run
(in which case only the specified fields will be changed).
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,314,663 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
Polyfill.io has been serving malware for months via its CDN, after the project's open source maintainer sold the service to a company based in China.
Security News
OpenSSF is warning open source maintainers to stay vigilant against reputation farming on GitHub, where users artificially inflate their status by manipulating interactions on closed issues and PRs.
Security News
A JavaScript library maintainer is under fire after merging a controversial PR to support legacy versions of Node.js.