hulla.dev

Concepts

Parser options

Control which argv entries are read and how names, aliases, and command arguments are matched.

On this page

Parser settings control how .parse() reads the array you pass. Start with the defaults, then change the options your command needs.

By default, startIndex is 0 and stopIndex is unset, so parse() reads the complete array. If you pass Node’s or Bun’s full process.argv, skip its executable and script path with startIndex: 2:

TypeScript
import { parser, positional } from '@hulla/args'

const cli = parser({
  name: 'greet',
  arguments: [positional({ name: 'name' })],
  settings: { startIndex: 2 },
})

const result = cli.parse(process.argv)

This is equivalent to passing process.argv.slice(2) to a parser with default settings. Prefer one approach, so the runtime prefix is removed exactly once. stopIndex can bound the end of the slice.

Case-insensitive matching also affects equals-form values

With the default caseSensitive: false, --name=Sam supplies the lowercased value sam. Positionals and space-separated values retain their spelling, and raw preserves the original token. Set caseSensitive: true when that distinction matters.

These are the supported settings and defaults:

SettingDefaultEffect
caseSensitivefalseMatch names without regard to case.
mode'both'Accept long and short forms; 'long' or 'short' restricts the form.
requireEqualsfalseRequire options to use --name=value when enabled.
keepOnlyDetectedfalseOmit declared argument and command entries that were not detected.
mergeArgsfalseLet root and selected command parsers inspect shared arguments.
sharedDashfalseExpand combined short forms such as -abc.

For example, a parser that accepts only long option forms can declare:

TypeScript
import { option, parser } from '@hulla/args'

const cli = parser({
  name: 'report',
  arguments: [option({ name: 'output' })],
  settings: { mode: 'long', requireEquals: true },
})

Then a value option is written as --output=report.txt; a short form such as -o is not accepted. Combined short forms require every short name to be one character; see arguments.

Settings apply to the parser and its nested commands. Keep the defaults until a concrete runtime or CLI convention calls for a change; see quick start for the recommended argv boundary and casing choice.