ordana

A declarative CLI argument parser with automatic help message and document generation.

• Declarative configuration
• Type safe parse results
• Automatic help message generation
• Automatic document generation
• Minimal package size: ~13kB for JS, ~6kB for types(without minify / gzip)
  • Note: to support older Node.js versions, you need @pkgjs/parseargs@^0.9.1 too, which is ~60kB

Install

npm i ordana
# yarn add ordana
# pnpm add ordana

Usage

parse

import { parse } from 'ordana'
import type { TopLevelOptions } from 'ordana'

const options = {
  subcommands: {
    dev: {
      description: 'my subcommand',
      arguments: {
        foo: { type: 'string|boolean', description: 'arg' },
        bar: { type: 'string', multiple: true },
        baz: {
          type: {
            type: 'string',
            parse: v => +v,
            docsType: 'number'
          }
        }
      },
      positionals: {}
    }
  }
} satisfies TopLevelOptions

const input = ['dev', '--foo', '--bar', 'a', '--bar', 'b', '--baz', '1', 'pos'] // process.argv.slice(2)
const result = parse(input, options)
console.log(result)
/*
{
  type: 'normal',
  subcommand: 'dev',
  values: {
    foo: true,
    bar: ['a', 'b'],
    baz: 1
  },
  positionals: ['pos']
}
*/

help message

const input2 = ['dev', '--help']
const result2 = parse(input2, options) // options is the same as above
if (result2.type === 'help') {
  const helpMessage = generateHelpMessage(options, result2.targetSubcommand)
  console.log(helpMessage)
  /*
    foo dev - my subcommand

    Usage
      $ foo dev

    Options
      --foo [foo]  [string | boolean]  arg
      --bar <bar>  [string]
      --baz <baz>  [number]
  */
}

document generation

import { generateDocs } from 'ordana-gen-docs' // `ordana-gen-docs` needs to be installed separately
const docs = generateDocs(options)
console.log(docs)

Output

foo dev

my subcommand

Usage

foo dev

Options

Options	Type	Description
--foo [foo]	string | boolean	arg
--bar <bar>	string
--baz <baz>	number

Credits

• The help message output is based on cac
• The option interface is based on Node's util.parseArgs API