cli-nano

cli-nano

Simple 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 again more configurable so that we really get what we would expect from a more complete CLI builder.

Features

• Parses arguments
• Supports defining Positional arguments
  • Supports Variadic args (1 or more positional args)
• Automatically converts flags to camelCase to match config options
  • accepts both --camelCase and --kebab-case
• Negates flags when using the --no- prefix
• Outputs version, when defined, by using --version
• Outputs description and supplied help text by using --help
• Supports defining required options
• Supports default values
• No dependencies!

Install

npm install cli-nano

Usage

#!/usr/bin/env node

import { type Config, parseArgs } from 'cli-nano';

const config: Config = {
  command: {
    name: 'serve',
    description: 'Start a server with the given options',
    positionals: [
      {
        name: 'input',
        description: 'serving files or directory',
        type: 'string',
        variadic: true, // 1 or more
        required: true,
      },
      {
        name: 'port',
        type: 'number',
        description: 'port to bind on',
        required: false,
        default: 5000, // optional default value
      },      
    ],
  },
  options: {
    dryRun: {
      alias: 'd',
      type: 'boolean',
      description: 'Show what would be done, but do not actually start the server',
      default: false, // optional default value
    },
    exclude: {
      alias: 'e',
      type: 'array',
      description: 'pattern or glob to exclude (may be passed multiple times)',
    },
    rainbow: {
      type: 'boolean',
      alias: 'r',
      description: 'Enable rainbow mode',
      default: true,
    },
    verbose: {
      alias: 'V',
      type: 'boolean',
      description: 'print more information to console',
    },
    up: {
      type: 'number',
      description: 'slice a path off the bottom of the paths',
      default: 1,
    },
    display: {
      alias: 'D',
      required: true,
      description: 'a required display option',
    }
  },
  version: '0.1.6',
};

const args = parseArgs(config);
console.log(args);

// do something with parse arguments, for example
// startServer(args);

Example CLI Calls

# Show help guide (created by reading CLI config)
serve --help

# Show version (when defined)
serve --version

# Uses default port 5000
serve dist/index.html

# With required and optional positionals
serve index1.html index2.html 8080 -D value

# With boolean and array options
serve index.html 7000 --dryRun --exclude pattern1 --exclude pattern2 -D value

# With negated boolean
serve index.html 7000 --no-dryRun -D value

# With short aliases
serve index.html 7000 -d -e pattern1 -e pattern2 -D value

# With 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 if 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).

See examples/ for more usage patterns.

Used by

cli-nano is currently used in these other projects of mine (feel free to edit this list):

• native-copyfiles
• remove-glob

Changelog

1.0.2 (2025-07-02)

Bug Fixes

• better align options list when displaying help (ea14137)