@benev/argv

🎛️ @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

instructions

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
   
   args.vessel
     // "waffle-cone"
   
   params["--flavor"]
     // "cookie-dough"
   
   params["--scoops"]
     // 5
   

notes

• argv uses exact names, like --param, so the typescript typings work.
• 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

Changelog

v0.0.0

• initial release