TypeScript icon, indicating that this package has built-in type declarations

0.1.0 • Public • Published

🎛️ @benev/argv

command line argument parser

🤖 for making node cli programs
💁 autogenerated --help page
🕵️‍♂️ designed for good typescript typings
🧼 zero dependencies
💖 made free and open source, just for you

example generated help page

$ icecream waffle-cone --flavor="cookie-dough" --scoops="5" +help

example help output


  1. install @benev/argv via npm
    npm install @benev/argv
  2. import the cli function
    import {cli} from "@benev/argv"
  3. formalize types for your arguments and parameters
    export type Args = {
      vessel: string
    export type Params = {
      flavor: string
      scoops: number
      help: boolean
  4. specify your cli, and perform the parsing
    const {args, params} = cli<Args, Params>()({
      program: "icecream",
      argv: process.argv,
      columns: process.stdout.columns ?? 72,
      // positional arguments your program will accept
      argorder: ["vessel"],
      // arguments your program will accept
      args: {
        vessel: {
          type: String,
          mode: "requirement",
          help: 'can be "cone", "bowl", or "waffle-cone"',
      // parameters your program will accept
      params: {
        flavor: {
          type: String,
          mode: "default",
          default: "vanilla",
          help: "your favorite icecream flavor",
        scoops: {
          type: Number,
          mode: "requirement",
          help: "number of icecream scoops",
        help: {
          type: Boolean,
          mode: "option",
          help: "trigger the help page",
  5. now you can access your args and params
    // example command:
    //  $ icecream waffle-cone --flavor cookie-dough --scoops 5
      // "waffle-cone"
      // "cookie-dough"
      // 5


  • typings work best if you declare Args and Params types, but it can infer some of it if you omit them.
  • these are equivalent ways to pass a param:
    • --param true
    • --param "true"
    • --param=true
    • --param="true"
    • +param (sets to boolean true)
  • boolean parsing regards these as true (case-insensitive):
    • "true"
    • "yes"
    • "y"
    • "on"
    • "ok"
    • "enabled"
  • --help has magic handling: it's the only "void" parameter which doesn't expect to be followed by a value
    • eg, icecream --help is good
    • eg, icecream --help true is bad
    • understand that --help is the ONLY parameter treated this way
    • all other parameters require a value
    • parameter syntax is strict like this so that it's consistent and unambiguous
    • however people will panic if --help doesn't give the expected result, thus the magic handling here
    • use +param as a shorthand for enabling a boolean
    • +help also works
  • you can disable the ansi colors by passing theme: notheme after import {notheme} from "@benev/argv"
  • you can disable the "tips" section by passing tips: false
  • you can also pass
    • columns current terminal width, used for text-wrapping
    • help description and usage instructions for your program
    • readme url to your program's readme


DownloadsWeekly Downloads






Unpacked Size

106 kB

Total Files


Last publish


  • chasemoskal