Skip to main content

Guide

When to use​

This package can tokenize and format standard POSIX-style command line syntax. For example, the input get weather --days 1 will be parsed into something resembling the following structure:

{
  "command": "get",
  "args": ["weather"],
  "flags": [
    {
      "name": "days",
      "value": 1
    }
  ]
}

Placeholders​

We use placeholders to show the user what they need to type next. There are two types of placeholders - matching placeholders, which indicate that the suggestion indicated by the placeholder can be typed verbatim, and For example, when a user first opens a prompt, they may see something like this:

> get <command> [flags]

The first placeholder, get indicates that this word can be typed verbatim. <command> is a placeholder which indicates that a subcommand is required as the next argument. Then, the second placeholder, [flags], indicates that there are flags available as optional arguments.

It's important to note that positional arguments must come before flags in order to show the correct placeholders. This is because typically a command can accept many different combinations of flags, but only a finite number of positional arguments. If flags were allowed to come first, we wouldn't know where to show the placeholders for positional arguments.

Multi-level commands​