Overview

Getting Started
 Fig for Teams

Docs›Option

Option

Options add additional information to a Subcommand. They usually start with - or --.

Some options, called flags, are boolean. Either they are included or not. For example, git --version.

Other options take an argument. For example, -m in git commit -m <message> requires the "message" parameter.

Properties

name

The exact name of the subcommand as defined in the CLI tool.

name: string | string[]
Examples

For git commit -m in the, message option nested beneath commit would have name: ["-m", "--message"]

For ls -l the -l option would have name: "-l"

Discussion

Fig's parser relies on your option name being exactly what the user would type. (e.g. if the user types git "-m", you must have name: "-m" and not something like name: "your message" or even with an = sign likename: "-m=")

If you want to customize what the text the popup says, use displayName.

The name prop in an Option object compiles down to the name prop in a Suggestion object

Final note: the name prop can be a string (most common) or an array of strings

args

Optional

An array of arg objects or a single arg object

args?: Arg | Arg[]
Examples

npm run takes one mandatory argument. This can be represented by args: { }

git push takes two optional arguments. This can be represented by: args: [{ isOptional: true }, { isOptional: true }]

git clone takes one mandatory argument and one optional argument. This can be represented by: args: [{ }, { isOptional: true }]

Discussion

If a subcommand takes an argument, please at least include an empty Arg Object. (e.g. { }). Why? If you don't, Fig will assume the subcommand does not take an argument. When the user types their argument If the argument is optional, signal this by saying isOptional: true.

isPersistent

Optional

Signals whether an option is persistent, meaning that it will still be available as an option for all child subcommands.

isPersistent?: boolean
Examples

Say the git spec had an option at the top level with { name: "--help", isPersistent: true }. Then the spec would recognize both git --help and git commit --help as a valid as we are passing the --help option to all git subcommands.

Discussion

As of now there is no way to disable this persistence for certain children. Also see https://github.com/spf13/cobra/blob/master/user_guide.md#persistent-flags.

isRequired

Optional

Signals whether an option is required.

isRequired?: boolean
Examples

The -m option of git commit is required

requiresEquals

Optional

Signals whether an equals sign is required to pass an argument to an option (e.g. git commit --message="msg")

requiresEquals?: boolean
Examples

When requiresEqual: true the user MUST do --opt=value and cannot do --opt value

requiresSeparator

Optional

Signals whether one of the separators specified in parserDirectives is required to pass an argument to an option (e.g. git commit --message[separator]"msg") If set to true this will automatically insert an equal after the option name. If set to a separator (string) this will automatically insert the separator specified after the option name.

requiresSeparator?: boolean | string
Examples

When requiresSeparator: true the user MUST do --opt=value and cannot do --opt value

When requiresSeparator: ':' the user MUST do --opt:value and cannot do --opt value

isRepeatable

Optional

Signals whether an option can be passed multiple times.

isRepeatable?: boolean | number
Examples

In npm install doesn't specify isRepeatable for { name: ["-D", "--save-dev"] }. When the user types npm install -D, Fig will no longer suggest -D. If the user types npm install -D -D. Fig will still parse the second -D as an option.

Suppose npm install explicitly specified { name: ["-D", "--save-dev"], isRepeatable: false }. Now if the user types npm install -D -D, Fig will instead parse the second -D as the argument to the install subcommand instead of as an option.

SSH has { name: "-v", isRepeatable: 3 }. When the user types ssh -vv, Fig will still suggest -v, when the user types ssh -vvv Fig will stop suggesting -v as an option. Finally if the user types ssh -vvvv Fig's parser will recognize that this is not a valid string of chained options and will treat this as an argument to ssh.

Discussion

Passing isRepeatable: true will allow an option to be passed any number of times, while passing isRepeatable: 2 will allow it to be passed twice, etc. Passing isRepeatable: false is the same as passing isRepeatable: 1.

If you explicitly specify the isRepeatable option in a spec, this constraint will be enforced at the parser level, meaning after the option (say -o) has been passed the maximum number of times, Fig's parser will not recognize -o as an option if the user types it again.

exclusiveOn

Optional

Signals whether an option is mutually exclusive with other options (ie if the user has this option, Fig should not show the options specified).

exclusiveOn?: string[]
Examples

You might see [-a | --interactive | --patch] in a man page. This means each of these options are mutually exclusive on each other. If we were defining the exclusive prop of the "-a" option, then we would have exclusive: ["--interactive", "--patch"]

Discussion

Options that are mutually exclusive with flags the user has already passed will not be shown in the suggestions list.

dependsOn

Optional

Signals whether an option depends on other options (ie if the user has this option, Fig should only show these options until they are all inserted).

dependsOn?: string[]
Examples

In a tool like firebase, we may want to delete a specific extension. The command might be firebase delete --project ABC --extension 123 This would mean we delete the 123 extension from the ABC project. In this case, --extension dependsOn --project

Discussion

If the user has an unmet dependency for a flag they've already typed, this dependency will have boosted priority in the suggestion list.

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.

previewComponent

Optional

Specifies which component to use to render the preview window.

previewComponent?: string
Examples

'ls/filepathPreview'

Discussion

This should be the path within the src directory to the component without the extension.

On this page