Class Cli

constructor

• new Cli(opts?: CliOptions): Cli

  Create an instance with the supplied configuration; omitted fields use the documented defaults.

  Parameters

  • opts: CliOptions = {}

  Returns Cli

Readonlycwd

Readonlyname

Readonlyroot

values

commandPath

• get commandPath(): string[]

  The command words selected by the last parse, e.g. ['db', 'migrate'].

  Returns string[]

arg

• arg(
      name: string,
      description: string,
      defaultValue?: string,
      validation?: Validation,
  ): this

  Register a positional argument. An empty default makes it required.

  Parameters

  • name: string
  • description: string
  • defaultValue: string = ''
  • validation: Validation = ''

  Returns this

argVariadic

• argVariadic(name: string, description: string, validation?: Validation): this

  Register a final positional argument that collects all remaining tokens.

  Parameters

  • name: string
  • description: string
  • validation: Validation = ''

  Returns this

command

• command(name: string, description: string): Cli

  Register a command (spec section 1.7) and return it, to register its options and arguments on.

  Parameters

  • name: string
  • description: string

  Returns Cli

completionData

• completionData(words?: string[]): string

  Tab-separated completion records (spec section 9). words are the words typed after the program name; a program with commands follows them.

  Parameters

  • words: string[] = []

  Returns string

completionScript

• completionScript(shell: string): string | undefined

  Shell script that enables completion for this program (spec section 9): eval "$(prog --completion bash)". Undefined for an unknown shell.

  Parameters

  • shell: string

  Returns string | undefined

exclusive

• exclusive(...longs: string[]): this

  At most one of these options may be given.

  Parameters

  • ...longs: string[]

  Returns this

get

• get(name: string): Value

  Look up a resolved value by option variable name or positional argument name.

  Parameters

  • name: string

  Returns Value

getArg

• getArg(
      ...args: [
          name: string,
          description: string,
          defaultValue: string,
          validation: Validation,
      ],
  ): this

  Register a positional argument using the legacy method name.

  Parameters

  • ...args: [
        name: string,
        description: string,
        defaultValue: string,
        validation: Validation,
    ]

  Returns this

  Deprecated

  Use Cli.arg.

getArgVariadic

• getArgVariadic(
      ...args: [name: string, description: string, validation: Validation],
  ): this

  Register a variadic argument using the legacy method name.

  Parameters

  • ...args: [name: string, description: string, validation: Validation]

  Returns this

  Deprecated

  Use Cli.argVariadic.

getOpt

• getOpt(
      ...args: [
          varName: string,
          long: string,
          short: string,
          defaultValue: string,
          description: string,
          group: string,
          validation: Validation,
      ],
  ): this

  Register an option using the legacy method name.

  Parameters

  • ...args: [
        varName: string,
        long: string,
        short: string,
        defaultValue: string,
        description: string,
        group: string,
        validation: Validation,
    ]

  Returns this

  Deprecated

  Use Cli.opt; kept for scripts written against getOpt.

getOptArray

• getOptArray(
      ...args: [
          varName: string,
          long: string,
          short: string,
          description: string,
          group: string,
          validation: Validation,
      ],
  ): this

  Register a repeatable option using the legacy method name.

  Parameters

  • ...args: [
        varName: string,
        long: string,
        short: string,
        description: string,
        group: string,
        validation: Validation,
    ]

  Returns this

  Deprecated

  Use Cli.optArray.

isExplicitlySet

• isExplicitlySet(long: string): boolean

  Whether an option came from CLI, config, or environment rather than a default.

  Parameters

  • long: string

  Returns boolean

isSet

• isSet(long: string): boolean

  Whether an option was explicitly supplied on the command line.

  Parameters

  • long: string

  Returns boolean

jsonSchema

• jsonSchema(): string

  JSON description of the CLI (spec section 8).

  Returns string

oneOf

• oneOf(...longs: string[]): this

  At least one of these options must be given.

  Parameters

  • ...longs: string[]

  Returns this

opt

• opt(
      varName: string,
      long: string,
      short: string,
      defaultValue: string,
      description: string,
      group?: string,
      validation?: Validation,
  ): this

  Register an option. defaultValue is a default, 'flag' for a boolean flag, 'optional' for no default, or '' to make the option required.

  Parameters

  • varName: string
  • long: string
  • short: string
  • defaultValue: string
  • description: string
  • group: string = 'Options'
  • validation: Validation = ''

  Returns this

optArray

• optArray(
      varName: string,
      long: string,
      short: string,
      description: string,
      group?: string,
      validation?: Validation,
  ): this

  Register a repeatable option whose values accumulate into a list.

  Parameters

  • varName: string
  • long: string
  • short: string
  • description: string
  • group: string = 'Options'
  • validation: Validation = ''

  Returns this

parse

• parse(argv?: string[]): ParseResult

  Parse without exiting. Values are available in values when status is 'ok'.

  Parameters

  • argv: string[] = ...

  Returns ParseResult

requireCommand

• requireCommand(command: string, description: string, installHint?: string): this

  Declare an external executable required at parse time; description and install hint explain a missing dependency.

  Parameters

  • command: string
  • description: string
  • installHint: string = ''

  Returns this

requires

• requires(long: string, ...longs: string[]): this

  When the first option is given, the others must be too.

  Parameters

  • long: string
  • ...longs: string[]

  Returns this

run

• run(argv?: string[]): Record<string, Value>

  Parse and act like a CLI: handles --help, --help-json-schema and --bash-completion, prints errors and exits on failure. Returns the values.

  Parameters

  • argv: string[] = ...

  Returns Record<string, Value>

setConfig

• setConfig(option: string, prefixes: string): this

  option holds the config file path; prefixes is comma-separated.

  Parameters

  • option: string
  • prefixes: string

  Returns this

setDescription

• setDescription(text: string): this

  Set the description shown below the usage line; returns this CLI.

  Parameters

  • text: string

  Returns this

setEffects

• setEffects(...effects: Effect[]): this

  What running the program does: read-only, idempotent, destructive, network.

  Parameters

  • ...effects: Effect[]

  Returns this

setEpilog

• setEpilog(text: string): this

  Set the text displayed after the help sections; returns this CLI.

  Parameters

  • text: string

  Returns this

setPathSearch

• setPathSearch(long: string, dirs: string | string[]): this

  Fallback dirs (relative to root) for bare relative values of a path option.

  Parameters

  • long: string
  • dirs: string | string[]

  Returns this

setStdin

• setStdin(description: string, contentType?: string): this

  What the program reads on stdin; contentType is a MIME type or a comma-separated list.

  Parameters

  • description: string
  • contentType: string = ''

  Returns this

setStdout

• setStdout(description: string, contentType?: string): this

  What the program writes on stdout; undeclared means text.

  Parameters

  • description: string
  • contentType: string = ''

  Returns this

source

• source(long: string): Source

  Where an option's value came from: cli, config, env, default or unset.

  Parameters

  • long: string

  Returns Source

usage

• usage(): string

  Help text (spec section 7), for the selected command.

  Returns string

valuesJson

• valuesJson(): string

  Resolved values as JSON (spec section 10).

  Returns string