Skip to content
@staticbolt/args-parser

Options

Options are the named inputs of a command: --list groceries, -n Sam, --verbose. Define them inside a CLI or subcommand definition, or separately with defineOptions when you want to share them.

Naming

The key that you use in code is the option name. It must be a valid JavaScript identifier, and it is converted to a flag for the command line.

Name in code Flag
listName --list-name
ListName --list-name
list_name --list-name
LIST_NAME --list-name
h or H -h

All four case styles map to the same flag, so pick the one that reads best in your code. Single letters become short flags.

aliases add extra names for the same option. They follow the same conversion, so ["n", "list"] gives you -n and --list.

Anatomy of an option

import { coerce, defineSubcommand } from "@staticbolt/args-parser";
import * as z from "zod";


const addItemsCommand = defineSubcommand({
  name: "add-items",


  options: {
    listName: {
      aliases: ["list", "name", "n"],


      // What the value must be. Also decides optional and default.
      schema: z.string(),


      // Turns the raw terminal string into what the schema expects.
      coerce: coerce.string,


      meta: {
        placeholder: "<list>",
        description: "The list to add items to.",
      },
    },


    items: {
      schema: z.string().array(),
      coerce: coerce.stringArray(","),
    },


    tags: {
      schema: z.set(z.enum(["food", "work", "chores"])),
      coerce: coerce.stringSet("|"),
    },
  },
});

schema

The schema decides the type, whether the option is required, and what it falls back to when missing. Nothing in the definition overrides it. See Using schemas.

coerce

Terminal input is always a string. coerce converts it to the type that the schema expects, and TypeScript checks that the two agree. You can leave it out when the schema expects a string.

defineOptions({
  count: { schema: z.number(), coerce: coerce.number },
  verbose: { schema: z.boolean(), coerce: coerce.boolean },
  items: { schema: z.array(z.string()), coerce: coerce.stringArray(",") },
  name: { schema: z.string() }, // no coerce needed
});

The helper that you pick also changes how the flag behaves on the command line. coerce.boolean makes it a flag that takes no value and accepts --no- negation. coerce.object and coerce.json make it accept JSON and dotted keys. Array and set helpers make it repeatable. The full list is in Coerce helpers.

meta

Everything under meta is for humans: help output and generated Markdown. It never changes what the parser accepts.

const meta = {
  // Shown after the flag name, in help and in Markdown.
  placeholder: "<list>",


  // Plain text. Preferred in terminal help when both descriptions exist.
  description: "The list to add items to.",


  // Markdown. Preferred in generated docs, and formatted for the terminal.
  descriptionMarkdown: "The list to add items to. Create one with **create-list**.",


  // Shown under the description in help, inside a code block in Markdown.
  example: "listy add-items --list groceries --items egg,milk",


  // Display only. Says "default: ..." in help without changing the real default.
  default: `"default-list"`,


  // Display only. Marks the option optional or required in help.
  optional: false,


  // Leaves the option out of help and docs. Useful for internal flags.
  hidden: false,
};

Field by field in the Option reference.

Constraints

exclusive, requires, and conflictWith control which options can appear together. See Constraints.