Generators

Generators let you run shell commands to generate a list of Suggestions for a given Argument.

Generators are used to programmatically generate suggestion objects. For instance, a generator can fetch a list of git remotes, grab all the folders in the current working directory, or even hit an API endpoint.

For a high level overview of Generators and their usage, see "Dynamic Suggestions".

Quick Summary

Generators let you run shell commands on the user's device to generate suggestions for arguments

Basic Generators

Run a shell command to provide dynamic suggestions.

See "Basic Generators" to understand the most common usage pattern.

Templates

Some generators, like the ones for filepaths and folders, are so common across CLI tools that it doesn't make sense for every spec to reimplement them from scratch.

See "Templates" to quickly provide rich suggestions for files and folders.

Contextual Generators

Provide suggestions that require context from other flags or options in the current edit buffer.

To handle this case, a Generator needs to run a script which incorporates text that the user has typed.

heroku addons:remove --app my-example-app |

For example, when completing this heroku command, Fig should only suggest addons that are associated with the specific app, my-example-app.

See "Contextual Generators" to learn how to run a script that incorporates text from the user's edit buffer.

Triggers & Filtering

Provide a new set of suggestions after the user types a certain character, like the / in a filepath, for instance.

See "Reimplementing the Filepath Generator" for more information of how to use triggers and filterTerm.

Caching & Debouncing

Suggestions are computed by an expensive function — a web request, for instance — and should be cached or debounced.

See "Making an HTTP Request from a Generator" for details on how to handle expensive functions.

Custom Generators

Write imperative code where suggestions must be recomputed on every keypress, to handle tools with non-standard parsing, like chmod.

See "Custom Generators" to learn more.

Properties