Docs›Subcommand

Subcommand

Used to define subcommands under a main command.

For example, within git commit, commit is a subcommand of git.

Subcommands can also be nested within subcommands.

Properties

The name of the subcommand. Should exactly match the name defined by the CLI tool.

name: string | string[]
Examples

For git checkout, the subcommand checkout would have name: "checkout"

For npm install, the subcommand install would have name: ["install", "i"] as these two values both represent the same subcommand.

Discussion

If a subcommand has multiple aliases, they should be included as an array.

Note that Fig's autocomplete engine requires this name to match the text typed by the user in the shell.

To customize the title that is displayed to the user, use displayName.


subcommands

Optional

An array of Subcommand objects representing all the subcommands that exist beneath the current command. * To support large CLI tools, Subcommands can be nested recursively.

subcommands?: Subcommand[]
Examples

A CLI tool like aws is composed of many top-level subcommands (s3, ec2, eks…), each of which include child subcommands of their own.


Specifies whether the command requires a subcommand. This is false by default.

A space will always be inserted after this command if requiresSubcommand is true. If the property is omitted, a space will be inserted if there is at least one required argument.

requiresSubcommand?: boolean

options

Optional

An array of Option objects representing the options that are available on this subcommand.

options?: Option[]
Examples

A command like git commit accepts various flags and options, such as --message and --all. These Option objects would be included in the options field.


args

Optional

An array of Arg objects representing the various parameters or "arguments" that can be passed to this subcommand.

args?: Arg | Arg[]

This option allows to enforce the suggestion filtering strategy for a specific subcommand.

filterStrategy?: "fuzzy" | "prefix" | "default"
Examples

yarn workspace [name] with fuzzy search is way more useful since we can omit the npm package scope

fig settings uses fuzzy search to prevent having to add the autocomplete. prefix to each searched setting

const figSpec: Fig.Spec {
  name: "fig",
  subcommands: [
    {
      name: "settings",
      filterStrategy: "fuzzy",
      subcommands: [
        {
          name: "autocomplete.theme", // if a user writes `fig settings theme` it gets the correct suggestions
        },
        // ... other settings
      ]
    },
    // ... other fig subcommands
  ]
}
Discussion

Users always want to have the most accurate results at the top of the suggestions list. For example we can enable fuzzy search on a subcommand that always requires fuzzy search to show the best suggestions. This property is also useful when subcommands or options have a prefix (e.g. the npm package scope) because enabling fuzzy search users can omit that part (see the second example below)


A list of Suggestion objects that are appended to the suggestions shown beneath a subcommand.

additionalSuggestions?: (string | Suggestion)[]
Discussion

You can use this field to suggest common workflows.


loadSpec

Optional

Dynamically load another completion spec at runtime.

loadSpec?:
  | string
  | Subcommand
  | ((
      token: string,
      executeShellCommand: (commandToExecute: string) => Promise<string>
    ) => Promise<SpecLocation | SpecLocation[] | Subcommand>)
Examples

Suppose you have an internal CLI tool that wraps kubectl. Instead of copying the kubectl completion spec, you can include the spec at runtime.

{
  name: "kube",
  description: "a wrapper around kubectl"
  loadSpec: "kubectl"
}

In the aws completion spec, loadSpec is used to optimize performance. The completion spec is split into multiple files, each of which can be loaded separately.

{
  name: "s3",
  loadSpec: "aws/s3"
}
Parameters
NameDescription
tokensa tokenized array of the text the user has typed in the shell.
executeShellCommandan async function that can execute a shell command on behalf of the user. The output is a string.
Discussion

loadSpec can be invoked as string (recommended) or a function (advanced).

The API tells the autocomplete engine where to look for a completion spec. If you pass a string, the engine will attempt to locate a matching spec that is hosted by Fig.


generateSpec

Optional

Dynamically generate a Subcommand object a runtime. The generated Subcommand is merged with the current subcommand.

generateSpec?: (
  tokens: string[],
  executeShellCommand: (commandToExecute: string) => Promise<string>
) => Promise<
  | Subcommand
  | ((version?: string) => Subcommand)
  | ((version?: string) => {
      versionedSpecPath: string
      version?: string
    })
>
Examples

The python spec uses generateSpec to include thedjango-admin spec if django manage.py exists.

generateSpec: async (tokens, executeShellCommand) => {
   // Load the contents of manage.py
   const managePyContents = await executeShellCommand("cat manage.py");
   // Heuristic to determine if project uses django
   if (managePyContents.contains("django")) {
     return {
       name: "python",
       subcommands: [{ name: "manage.py", loadSpec: "django-admin" }],
     };
   }
 },
Parameters
NameDescription
tokensa tokenized array of the text the user has typed in the shell.
executeShellCommandan async function that can execute a shell command on behalf of the user. The output is a string.
Discussion

