Komando
Type safe CLI devtool for Deno and Node
Features
- Minimal API, enhance as you progress
- Unlimited (nested) sub-commands
- Responsive help message with terminal width
- Fully Typed API
Jump to
bat
example.
Installation
For Deno:
// @deno-types="https://deno.land/x/komando/mod.d.ts"
import { komando } from 'https://deno.land/x/komando/mod.js';
For Node:
pnpm add komando -D
Usage
The main entry of this module is komando
function. komando
function creates
the CLI app and parse Deno.args
for Deno or process.argv.slice(2)
for Node
and run them. Komando will generate the help message by default with respect to
the terminal width.
komando({
name: 'main',
version: '1.0.0', // will add `-V, --version` flag if `version` exist.
// ... the rest of options
});
Sub-commands
Sub-commands can be created with defineCommand
helper function. It provides
type inference and set the default values if there isn’t. And put the command in
the commands
property of komando
function. Sub-sub-commands can be put in
the commands
property of the parent sub-commands.
const devCommand = defineCommand({
name: 'dev',
commands: [
// ...sub sub commands if needed
],
});
komando({
commands: [
devCommand,
],
});
Flags
Flags (aka Options) are simple JavaScript objects and they can be created in the
flags
property of command options.
komando({
// ...
flags: {
host: {
typeFn: String, // require for type inference, can be Number, Boolean, or [Number] for an array of output any other function that takes one argument and return one value,
// ...
},
},
});
NOTE: flags
are local by default. If you need a global flags, create a
global shared object and reused it where needed.
const globalOptions = {
config: { typeFn: String },
debug: { typeFn: Boolean },
};
const devCommand = defineCommand({
flags: {
host: { typeFn: String },
port: { typeFn: Number },
...globalOptions,
},
});
komando({
flags: {
...globalOptions,
},
});
Arguments
Arguments are also simple objects and can be created in args
property of
command options. Arguments after --
are collected in the --
property of
args
.
komando({
args: {
root: {
nargs: '?', // can be one of '1' | '?' | '*' | '+'
description: 'Root directory',
},
},
run(args) {
console.log(args); // { '--': [], root: undefined }
},
});
Run function
Each command has an optional run
function to run when the command is
encountered in the argv
.
komando({
// ....
flags: {
config: { typeFn: String },
debug: { typeFn: Number },
},
run(args, flags) {
// do something, run your code with fully typed `args`, `flags`
flags.config; // string | undefined
flags.debug; // boolean | undefined
args['--']; // string[]
},
});
Misc
-
Commands or flags can be grouped under custom title in the help message. This is done by
groupBy
function. It takes a title and an array of commands or a flags object to group.
Acknowledgement
Komando is inspired by the below prior type safe tools:
As first, Komando is intended for Deno only. But there is no Deno only specific features that Komando depends on, so npm package is also published.
Contribution
Install Deno.
Setup git hooks
git config core.hookspath .githooks