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

Optional

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

name?: string
Examples

The name prop for the git commit -m <msg> arg object is "msg". But you could also make it "message" or "your message". It is only used for description purposes (you see it when you type the message), not for parsing!


description

Optional

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!

description?: string
Examples

"Your commit message"


isDangerous

Optional

Specifies whether the suggestions generated for this argument are "dangerous".

isDangerous?: boolean
Examples

This is used for all arguments in the rm spec.

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. Turning on isDangerous will make it harder for a user to accidentally run a dangerous command.


suggestions

Optional

A list of Suggestion objects that are shown when a user is typing an argument.

suggestions?: (string | Suggestion)[]
Examples

For git reset <branch or commit>, a two common arguments to pass are "head" and "head^". Therefore, the spec suggests both of these by using the suggestion prop

Discussion

These suggestions are static meaning you know them beforehand and they are not generated at runtime. If you want to generate suggestions at runtime, use a generator


template

Optional

A template which is a single TemplateString or an array of TemplateStrings

template?:
  | ("filepaths" | "folders" | "history" | "help")
  | ("filepaths" | "folders" | "history" | "help")[]
Examples

cd uses the "folders" template

ls used ["filepaths", "folders"]. Why both? Because if I ls a directory, we want to enable a user to autoexecute on this directory. If we just did "filepaths" they couldn't autoexecute.

Discussion

Templates are generators prebuilt by Fig. Here are the three templates:

  • filepaths: show folders and filepaths. Allow autoexecute on filepaths
  • folders: show folders only. Allow autoexecute on folders
  • history: show suggestions for all items in history matching this pattern
  • help: show subcommands. Only includes the 'siblings' of the nearest 'parent' subcommand

generators

Optional

Generators let you dynamically generate suggestions for arguments by running shell commands on a user's device.

This takes a single generator or an array of generators

generators?: Generator | Generator[]

This option allows to enforce the suggestion filtering strategy for a specific argument suggestions.

filterStrategy?: "fuzzy" | "prefix" | "default"
Examples

npm uninstall [packages…] uses fuzzy search to allow searching for installed packages ignoring the package scope

const figSpec: Fig.Spec {
  name: "npm",
  subcommands: [
    {
      args: {
        name: "packages",
        filterStrategy: "fuzzy", // search in suggestions provided by the generator (in this case) using fuzzy search
        generators: generateNpmDeps,
        isVariadic: true,
      },
    },
    // ... other npm commands
  ],
}
Discussion

Users always want to have the most accurate results at the top of the suggestions list. For example we can enable fuzzy search on an argument that always requires fuzzy search to show the best suggestions. This property is also useful when argument suggestions have a prefix (e.g. the npm package scope) because enabling fuzzy search users can omit that part (see the second example below)


Provide a suggestion at the top of the list with the current token that is being typed by the user.

suggestCurrentToken?: boolean

isVariadic

Optional

Specifies that the argument is variadic and therefore repeats infinitely.

isVariadic?: boolean
Examples

echo takes a variadic argument (echo hello world ...)

git add also takes a variadic argument

Discussion

Man pages represent variadic arguments with an ellipsis e.g. git add <pathspec...>


Specifies whether options can interrupt variadic arguments. There is slightly different behavior when this is used on an option argument and on a subcommand argument:

  • When an option breaks a variadic subcommand argument, after the option and any arguments are parsed, the parser will continue parsing variadic arguments to the subcommand
  • When an option breaks a variadic option argument, after the breaking option and any arguments are parsed, the original variadic options arguments will be terminated. See the second examples below for details.
optionsCanBreakVariadicArg?: boolean
Examples

When true for git add's argument: git add file1 -v file2 will interpret -v as an option NOT an argument, and will continue interpreting file2 as a variadic argument to add after

When true for -T's argument, where -T is a variadic list of tags: cmd -T tag1 tag2 -p project tag3 will interpret -p as an option, but will then terminate the list of tags. So tag3 is not parsed as an argument to -T, but rather as a subcommand argument to cmd if cmd takes any arguments.

When false: echo hello -n world will treat -n as an argument NOT an option. However, in echo -n hello world it will treat -n as an option as variadic arguments haven't started yet


isOptional

Optional

true if an argument is optional (ie the CLI spec says it is not mandatory to include an argument, but you can if you want to).

isOptional?: boolean
Examples

git push [remote] [branch] takes two optional args.

Discussion

NOTE: It is important you include this for our parsing. If you don't, Fig will assume the argument is mandatory. When we assume an argument is mandatory, we force the user to input the argument and hide all other suggestions.


isCommand

Optional

Syntactic sugar over the loadSpec prop.

isCommand?: boolean
Examples

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.

Discussion

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


isScript

Optional

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

isScript?: boolean
Examples

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[space] Fig will look for a completion spec in ~/Desktop/.fig/autocomplete/build/main.py.js

Discussion

See our docs for more on building completion specs for local scripts Fig for Teams


isModule

Optional

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.

isModule?: string
Examples

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.

Discussion

If isModule: "python/", Fig would load up the python/USER_INPUT.js completion spec from the ~/.fig/autocomplete folder.


debounce

Optional

This will debounce every keystroke event for this particular arg.

debounce?: boolean
Examples

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

Discussion

If there are no keystroke events after 100ms, Fig will execute all the generators in this arg and return the suggestions.


default

Optional

The default value for an optional argument.

default?: string
Discussion

Note: This is currently not used anywhere in Fig's autocomplete popup, but will be soon.


loadSpec

Optional
loadSpec?:
  | string
  | Subcommand
  | ((
      token: string,
      executeShellCommand: (commandToExecute: string) => Promise<string>
    ) => Promise<SpecLocation | SpecLocation[] | Subcommand>)
Discussion

There is a very high chance you want to use one of the following:

  1. isCommand (See Arg Object)
  2. isScript (See Arg Object)

The arg.parserDirective.alias prop defines whether Fig's tokenizer should expand out an alias into separate tokens then offer completions accordingly.

parserDirectives?: {
  alias?:
    | string
    | ((
        token: string,
        exec: (commandToExecute: string) => Promise<string>
      ) => Promise<string>)
}
Examples

git takes git aliases. These aliases are defined in a user's gitconfig file. Let's say a user has an alias for p=push, then if a user typed git p[space], this function would take the p token, return push and then offer suggestions as if the user had typed git push[space]

npm run <script> also takes an arg called "script". This arg is technically an alias for another shell command that is specified in the package.json. If the user typed npm run start[space], the package.json had script start=node index.js, then Fig would start offering suggestions for as if you had just typed node index.js[space]

Note: In both cases, the alias function is only used to expand a given alias NOT to generate the list of aliases. To generate a list of aliases, scripts etc, use a generator.

Parameters
NameDescription
tokenThe token that the user has just typed that is an alias for something else
executeShellCommandan async function that allows you to execute a shell command on the user's system and get the output as a string.
Discussion

This is similar to how Fig is able to offer autocomplete for user defined shell aliases, but occurs at the completion spec level.