{"id":17532,"library":"cli-nano","title":"Tiny CLI Argument Parser","description":"cli-nano is a lightweight library for building command-line interfaces (CLIs) in Node.js, offering functionality similar to `yargs` or Node.js's built-in `parseArgs()`. It supports parsing positional arguments, flags, and options with robust configuration capabilities. The current stable version is 1.2.2, with releases occurring fairly frequently, often including minor bug fixes and features, sometimes with breaking changes within minor versions as seen with v1.2.0 and v1.0.0. Its key differentiators include a minimal footprint, zero external dependencies, and extensive configurability for defining argument types, aliases, defaults, and generating help output, making it a powerful alternative to heavier CLI libraries while providing more features than the native `parseArgs()` method. It is designed for Node.js environments and ships with TypeScript types for enhanced developer experience.","status":"active","version":"1.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/ghiscoding/cli-nano","tags":["javascript","typescript"],"install":[{"cmd":"npm install cli-nano","lang":"bash","label":"npm"},{"cmd":"yarn add cli-nano","lang":"bash","label":"yarn"},{"cmd":"pnpm add cli-nano","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"cli-nano is primarily designed for ESM usage, though CommonJS `require` might work with transpilers, direct usage is ESM-first.","wrong":"const { parseArgs } = require('cli-nano');","symbol":"parseArgs","correct":"import { parseArgs } from 'cli-nano';"},{"note":"Always use `import type` for importing types to ensure they are stripped from the JavaScript output, preventing potential runtime issues and optimizing bundle size.","wrong":"import { Config } from 'cli-nano';","symbol":"Config","correct":"import { type Config } from 'cli-nano';"},{"note":"The main parsing function `parseArgs` is a named export, not a default export.","wrong":"import parseArgs from 'cli-nano';\nparseArgs({ command: {...}, options: {...} });","symbol":"parseArgs","correct":"import { parseArgs } from 'cli-nano';\nparseArgs({ command: {...}, options: {...} });"}],"quickstart":{"code":"import { parseArgs } from 'cli-nano';\n\nconst main = async () => {\n  const config = {\n    command: {\n      name: 'serve',\n      describe: 'Start a server with the given options',\n      examples: [\n        { cmd: '$0 ./www/index.html 8080 --open', describe: 'Start web server on port 8080' }\n      ],\n      positionals: [\n        { name: 'input', describe: 'serving files or directory', type: 'string', variadic: true, required: true },\n        { name: 'port', type: 'number', describe: 'port to bind on', required: false, default: 5000 }\n      ]\n    },\n    options: {\n      dryRun: { alias: 'd', type: 'boolean', describe: 'Show what would be executed', default: false },\n      verbose: { alias: 'V', type: 'boolean', describe: 'print more information to console' },\n      open: { alias: 'o', type: 'boolean', describe: 'open browser when starting server', default: true },\n      address: { type: 'string', describe: 'Address to use', required: true, default: '127.0.0.1' }\n    },\n    version: '1.2.2',\n    helpFlagCasing: 'camel'\n  };\n\n  try {\n    const args = parseArgs(config);\n    if (args) {\n      console.log('Parsed Arguments:', args);\n      console.log(`Serving '${args.input.join(', ')}' on ${args.address}:${args.port}`);\n      if (args.dryRun) {\n        console.log('This is a dry run. Server would not actually start.');\n      } else if (args.open) {\n        console.log('Opening browser...');\n      }\n    }\n  } catch (error) {\n    console.error('CLI Error:', (error as Error).message);\n  }\n};\n\nmain();","lang":"typescript","description":"This quickstart demonstrates how to define a CLI command with positional arguments, various options (booleans, numbers, strings, arrays), aliases, default values, and a version/help display. It then parses `process.argv` and logs the results, showcasing basic argument access and conditional logic based on flags."},"warnings":[{"fix":"Update `command.positionals` from `[{ name: 'arg', ... }]` to `{ arg: { ... } }`.","message":"The `positionals` configuration property changed from an array of positional argument definitions to an object where keys are the positional argument names. This requires updating how positional arguments are defined in your CLI configuration.","severity":"breaking","affected_versions":">=1.2.0"},{"fix":"Change `command.description` to `command.describe` in your CLI configuration.","message":"The `description` property within the command configuration was renamed to `describe` to align with `Yargs`'s terminology and conventions. Using the old `description` property will no longer have an effect.","severity":"breaking","affected_versions":">=1.2.0"},{"fix":"Rename the `positional` property in your command configuration to `positionals`.","message":"The property for defining positional arguments was changed from `positional` (singular) to `positionals` (plural). If you were using the singular form, your configuration will no longer be correctly interpreted.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always access parsed options using their camelCase equivalent (e.g., `args.myFlag`). If you need kebab-case for help display, set `helpFlagCasing: 'kebab'` in your config, but this does not change the parsed argument key.","message":"cli-nano defaults to camelCase for converting kebab-case flags (e.g., `--my-flag` becomes `myFlag`). While it accepts both, ensure your code accesses options using the camelCase variant unless `helpFlagCasing` is explicitly set to `kebab`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure all `required: true` arguments and options are supplied when running the CLI. For example, if 'input' is required, run `your-cli-command 'some-value'`.","cause":"A required positional argument or option was not provided on the command line.","error":"Error: Missing required argument: input"},{"fix":"Provide values that match the expected type for each option. For a number type, ensure a valid numeric string is passed (e.g., `--port 8080`, not `--port abc`).","cause":"An option was provided with a value that does not match its defined `type` (e.g., passing a string where a number is expected).","error":"Error: Expected option 'port' to be of type 'number', but received 'abc'"},{"fix":"Check for typos in the flag name or define the option in your `parseArgs` configuration. If it's an intended flag, add it to `config.options` with its type and description.","cause":"The CLI was invoked with an option or flag that was not defined in the `config.options` object.","error":"Error: Unknown option: --unknown-flag"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}