๐ป A type-driven command line argument parser
MIT License
cmd-ts
๐ป A type-driven command line argument parser, with awesome error reporting ๐คค
Not all command line arguments are strings, but for some reason, our CLI parsers force us to use strings everywhere. ๐ค cmd-ts
is a fully-fledged command line argument parser, influenced by Rust's clap
and structopt
:
๐คฉ Awesome autocomplete, awesome safeness
๐ญ Decode your own custom types from strings with logic and context-aware error handling
๐ฒ Nested subcommands, composable API
import { command, run, string, number, positional, option } from 'cmd-ts';
const cmd = command({
name: 'my-command',
description: 'print something to the screen',
version: '1.0.0',
args: {
number: positional({ type: number, displayName: 'num' }),
message: option({
long: 'greeting',
type: string,
}),
},
handler: (args) => {
args.message; // string
args.number; // number
console.log(args);
},
});
run(cmd, process.argv.slice(2));
command(arguments)
Creates a CLI command.
Not all command line arguments are strings. You sometimes want integers, UUIDs, file paths, directories, globs...
Note: this section describes the
ReadStream
type, implemented in./src/example/test-types.ts
Let's say we're about to write a cat
clone. We want to accept a file to read into stdout. A simple example would be something like:
// my-app.ts
import { command, run, positional, string } from 'cmd-ts';
const app = command({
/// name: ...,
args: {
file: positional({ type: string, displayName: 'file' }),
},
handler: ({ file }) => {
// read the file to the screen
fs.createReadStream(file).pipe(stdout);
},
});
// parse arguments
run(app, process.argv.slice(2));
That works okay. But we can do better. In which ways?
What if we had a way to get a Stream
out of the parser, instead of a plain string? This is where cmd-ts
gets its power from, custom type decoding:
// ReadStream.ts
import { Type } from 'cmd-ts';
import fs from 'fs';
// Type<string, Stream> reads as "A type from `string` to `Stream`"
const ReadStream: Type<string, Stream> = {
async from(str) {
if (!fs.existsSync(str)) {
// Here is our error handling!
throw new Error('File not found');
}
return fs.createReadStream(str);
},
};
Now we can use (and share) this type and always get a Stream
, instead of carrying the implementation detail around:
// my-app.ts
import { command, run, positional } from 'cmd-ts';
const app = command({
// name: ...,
args: {
stream: positional({ type: ReadStream, displayName: 'file' }),
},
handler: ({ stream }) => stream.pipe(process.stdout),
});
// parse arguments
run(app, process.argv.slice(2));
Encapsulating runtime behaviour and safe type conversions can help us with awesome user experience:
-
, and when it happens, return process.stdin
like many Unix applicationsAnd the best thing about it โ everything is encapsulated to an easily tested type definition, which can be easily shared and reused. Take a look at io-ts-types, for instance, which has types like DateFromISOString, NumberFromString and more, which is something we can totally do.
This project was previously called clio-ts
, because it was based on io-ts
. This is no longer the case, because I want to reduce the dependency count and mental overhead. I might have a function to migrate types between the two.