DocsArg

Argument

The Argument object is used to indicate when a Subcommand or Option takes a user-defined value as a parameter.

Important:

When mapping out the CLI Skeleton, it is essential to include an Argument object when required by a subcommand or options. If no argument is specified but one is expected by the CLI tool, Fig will provide incorrect suggestions and get in the user's way when they try to type it out.

Unlike Subcommand or Option, Argument objects do not conform to the Suggestion type. The only properties on Argument, which are visible in the autocomplete popup are name and description.

Arguments can also include hints about what suggestions should be displayed.

  • Generators, which can only be defined on Arguments, are one example of this. Generators are responsible for providing suggestions for the argument.
  • The isScript, isCommand, and isModule properties also inform what type of suggestions Fig will list.

Properties

name

Type: string

Required:

Description:

The name of an argument. This is different to the name prop for subcommands, options, and suggestion objects so please read carefully. This is a normal, human readable string that signals to the user the type of argument they are inserting if there are no available suggestions. Fig does not use this value for parsing. Therefore, it can be whatever you want.

Example:

The name prop for the git commit -m arg object is "message". You can see this when you type!


description

Type: string

Required:

Description:

The text that gets rendered at the bottom of the autocomplete box a) when the user is inputting an argument and there are no suggestions and b) for all generated suggestions for an argument Keep it short and direct!


isDangerous

Type: boolean

Required:

Description:

Specifies whether the suggestion is "dangerous". If true, Fig will not enable its "insert and run" functionality (when Fig has the red insert icon). This will make it harder for a user to accidentally run a dangerous command.

Example:

This is used in the rm spec.


suggestions

Type: (string

Required:

Description:

An array of strings or Suggestion objects. This is used to specify custom suggestions that are static (ie you know of in advance and don't have to be statically generated). If suggestions are dependent upon the user's input or tokens, you most likely will want to use a Generator object instead.


template

Type: Template

Required:

Description:

Fig has pre-built generators for common suggestion types. Currently, we support templates for either "filepaths" or "folders". You can do either of these as a string or both in an array. Folders will only show folders. Filepaths will show folders and filepaths but will only offer the insert and execute functionality (the red automatic insert icon you see when using cd) for files NOT folders.

Example:

cd uses the folders template whereas ls uses [filepaths, folders]


generators

Type: SingleOrArray\<Generator>

Required:

Description:

Generators let you run shell commands on the user's device to generate suggestions for arguments. The generators prop takes a single generator object or a list of generator objects. The generator object outputs an array of suggestions which are offered to users when inserting an argument.


isVariadic

Type: boolean

Required:

Description:

Specifies that the argument is variadic and therefore repeats infinitely.

Example:

echo takes a variadic argument (echo hello world ...) and so does git add


optionsCanBreakVariadicArg

Type: boolean

Required:

Description:

Specifies whether options can interupt variadic arguments. This is true by default

Example:

echo's variadic argument cannot be broken by options so the -n in echo hello -n world will be consumed by the variadic arg and not as an option.


isOptional

Type: boolean

Required:

Description:

True if an argument is optional. It is important you include this for our parsing. If you don't, Fig will assume the argument is mandatory and will not offer suggestions for a user.

Example:

Git push [remote][branch] takes two optional args


isCommand

Type: boolean

Required:

Description:

Specifies that the argument is an entirely new command which Fig should start completing on from scratch.

Example:

time and builtin have only one argument and this argument has the isCommand property. If I type time git, Fig will load up the git completion spec because the isCommand property is set.


isModule

Type: string

Required:

Description:

The same as the isCommand prop, except you specify a string to prepend to what the user inputs and fig will load the completion spec accordingly. if isModule: "python/", Fig would load up the python/USER_INPUT.js completion spec from the ~/.fig/autocomplete folder.

Example:

For python -m, the user can input a specific module such as http.server. Each module is effectively a mini CLI tool that should have its own completions. Therefore the argument object for -m has isModule: "python/". Whatever the modules user inputs, Fig will look under the ~/.fig/autocomplete/python/ directory for completion spec.


isScript

Type: boolean

Required:

Description:

The same as the isCommand prop, except Fig will look for a completion spec in a .fig folder in the user's current working directory.

Example:

python take one argument which is a .py file. If I have a main.py file on my desktop and my current working directory is my desktop, if I type python main.py Fig will look for a completion spec in ~/Desktop/.fig/main.py.js See our docs for more on this Fig for Teams


debounce

Type: boolean

Required:

Description:

This will debounce every keystroke event for this particular arg. If there are no keystroke events after 100ms, Fig will execute all the generators in this arg and return the suggestions.

Example:

npm install and pip install send debounced network requests after inactive typing from users.


default

Type: string

Required:

Description:

The default value for an optional argument.


loadSpec

Type: LoadSpec

Required:

Description:


parserDirectives

Type: { alias?:

Required:

Description:

On this page