DocsOption

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.

Declaration:name: string | string[];

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

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: ["-m", "--message"]

args

An array of arg objects or a single arg object

Optional Property:true

Declaration:args?: Arg | Arg[];

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 isOptiona

Examples

  • npm run takes one mandatory argument. This can be represented by args: { }
  • git push takes two mandatory arguments. This can be represented by: args: [{ isOptional: true }, { isOptional: true }]
  • git clone takes two optional arguments. This can be represented by: args: [{ isOptional: true }, { }]

isPersistent

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

Optional Property:true

Declaration:isPersistent?: boolean;

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.

Default Value:false

Example

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.


isRequired

Signals whether an option is required.

Optional Property:true

Declaration:isRequired?: boolean;

Default Value:false (option is NOT required)

Example

The -m option of git commit is required


requiresEquals

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

Optional Property:true

Declaration:requiresEquals?: boolean;

Default Value:false (does NOT require an equal)

Example

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


isRepeatable

Signals whether an option can be passed multiple times.

Optional Property:true

Declaration:isRepeatable?: boolean | number;

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.

Default Value:false (option is NOT repeatable)

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.

exclusiveOn

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

Optional Property:true

Declaration:exclusiveOn?: string[];

Discussion

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

Default Value:false

Example

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"]


dependsOn

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

Optional Property:true

Declaration:dependsOn?: string[];

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.

Default Value:false

Example

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


displayName

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

Optional Property:true

Declaration:displayName?: string;

Default Value:the name prop

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

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

Optional Property:true

Declaration:insertValue?: 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.

Default Value:The value of the name prop.

Example

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


description

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

Optional Property:true

Declaration:description?: string;

Example

"Your commit message"


icon

The icon that is rendered is based on the type.

Optional Property:true

Declaration:icon?: string;

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.

Default Value

related to the type of the object (e.g. Suggestion, Subcommand, Option, Arg)

Examples

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

isDangerous

Specifies whether the suggestion is "dangerous".

Optional Property:true

Declaration:isDangerous?: boolean;

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.

Default Value:false

Example

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


priority

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

Optional Property:true

Declaration:priority?: number;

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

Default Value:50

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

hidden

Specifies whether a suggestion should be hidden from results.

Optional Property:true

Declaration:hidden?: boolean;

Discussion

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

Default Value:false

Example

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


deprecated

Specifies whether a suggestion is deprecated.

Optional Property:true

Declaration

deprecated?: boolean | Omit<BaseSuggestion, "deprecated">;

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.

Example

deprecated: { insertValue: '--ansi never', description: 'The --no-ansi option has been deprecated in v2' }