Small command-line tool similar to `yargs` or `parseArgs` from Node.js to create a CLI accepting positional arguments, flags and options.
npm install cli-nano






Small library to create command-line tool (aka CLI) which is quite similar to Yargs, it is as configurable as Yargs but is a fraction of its size. The library is also inspired by NodeJS parseArgs() but is a lot more configurable in order to get what we would expect from a more complete CLI builder tool.
--camelCase and --kebab-case--no- prefix--version--helprequired optionsdefault valuesgroup for grouping command options in helpsh
npm install cli-nano
`$3
`ts
#!/usr/bin/env nodeimport { type Config, parseArgs } from 'cli-nano';
const config: Config = {
command: {
name: 'serve',
describe: 'Start a server with the given options',
examples: [
{ cmd: '$0 ./www/index.html 8080 --open', describe: 'Start web server on port 8080 and open browser' },
{
cmd: '$0 ./index.html 8081 --no-open --verbose',
describe: 'Start web server on port 8081 without opening browser and print more debugging logging to the console',
},
],
positionals: [
{
name: 'input',
describe: 'serving files or directory',
type: 'string',
variadic: true, // 1 or more
required: true,
},
{
name: 'port',
type: 'number',
describe: 'port to bind on',
required: false,
default: 5000, // optional default value
},
],
},
options: {
dryRun: {
alias: 'd',
type: 'boolean',
describe: 'Show what would be executed but without starting the server',
default: false, // optional default value
},
display: {
group: 'Advanced Options',
alias: 'D',
required: true,
type: 'boolean',
describe: 'a required display option',
},
exclude: {
alias: 'e',
type: 'array',
describe: 'pattern or glob to exclude (may be passed multiple times)',
},
verbose: {
alias: 'V',
type: 'boolean',
describe: 'print more information to console',
},
open: {
alias: 'o',
type: 'boolean',
describe: 'open browser when starting server',
default: true,
},
cache: {
type: 'number',
describe: 'Set cache time (in seconds) for cache-control max-age header',
default: 3600,
},
address: {
type: 'string',
describe: 'Address to use',
required: true,
},
rainbow: {
group: 'Advanced Options',
type: 'boolean',
alias: 'r',
describe: 'Enable rainbow mode',
default: true,
},
},
version: '0.1.6',
helpFlagCasing: 'camel', // show help flag option in which casing (camel/kebab) (defaults to 'kebab')
helpDescMinLength: 40, // min description length shown in help (defaults to 50)
helpDescMaxLength: 120, // max description length shown in help (defaults to 100), will show ellipsis (...) when greater
helpUsageSeparator: ':', // defaults to "→"
};
const args = parseArgs(config);
console.log(args);
// do something with parsed arguments, for example
// const { input, port, open } = args;
// startServer({ input, port, open });
`$3
For full TypeScript auto-inference and intelliSense of parsed arguments, define your config as a
const and cast it as const:`ts
const config = {
... // your config object as shown above
} as const;const args = parseArgs(config);
// TypeScript will infer the correct types:
args.input; // [string, ...string[]] (required, variadic)
args.port; // number (optional, has default)
args.verbose; // boolean (optional)
args.display; // boolean (required)
`> Tip:
> Using
as const preserves literal types and tuple information, so TypeScript can infer required/optional fields and argument types automatically.
> If you use const config: Config = { ... }, you get type checking but not full intelliSense for parsed arguments.> [!NOTE]
> For required+variadic positionals, the type is
[string, ...string[]] (at least one value required). For optional variadic, it's string[]. For non-variadic, it's string.#### Example CLI Calls
`sh
Show help guide (created by reading CLI config)
serve --helpShow version (when defined)
serve --versionUses default port 5000
serve dist/index.htmlWith required and optional positionals
serve index1.html index2.html 8080 -D valueWith boolean and array options entered as camelCase (kebab-case works too)
serve index.html 7000 --dryRun --exclude pattern1 --exclude pattern2 -D valueWith negated boolean entered as kebab-case
serve index.html 7000 --no-dryRun -D valueWith short aliases (case sensitive)
serve index.html 7000 -d -e pattern1 -e pattern2 -D valueWith number option
serve index.html 7000 --up 2 -D value
`#### Notes
- Default values: Use the
default property in an option or positional argument to specify a value when the user does not provide one.
- Example for option: { type: 'boolean', default: false }
- Example for positional: { name: 'port', type: 'number', default: 5000 }
- Variadic positionals: Use variadic: true for arguments that accept multiple values.
- Required options: Add required: true to enforce presence of an option.
- Negated booleans: Use --no-flag to set a boolean option to false.
- Array options: Repeat the flag to collect multiple values (e.g., --exclude a --exclude b).
- Aliases: Use alias for short flags (e.g., -d for --dryRun).
- Groups: Use group for grouping some commands in help (e.g., { group: 'Extra Commands' }).See examples/ for more usage patterns.
Used by
cli-nano is currently being used by the following projects, which is actually why I created this CLI tool, that I currently maintain as well (feel free to edit this list):- native-copyfiles
- remove-glob
Help Example
You can see below an example of a CLI help (which is the result of calling
--help with the config shown above). Please note that the following means:
-