DocsAutocompleteSchemasArg

The Arg Object is a blueprint used to generate dynamic suggestions for users based on their context. e.g. when a user types git push [remote] [branch] they expect to first see suggestions for all the remote repos connected to their local git repo, then all of the local branches connected to their local git repo.

Important: Fig relies on Subcommand and Option objects correctly including an Arg Objects when relevant. This is important for our parsing and generating suggestions. e.g. in git commit -m 'my message' we see that -m is an option that takes an argument. If we don't specify that -m takes an arg, when the user starts typing their commit message, Fig will begin generating suggestions for the wrong thing.

Ideally your arg object includes a name, description, and generator, however, if you are just building the skeleton of a CLI tool, It is okay to specify an empty Arg Object e.g.

// dummy option object
const commitOption: Fig.Option = {
  name: "-m",
  description: "commit message",
  // empty Arg Object
  args: {},
};

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 suggestions generated by this argument are "dangerous". If so, Fig will not enable its insert and run functionality (when the red icon appears that automatically executes commands for you rather than just inserting)

Remark:

This is used in specs like rm and trash.


suggestions

Type: string[]

Required:

Description:

An array of strings or Suggestion obejcts. Use this prop 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 context, you most likely will want to use a Generator object in this arg's generator prop.


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


variadic

Type: boolean

Required:

Description:

Specifies that the argument is variadic and therefore repeats infinitely.

Example:

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


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:

Exactly the same as isCommand, except, you specify a string to preprend 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

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:

Exactly 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. This is just a string

On this page