This API is often used by CLI tools where the structure of the CLI tool is not static. For instance, if the tool can be extended by plugins or otherwise shows different subcommands or options depending on the environment.


Configure how the autocomplete engine will map the raw tokens to a given completion spec.

parserDirectives?: {
  flagsArePosixNoncompliant?: boolean
  optionsMustPrecedeArguments?: boolean
  optionArgSeparators?: string | string[]
}
Examples

The -work option from the go spec is parsed as a single flag when parserDirectives.flagsArePosixNoncompliant is set to true. Normally, this would be chained and parsed as -w -o -r -k if flagsArePosixNoncompliant is not set to true.

Parameters
NameDescription
flagsArePosixNoncompliantIndicates that flags with one hyphen may have *more* than one character. Enabling this directive, turns off support for option chaining.
optionsMustPrecedeArgumentsOptions will not be suggested after any argument of the Subcommand has been typed.
optionArgSeparatorsIndicate that options which take arguments will require one of the specified separators between the 'verbose' option name and the argument.

displayName

Optional

The string that is displayed in the UI for a given suggestion.

displayName?: string
Examples

The npm CLI has a subcommand called install. If we wanted to display some custom text like Install an NPM package 📦 we would set name: "install" and displayName: "Install an NPM package 📦"


insertValue

Optional

The value that's inserted into the terminal when a user presses enter/tab or clicks on a menu item.

insertValue?: string
Examples

For the git commit subcommand, the -m option has an insert value of -m '{cursor}'

Discussion

You can use \n to insert a newline or \b to insert a backspace. You can also optionally specify {cursor} in the string and Fig will automatically place the cursor there after insert.


replaceValue

Optional

When the suggestion is inserted, replace the command with this string

replaceValue?: string
Discussion

You can use \n to insert a newline or \b to insert a backspace. You can also optionally specify {cursor} in the string and Fig will automatically place the cursor there after insert. Note that currently the entire edit buffer will be replaced. Eventually, only the root command will be replaced, preserving pipes and continuations.


description

Optional

The text that gets rendered at the bottom of the autocomplete box (or the side if you hit ⌘i)

description?: string
Examples

"Your commit message"


icon

Optional

The icon that is rendered is based on the type.

icon?: string
Examples

A

😊

https://www.herokucdn.com/favicon.ico

fig://icon?type=file

Discussion

Icons can be a 1 character string, a URL, or Fig's icon protocol (fig://) which lets you generate colorful and fun systems icons.


isDangerous

Optional

Specifies whether the suggestion is "dangerous".

isDangerous?: boolean
Examples

This is used in the rm spec. Why? Because we don't want users to accidentally delete their files so we make it just a little bit harder…

Discussion

If true, Fig will not enable its autoexecute functionality. Autoexecute means if a user selects a suggestion it will insert the text and run the command. We signal this by changing the icon to red. Setting isDangerous to true will make it harder for a user to accidentally run a dangerous command.


priority

Optional

The number used to rank suggestions in autocomplete. Number must be from 0-100. Higher priorities rank higher.

priority?: number
Examples

Let's say a user has previously selected a suggestion at unix timestamp 1634087677: - If completion spec did not set a priority (Fig treats this as priority 50), its priority would change to 75 + 0.1634087677 = 75.1634087677; - If completion spec set a priority of 49 or less, its priority would change to 49 + 0.1634087677 = 49.1634087677; - If completion spec set a priority of 76 or more, its priority would change to 76 + 0.1634087677 = 76.1634087677; - If a user had never selected a suggestion, then its priority would just stay as is (or if not set, default to 50).

If you want your suggestions to always be: - at the top order, rank them 76 or above. - at the bottom, rank them 49 or below

Discussion

Fig ranks suggestions by recency. To do this, we check if a suggestion has been selected before. If yes and the suggestions has:

  • a priority between 50-75, the priority will be replaced with 75, then we will add the timestamp of when that suggestion was selected as a decimal.
  • a priority outside of 50-75, the priority will be increased by the timestamp of when that suggestion was selected as a decimal. If it has not been selected before, Fig will keep the same priority as was set in the completion spec If it was not set in the spec, it will default to 50.

hidden

Optional

Specifies whether a suggestion should be hidden from results.

hidden?: boolean
Examples

The "-" suggestion is hidden in the cd spec. You will only see it if you type exactly cd -

Discussion

Fig will only show it if the user exactly types the name.


deprecated

Optional

Specifies whether a suggestion is deprecated.

deprecated?: boolean | Omit<BaseSuggestion, "deprecated">
Examples
deprecated: { insertValue: '--ansi never', description: 'The --no-ansi option has been deprecated in v2' }
Discussion

It is possible to specify a suggestion to replace the deprecated one.

  • The description of the deprecated object (e.g deprecated: { description: 'The --no-ansi option has been deprecated in v2' }) is used to provide infos about the deprecation.
  • deprecated: true and deprecated: { } behave the same and will just display the suggestion as deprecated.