DocsSubcommand

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

name

Type: SingleOrArray\<string>

Required:

Description:

The exact name of the subcommand. It is important to get this right for parsing purposes.

Example:

For npm install, the subcommand install would have "name: install"


subcommands

Type: Subcommand[]

Required:

Description:

A list of subcommands for this spec. Subcommands can be nested recursively.


options

Type: Option[]

Required:

Description:

A list of option objects for this subcommand.


args

Type: SingleOrArray\<Arg>

Required:

Description:

An array of args or a single arg.

If a subcommand takes an argument, please at least include an empty Arg Object (e.g. {}). If you don't, Fig will assume the subcommand does not take an argument and we will present the wrong suggestions.

Example:

git push takes two arguments. The most basic representation of this is args: [{}, {}]


additionalSuggestions

Type: (string

Required:

Description:

A list of Suggestion objects that are appended to a specific subcommand. These are often shortcuts.

Example:

commit -m '{cursor}' is a shortcut for git


loadSpec

Type: LoadSpec

Required:

Description:

Allows Fig to load another completion spec in the ~/.fig/autocomplete folder. Specify the spec name without js.

Example:

aws-s3 refers to the ~/.fig/autocomplete/aws-s3 spec.

When is this used? The aws spec is so large that it is slow to load. It needs to be broken up into a separate spec for each subcommand.

If your CLI tool takes another CLI command (e.g. time , builtin) or a script (e.g. python, node) and you would like Fig to continue to provide completions for this script, see isCommand and isScript in Arg.


generateSpec

Type: ( tokens?: string[], executeShellCommand?: ExecuteShellCommandFunction ) => Promise\<Spec>

Required:

Description:

Dynamically generate a completion spec to be merged in at the same level as the current subcommand. This is useful when a CLI is generated dynamically. This function takes two params:

  1. Tokens: an array of strings (the tokens the user has typed)
  2. executeShellCommand: a function that takes a string as input. It executes this string as a shell command on the user's device from the same current working directory as their terminal. It outputs a text blob. It is also async.

generateSpec outputs a completion spec object.

Example:

The python spec uses generateSpec to insert the django-admin spec if django manage.py exists.


parserDirectives

Type: { flagsArePosixNoncompliant?: boolean; }

Required:

Description:

These flags allow customization of how Fig parses tokens from the command line.

Currently, the only parser option that exists is flagsArePosixNoncompliant. This allows options to have multiple characters even if they only have one hyphen when set to true.

Example:

-work 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.


displayName

Type: string

Required:

Description:

See Suggestion

Example:

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

Type: string

Required:

Description:

See Suggestion

Example:

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


description

Type: string

Required:

Description:

See Suggestion


icon

Type: string

Required:

Description:

See Suggestion

Example:

A, 😊 https://www.herokucdn.com/favicon.ico fig://icon?type=file


isDangerous

Type: boolean

Required:

Description:

See Suggestion

Example:

This is used in the rm spec.


priority

Type: number

Required:

Description:

See Suggestion

Example:

If you want your suggestions to always be at the top order regardless of whether they have been selected before or not, rank them 76 or above.

If you want your suggestions to always be at the bottom regardless of whether they have been selected before or not, rank them 49 or below


hidden

Type: boolean

Required:

Description:

See Suggestion

Example:

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