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

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

Properties

name

Type: SingleOrArray\<string>

Required:

Description:

The exact name(s) of the option represented as a string or array of strings. Do NOT include an = sign here as it will mess up the parsing. Fig handles this logic for you.

Example:

For git commit -m, the option name is ["-m", "--message"]


args

Type: SingleOrArray\<Arg>

Required:

Description:

An array of args or a single arg object.

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

Example:

git commit -m takes one argument. The most basic representation of this is args: {}


isPersistent

Type: boolean

Required:

Description:

Signals whether an option is persistent, meaning that it will still be available as an option for all child subcommands. 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.

By default, this option is 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 passing the --help option to all git subcommands.


isRequired

Type: boolean

Required:

Description:

Signals whether an option is required. The default value is false, meaning an option is NOT required.

Signalling that an option is required currently doesn't do anything. However, Fig will handle it in the future.

Example:

The -m option of git commit is required


requiresEquals

Type: boolean

Required:

Description:

Signals whether an equals sign is required to pass an option. This is false by default. When true

Example:

When true --opt=value is parsed with value as an arg to --opt but --opt value is parsed as --opt without an arg passed.


isRepeatable

Type: boolean

Required:

Description:

Signals whether an option can be passed multiple times. The default is an option is NOT repeatable, meaning after you pass it, it will not be suggested again.

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.

Example:

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

Type: string[]

Required:

Description:

Signals whether an option is mutually exclusive with other options. This is defined as an array of strings of the option names. The default behavior is that an option is NOT mutually exclusive with any other options. Options that are mutually exclusive with flags the user has already passed will not be shown in the suggestions list.

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

Type: string[]

Required:

Description:

Signals whether an option depends other options. This is defined as an array of strings of the option names. The default behavior is that an option does NOT depend on any other options. If the user has an unmet dependency for a flag they've already typed, this dependency will have boosted priority in the suggestion list.

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

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 -

On this page