Overview

Getting Started
 Fig for Teams

Docs›CLI skeleton

CLI Skeleton

Completion specs are defined in a declarative schema that specifies subcommands, options and arguments.

Broadly speaking, every CLI tool can be expressed as a tree-like structure with a root command that potentially has its own subcommands, options and arguments.

For instance, git has many subcommands, like commit, checkout and push, which in turn have options and arguments of their own.

The primary purpose of a completion spec is to map out this structure or 'skeleton' for a given CLI tool.

cli_structure

It is very important that the mapping between a CLI tool and the completion spec is accurate. An inaccurate mapping (e.g. forgetting to signal that an option takes an argument) will cause Fig to render the wrong suggestions.

Mapping from skeleton to spec

The skeleton of the CLI is mapped out using the following objects and fields.

Subcommand

These properties on Subcommand define how it is interpreted by the parser.

  • name

    This is a mandatory field and must precisely match the text value of the subcommand.

  • subcommands

    Any nested subcommands that are associated with current command must be defined.

  • options

    Any options that are associated with the current command must be defined.

  • args

    If the subcommand takes an argument, the args field must have a value besides null or an [], otherwise Fig will present incorrect suggestions.

    If the subcommand takes multiple arguments, each should have a corresponding entry in the args array.

See "Subcommand" for a full description of all properties.

Option

These properties on Option define how it is interpreted by the parser.

  • name

    This is a mandatory field and must precisely match the text value of the option.

    Note: Do not include any additional text in the name field. Even if an option accepts a value passed in using an equals sign — for instance, --port=1234 — the name field should not include the =.

  • args

    If the option takes an argument, the args field must have a value besides null or an [], otherwise Fig will present incorrect suggestions.

    If the option takes multiple arguments, each should have a corresponding entry in the args array.

See "Option" for a full description of all properties.

Argument

These properties on Argument define how it is interpreted by the parser.

  • variadic

    If an argument is variadic, Fig will expect one or more values.

  • isOptional

    If an argument is optional, Fig will expect zero or one value(s).

Note: The name property of an Argument object is not used in parsing. However, it provides additional contextual information while the user types, and still should be defined.

See "Argument" for a full description of all properties.

All other properties besides those defined above are used for rendering or generating suggestions, rather than parsing the command.

Bringing it all together

Here is a simplified, 'skeletal' completion spec for git that only includes the commit subcommand and the -m flag:

const completionSpec: Fig.Spec = {
  name: "git",
  subcommands: [
    {
      name: "commit",
      options: [
        {
          name: ["-m", "--message"],
          args: [
            {
              name: "message"
            }
          ]
        }
      ]
    }
  ]
}

Note: A more fleshed out spec might add descriptions, customize icons or provide dynamic suggestions. However, these additions are not essential for the command line to be parsed correctly.

A few things warrant special attention.

  • The Option's name property takes an array of string, so that both the short flag and the long flag can be defined simultaneously.

    (This functionality also works on the Subcommand object, so if a subcommand has multiple aliases, these can be declared in the same manner.)

  • The --message option takes an argument, so its args property contains an Argument object. Including an argument object here is essential. Without it, Fig will render incorrect suggestions as the user is typing their message input.

Next Steps

Once you have the basic structure or skeleton, you can enrich the autocomplete experience by writing code that produces dynamic suggestions for argument values.

Generating Suggestions at Runtime

To learn how to run shell commands and read local files in order to list contextually relevant options, see "Dynamic Suggestions".

You can also specify how you want the suggestions to look and behave.

Customizing the Appearance of Suggestions

For an overview of the different properties that you can tweak, see "Customizing Suggestions".

On this page