Fig

https://fig.io/docs
Admin
Fig provides visual autocomplete for command-line interface (CLI) tools and scripts, enhancing...
Tokens:20,065
Snippets:170
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example Fig Completion Spec

Source: https://fig.io/docs/getting-started

A basic Fig completion spec written in TypeScript, defining a command with subcommands and options. This is auto-generated by `npm run create-spec`.

```typescript
const completionSpec: Fig.Spec = {
  name: "abc",
  description: "",
  subcommands: [
    {
      name: "my_subcommand",
      description: "Example subcommand",
      subcommands: [
        {
          name: "my_nested_subcommand",
          description: "Example nested subcommand",
        },
      ],
    },
  ],
  options: [
    {
      name: ["-h", "--help"],
      description: "Help for abc",
    },
  ],
};
```

--------------------------------

### Start Fig Development Mode

Source: https://fig.io/docs/index

This command starts Fig in developer mode. While active, Fig automatically recompiles and loads any updated completion specs from your local development repository, allowing for rapid testing of your custom completions.

```bash
npm run dev
```

--------------------------------

### Tokenizer Examples: Standard Input

Source: https://fig.io/docs/handbook/tokenizer

Demonstrates how Fig's tokenizer converts a standard command-line input into a list of string tokens.

```shell
User Input| Tokenized Output
---
`git push origin main`
|
`["git", "push", "origin", "main"]`
```

--------------------------------

### Install Dependencies for Fig Development

Source: https://fig.io/docs/index

This command installs the necessary Node.js dependencies required for developing and testing Fig completion specs. It uses npm, the Node Package Manager, to download and install packages listed in the project's package.json file.

```bash
npm install
```

--------------------------------

### Tokenizer Examples: Options with Arguments

Source: https://fig.io/docs/handbook/tokenizer

Explains how the tokenizer parses options that take arguments, whether separated by space or an equals sign.

```shell
User Input| Tokenized Output
---
Long options
`--message="hello"` and `--message "hello"`
  
|
`["--message", "hello"]`
Short options
`-m "hello"` and `-m="hello"`
|
`["-m", "hello"]`
Short options with arguments not separated by `=` or space
`grep -C50`
  
_See exceptions to this below_|
`["grep", "-C", "-50"]`
```

--------------------------------

### Tokenizer Examples: Chained Short Options

Source: https://fig.io/docs/handbook/tokenizer

Demonstrates the parsing of chained short options, including cases with and without trailing arguments.

```shell
User Input| Tokenized Output
---
Normal chained options
`ps -aux`
|
`["ps", "-a", "-u", "-x"]`
Chained options with argument at end
  
`grep -abC555` →
_See exceptions to this below_|
`["grep", "-a", "-b", "-C", "555"]`
```

--------------------------------

### Set Up Fig Autocomplete Repository Remotes

Source: https://fig.io/docs/index

After cloning the repository, navigate into the directory and add the upstream repository as a remote. This allows you to pull the latest updates from the official Fig repository and contribute your changes back.

```bash
cd fig-autocomplete
git remote add upstream https://github.com/withfig/autocomplete.git
```

--------------------------------

### Example Fig Completion Spec Structure (TypeScript)

Source: https://fig.io/docs/index

This TypeScript code defines a basic structure for a Fig completion spec. It includes the spec's name, description, subcommands, and options. This serves as a template that can be expanded upon to define complex autocompletion behavior.

```typescript
const completionSpec: Fig.Spec = {
  name: "abc",
  description: "",
  subcommands: [
    {
      name: "my_subcommand",
      description: "Example subcommand",
      subcommands: [
        {
          name: "my_nested_subcommand",
          description: "Example nested subcommand",
        },
      ],
    },
  ],
  options: [
    {
      name: ["-h", "--help"],
      description: "Help for abc",
    },
  ],
};

```

--------------------------------

### Clone Fig Autocomplete Repository

Source: https://fig.io/docs/index

This command clones the Fig autocomplete repository from GitHub to your local machine. Ensure you replace 'YOUR_GITHUB_USERNAME' with your actual GitHub username. This step is crucial for setting up your development environment.

```bash
git clone https://github.com/YOUR_GITHUB_USERNAME/autocomplete.git fig-autocomplete
```

--------------------------------

### Tokenizer Examples: Escape Characters

Source: https://fig.io/docs/handbook/tokenizer

Shows how the tokenizer interprets escape characters, treating escaped spaces as part of the preceding token.

```shell
User Input| Tokenized Output
---
`echo hello\ world 1234`
|
`["echo", "hello world", "1234"]`
```

--------------------------------

### Tokenizer Examples: Handling Quotes

Source: https://fig.io/docs/handbook/tokenizer

Illustrates how Fig's tokenizer handles both double and single quotes, preserving quoted content as a single token.

```shell
User Input| Tokenized Output
---
Double Quotes
`git commit -m "brendan's commit message"`
|
`["git", "commit", "-m", "brendan's commit message"]`
Single Quotes
`git commit -m 'my "commit" msg'`
| `['git', 'commit', '-m', 'my "commit" msg']`
```

--------------------------------

### Enable Fig Development Mode

Source: https://fig.io/docs/guides/personal-shortcuts

Starts Fig in development mode, which enables live compilation and testing of your custom completion specs. This command is run from the root of your spec project.

```bash
npm run dev

```

--------------------------------

### Example cd completion spec using 'folders' template

Source: https://fig.io/docs/reference/generator/templates

This example demonstrates how to use the 'folders' template within a completion spec for the 'cd' command. It simplifies the process of providing directory suggestions by using the predefined template instead of a complex generator.

```typescript
const completion: Fig.Spec = {
  name: "cd",
  description: "Change the shell's working directory.",
  args: {
        name: "directory"
        template: "folders"
  }
};

```

--------------------------------

### Initialize Fig Autocomplete Environment

Source: https://fig.io/docs/guides/private-autocomplete

Initializes the necessary `.fig/` directory structure in your project to start building autocomplete specifications. This command sets up the folders for specs and user-defined mixins, along with their respective build and source directories.

```bash
npx @withfig/autocomplete-tools@latest init

```

--------------------------------

### Create a New Fig Completion Spec

Source: https://fig.io/docs/index

This command utilizes the 'create-spec' script provided by the Fig project to generate a new, basic completion spec. The argument 'abc' specifies the name for the new spec. This script will create a template file for you to customize.

```bash
npm run create-spec abc
```

--------------------------------

### Define Subcommand with Aliases - Fig Spec

Source: https://fig.io/docs/reference/subcommand

This example shows how to define a subcommand with multiple aliases using the 'name' property. It's useful when a subcommand can be invoked by different strings, like 'install' and 'i' for npm.

```yaml
name: ["install", "i"]
```

--------------------------------

### Example Custom Generator for 'ls'

Source: https://fig.io/docs/reference/generator

An example of a custom generator function that executes the 'ls' command and maps its output to suggestions. It demonstrates how to use the `executeShellCommand` function.

```typescript
const generator: Fig.Generator = {
  custom: async (tokens, executeShellCommand) => {
    const out = await executeShellCommand("ls");
    return out.split("\n").map((elm) => ({ name: elm }));
  },
};
```

--------------------------------

### Execute Git Branch Command

Source: https://fig.io/docs/reference/generator

Example of executing a shell command 'git branch' to get a list of branches. The output of this command is then processed by a postProcess function to generate suggestions.

```shell
git checkout <branch>
```

--------------------------------

### Basic Generator Example for Git Branches

Source: https://fig.io/docs/reference/generator/basic

This JavaScript code defines an argument 'branch' for a CLI command, using a generator to fetch Git branch suggestions. The 'script' executes 'git branch -l' and 'postProcess' formats the raw output into an array of suggestion objects, each with a name and description.

```javascript
{
  name: "branch",
  generators: [
    {
      script: "git branch -l",
      postProcess: function(out) {
        return out.split('\n').map(branch => {
          return { name: branch, description: "branch"}
        })
      }
    }
  ]
}
```

--------------------------------

### Basic Filepath Generator Script in Fig (JavaScript)

Source: https://fig.io/docs/reference/generator/contextual

This initial JavaScript function for a Fig generator takes the last component of the context and constructs a shell command to list files and folders. It's a starting point before adding logic to handle directory navigation and path escaping.

```javascript
script: function(context) {
  let path = context[context.length - 1]

  return `ls -1AF ${path} | xargs -I '{}' echo $PWD/{}`
}
```

--------------------------------

### Configure Argument as a Local Script Spec

Source: https://fig.io/docs/reference/arg

This example shows how to use `isScript: true` to indicate that an argument is a local script. Fig will then look for a completion spec in the user's current directory's `.fig/autocomplete/build` folder, allowing for custom completions for local scripts.

```typescript
{
  name: "python",
  args: [
    {
      name: "script",
      isScript: true,
    },
  ],
}
```

--------------------------------

### Tokenizer Configuration: Non-POSIX Compliant Flags

Source: https://fig.io/docs/handbook/tokenizer

Illustrates how the `posixNoncompliantFlags` setting can alter the tokenizer's behavior for specific options.

```shell
User Input| Tokenized Output
---
Non posix compliant options `posixNoncompliantFlags`
`ps -aux`
|
`["ps", "-aux"]`
```

--------------------------------

### Execute Generic Shell Command

Source: https://fig.io/docs/reference/generator

Example of executing a generic shell command like 'ls' or 'git branch'. The output can be processed further using postProcess or splitOn.

```shell
ls
```

--------------------------------

### description API

Source: https://fig.io/docs/reference/subcommand

The text that gets rendered at the bottom of the autocomplete box, providing additional context for the user.

```APIDOC
## description API

### Description
The text that gets rendered at the bottom of the autocomplete box (or the side if you hit ⌘i).

### Method
N/A (String within a spec)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **description** (string) - Optional - Descriptive text to show for a suggestion.

### Request Example
```json
{
  "description": "Your commit message"
}
```

### Response
#### Success Response (N/A)
No direct response, this is a display configuration.

#### Response Example
N/A
```

--------------------------------

### Trigger Function Example - Re-run on '/' change - TypeScript

Source: https://fig.io/docs/reference/generator/triggers-and-filtering

An example trigger function that regenerates suggestions whenever the last index of '/' differs between the current and previous input strings. This is useful for commands like 'cd' where new directory suggestions are needed upon encountering a '/'.

```typescript
function trigger(curr, prev) {
  return curr.lastIndexOf("/") !== prev.lastIndexOf("/")
})
```

--------------------------------

### Define Fig Personal Shortcuts (TypeScript)

Source: https://fig.io/docs/guides/personal-shortcuts

A TypeScript example defining a Fig completion spec for personal shortcuts. It includes various subcommands with icons, descriptions, and `insertValue` properties that specify the terminal commands to be executed. The `` characters are used to clear the initial trigger, and `
` can be used to execute the command automatically.

```typescript
const completionSpec: Fig.Spec = {
  name: "+",
  description: "Fig shortcuts",
  subcommands: [
    {
      icon: "💻",
      name: "Jump to autocomplete repo",
      insertValue: "\b\bcd ~/.fig/projects/autocomplete\n",
      description: "Go ~/.fig/projects/autocomplete",
    },
    {
      icon: "🛠",
      name: "Start dev server",
      insertValue: "\b\bnpm run dev",
      description: "npm run dev",
    },
    {
      icon: "fig://icon?type=github",
      name: "withfig/autocomplete",
      insertValue: "\b\bopen https://github.com/withfig/autocomplete",
      description: "Open Fig Autocomplete Github page",
    },
    {
      icon: "fig://icon?type=github",
      name: "withfig/fig issues",
      insertValue: "\b\bopen https://github.com/withfig/fig/issues",
      description: "Open Fig Issues Github page",
    },
    {
      icon: "fig://icon?type=git",
      name: "Push to staging",
      insertValue: "\b\bgit push origin staging",
      description: "Push current repo to origin/staging",
    },
    {
      icon: "fig://icon?type=heroku",
      name: "View logs",
      insertValue: "\b\bheroku logs --tail",
      description: "Tail logs for current heroku app",
    },
    {
      name: "Good Morning! ☀️",
      icon: "☀️",
      description: "Update brew, NPM and node. Say an inspirational quote",
      insertValue: "\n      brew update; \n      npm install npm@latest -g; \n      npm update -g;\n      brew upgrade node;\n      echo;\n      npx -y fortuity | npx -y cowsay;\n      echo;\n      "
    },
  ],
};

export default completionSpec;

```

--------------------------------

### Define Variadic Argument for echo Command

Source: https://fig.io/docs/reference/arg

This example shows how to define a variadic argument for the 'echo' command. Variadic arguments can accept an unlimited number of values, represented by an ellipsis in man pages. This is useful for commands that take a list of items.

```typescript
{
  args: {
    name: "message",
    isVariadic: true,
  }
}
```

--------------------------------

### Enable Fuzzy Search for npm Package Suggestions

Source: https://fig.io/docs/reference/arg

This snippet demonstrates how to enable fuzzy search for the 'packages' argument in the npm CLI spec. Fuzzy search allows users to find installed packages even with typos or by omitting parts of the package name, improving suggestion accuracy.

```typescript
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
  ],
}
```

--------------------------------

### Command to List Directory Contents in Fig Generator

Source: https://fig.io/docs/reference/generator/contextual

This shell command is used within a Fig generator script to list files and folders in a specified directory. It uses `ls -1AF` to get a detailed, one-item-per-line, listing and `xargs` to process each item, prepending the current working directory to create a full path.

```bash
ls -1AF /directory/to/show/suggestions/for/ | xargs -I '{}' echo $PWD/{}
```

--------------------------------

### Integrate Branch Generator into Git Checkout Spec - TypeScript

Source: https://fig.io/docs/getting-started/generating-argument-suggestions

Integrates the previously defined `branches` generator into the 'git checkout' subcommand's arguments. This enables Fig to provide suggestions for local branches when the user types 'git checkout'. Includes an example option for creating a new branch.

```typescript
const completionSpec: Fig.Spec = {
  name: "git",
  description: "the stupid content tracker",
  subcommands: [
    {
      name: "checkout",
      description: "Switch branches or restore working tree files",
      args: {
        name: "branch",
        description: "the branch you want to checkout",
        isOptional: true,
        generators: branches,
      },
      options: [
        {
          name: ["-b"],
          description: "create and checkout a new branch",
          args: {
            name: "New branch",
          },
        },
      ],
    },
  ],
};

```

--------------------------------

### Get Icon by File Extension - Fig Icon API

Source: https://fig.io/docs/reference/suggestion/icon-api

Request the icon for a specific file type using its extension. You can also request the generic folder icon by passing 'folder' as the type.

```fig
fig://icon?type=txt
fig://icon?type=png
fig://icon?type=folder
```

--------------------------------

### Suggestion Insert Value Property

Source: https://fig.io/docs/reference/suggestion

The `insertValue` property defines the string that gets inserted into the terminal when a user selects a suggestion. It supports special sequences like `\n` for newlines, `\b` for backspaces, and `{cursor}` to place the cursor after insertion.

```typescript
insertValue?: string
```

--------------------------------

### Filter Term Example - Slice after last '/' - TypeScript

Source: https://fig.io/docs/reference/generator/triggers-and-filtering

Provides a concrete implementation for the 'filterTerm' function. It returns the portion of the string after the last '/' if present, otherwise returns the entire string. This is useful for filtering directory suggestions in commands like 'cd'.

```typescript
const generator: Fig.Generator = {
  filterTerm: (curr) => {
    if (curr.includes("/")) {
      return curr.slice(curr.lastIndexOf("/") + 1);
    } else {
      return curr;
    }
  },
};
```

--------------------------------

### Get Native macOS Icon for File Path - Fig Icon API

Source: https://fig.io/docs/reference/suggestion/icon-api

Retrieve the native macOS icon for a given file or folder path. Fig expands `~` to the user's home directory. If the path doesn't exist, it falls back to an icon based on the file extension.

```fig
fig:///Users/mschrage/Desktop
fig://~/Desktop
```

--------------------------------

### Split Script Output into Suggestions

Source: https://fig.io/docs/reference/generator

A simplified way to process script output by splitting it into multiple suggestions based on a delimiter string. Fig automatically creates suggestion objects for each line or segment created by the split. For example, splitting on newline characters (`\n`) creates a suggestion for each line.

```typescript
splitOn?: string
```

--------------------------------

### Mark Suggestions as Deprecated in Fig.io

Source: https://fig.io/docs/reference/option

The 'deprecated' field indicates that a suggestion is no longer recommended. It can be set to a boolean `true` or an object containing a `description` for deprecation notices and optionally an `insertValue` for a replacement suggestion. This helps guide users away from outdated commands.

```typescript
deprecated?: boolean | Omit<BaseSuggestion, "deprecated">
```

```typescript
deprecated: { insertValue: '--ansi never', description: 'The --no-ansi option has been deprecated in v2' }
```

--------------------------------

### Define Basic Git Completion Spec

Source: https://fig.io/docs/getting-started/first-completion-spec

Initializes a Fig completion spec for the 'git' command with its name and description. The `Fig.Spec` type and `export default` are required for compilation.

```typescript
const completionSpec: Fig.Spec = {
  name: "git",
  description: "The basic content tracker",
};

export default completionSpec;

```

--------------------------------

### Build Fig Completion Specs

Source: https://fig.io/docs/guides/personal-shortcuts

Compiles your completion specs from the `src/` directory to the `build/` directory. This command is used when you are not in dev mode and want to update your compiled specs.

```bash
npm run build

```

--------------------------------

### Create a New Fig Completion Spec

Source: https://fig.io/docs/guides/personal-shortcuts

Generates a new completion spec file for a given command. This command should be run after navigating to the `.fig/autocomplete` directory.

```bash
npm run create-spec +

```

--------------------------------

### Add Argument Spec for Git Checkout Branch

Source: https://fig.io/docs/getting-started/first-completion-spec

Specifies the 'branch' argument for the 'git checkout' subcommand. The `args` prop takes an `Arg` object, which can include properties like `name`, `description`, and `isOptional`. This helps Fig render suggestions when the user inputs non-subcommand or non-option text.

```typescript
const completionSpec: Fig.Spec = {
  name: "git",
  description: "The example content tracker",
  subcommands: [
    {
      name: "checkout",
      description: "Switch branches or restore working tree files",
      args: {
        name: "branch",
        description: "the branch you want to checkout",
        isOptional: true,
      },
    },
  ],
};
export default completionSpec;

```

--------------------------------

### Manage Autocomplete Specs with npm Scripts

Source: https://fig.io/docs/guides/private-autocomplete

Provides npm scripts for managing the lifecycle of autocomplete specifications within the `.fig/` directory. These scripts allow for creating new spec files, enabling a development mode for live testing, and compiling specs into a buildable format.

```bash
# Make a new typescript completion spec in src/ 
npm run create-spec <spec_name>

# Start dev mode to see live updates to your spec in your terminal as you edit.
npm run dev

# Compile your specs from the src/ folder to build/ folder (dev mode does this automatically)
npm run build

```

--------------------------------

### Create Git Branch Generator - TypeScript

Source: https://fig.io/docs/getting-started/generating-argument-suggestions

Creates a Fig generator to fetch local Git branches. It executes 'git branch --no-color', processes the output to remove formatting and asterisks, and returns an array of suggestion objects with 'name' and 'description'. Handles potential 'fatal:' errors from the script.

```typescript
const branches: Fig.Generator = {
  script: "git branch --no-color",
  postProcess: (output) => {
    if (output.startsWith("fatal:")) {
      return [];
    }
    return output.split("\n").map((branch) => {
      return { name: branch.replace("*", "").trim(), description: "branch" };
    });
  },
};

```

--------------------------------

### Create Git Completion Spec

Source: https://fig.io/docs/guides/personal-mixins

Generates a new TypeScript completion spec file for the 'git' command using Fig's tools.

```shell
npm run create-spec git

```

--------------------------------

### Add Git Checkout Subcommand Spec

Source: https://fig.io/docs/getting-started/first-completion-spec

Adds the 'checkout' subcommand to the 'git' completion spec. The `subcommands` prop takes an array of subcommand objects, each with a name and description. Fig uses this structure to suggest subcommands.

```typescript
const completionSpec: Fig.Spec = {
  name: "git",
  description: "The example content tracker",
  subcommands: [
    {
      name: "checkout",
      description: "Switch branches or restore working tree files",
    },
  ],
};

```

--------------------------------

### Using Folder Template for 'cd' Command Argument (TypeScript)

Source: https://fig.io/docs/concepts/dynamic-suggestions

Demonstrates how to use the built-in 'folders' template for the 'directory' argument of the 'cd' command. This simplifies the process of providing directory suggestions without manually defining a generator.

```typescript
const completionSpec: Fig.Spec = {
  name: "cd",
  description: "Change the shell's working directory.",
  args: {
        name: "directory"
        template: "folders"
  }
};
```

--------------------------------

### Icon API - Standard Icons

Source: https://fig.io/docs/reference/suggestion/icon-api

Access a library of bundled icons provided by Fig using the `type` query parameter.

```APIDOC
## GET fig://icon

### Description
Retrieves a standard bundled icon from Fig's library.

### Method
GET

### Endpoint
`fig://icon`

### Parameters
#### Query Parameters
- **type** (string) - Required - The name of the standard icon (e.g., `alert`, `github`, `node`). Refer to the documentation for the full list.

### Request Example
```
fig://icon?type=alert
fig://icon?type=github
fig://icon?type=node
```

### Response
#### Success Response (200)
Returns the specified standard icon.

#### Response Example
(Icon image data)
```

--------------------------------

### Define Git checkout options with Fig

Source: https://fig.io/docs/getting-started/first-completion-spec

This TypeScript code defines a Fig completion specification for the 'git checkout' command. It includes an option '-b' to create and checkout a new branch, with an argument for the new branch name. This spec enhances the autocompletion experience for Git users.

```typescript
const completionSpec: Fig.Spec = {
  name: "git",
  description: "The example content tracker",
  subcommands: [
    {
      name: "checkout",
      description: "Switch branches or restore working tree files",
      args: {
        name: "branch",
        description: "the branch you want to checkout",
        isOptional: true,
      },
      options: [
        {
          name: ["-b"],
          description: "create and checkout a new branch",
          args: {
            name: "New branch",
          },
        },
      ],
    },
  ],
};
export default completionSpec;

```

--------------------------------

### Filter Term Function - Extract substring after '/' - TypeScript

Source: https://fig.io/docs/reference/generator/triggers-and-filtering

A function to specify how user input should be matched against suggestions. This example extracts the substring after the last '/' character, effectively filtering suggestions based on the current directory or path segment being typed.

```typescript
const filterTerm = (currentString: string): string => {
  // ...
}
```

--------------------------------

### Icon API - File Icons via Path

Source: https://fig.io/docs/reference/suggestion/icon-api

Retrieve native macOS icons for files or folders by appending their local path to the `fig://` URL. Supports tilde expansion for home directory and fallbacks for non-existent files.

```APIDOC
## GET fig://[PATH]

### Description
Retrieves the native macOS icon for a given file or folder path.

### Method
GET

### Endpoint
`fig://[PATH]`

### Parameters
#### Path Parameters
- **PATH** (string) - Required - The local file or folder path. Supports `~` for the home directory.

### Request Example
```
fig:///Users/mschrage/Desktop
fig://~/Desktop
```

### Response
#### Success Response (200)
Returns an icon representation for the specified path.

#### Response Example
(Icon image data)
```

--------------------------------

### Specify Optional Argument for git push

Source: https://fig.io/docs/reference/arg

This demonstrates defining optional arguments for the 'git push' command. Optional arguments allow users to omit certain parameters, improving flexibility. Fig requires explicit `isOptional: true` to correctly parse these.

```typescript
{
  name: "push",
  args: [
    {
      name: "remote",
      isOptional: true,
    },
    {
      name: "branch",
      isOptional: true,
    },
  ],
}
```

--------------------------------

### Option Definition

Source: https://fig.io/docs/reference/option

This section details the properties available when defining an option for a CLI subcommand in Fig.

```APIDOC
## 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 --version`.
Other options take an argument. For example, `-m` in `git commit -m <message>` requires the "message" parameter.

### Properties

#### name

The exact name of the subcommand as defined in the CLI tool.
```
name: string | string[]
```

##### Examples
For `git commit -m` in the, message option nested beneath `commit` would have `name: ["-m", "--message"]`
For `ls -l` the `-l` option would have `name: "-l"`

#### args

Optional
An array of arg objects or a single arg object
```
args?: Arg | Arg[]
```

##### Examples
`npm run` takes one mandatory argument. This can be represented by `args: { }`
`git push` takes two optional arguments. This can be represented by: `args: [{ isOptional: true }, { isOptional: true }]`
`git clone` takes one mandatory argument and one optional argument. This can be represented by: `args: [{ }, { isOptional: true }]`

#### isPersistent

Optional
Signals whether an option is persistent, meaning that it will still be available as an option for all child subcommands.
```
isPersistent?: boolean
```

##### Examples
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 as we are passing the `--help` option to all `git` subcommands.

#### isRequired

Optional
Signals whether an option is required.
```
isRequired?: boolean
```

##### Examples
The `-m` option of `git commit` is required

#### requiresEquals

Optional
Signals whether an equals sign is required to pass an argument to an option (e.g. `git commit --message="msg"`)
```
requiresEquals?: boolean
```

##### Examples
When `requiresEqual: true` the user MUST do `--opt=value` and cannot do `--opt value`

#### requiresSeparator

Optional
Signals whether one of the separators specified in parserDirectives is required to pass an argument to an option (e.g. `git commit --message[separator]"msg"`) If set to true this will automatically insert an equal after the option name. If set to a separator (string) this will automatically insert the separator specified after the option name.
```
requiresSeparator?: boolean | string
```

##### Examples
When `requiresSeparator: true` the user MUST do `--opt=value` and cannot do `--opt value`
When `requiresSeparator: ':'` the user MUST do `--opt:value` and cannot do `--opt value`

#### isRepeatable

Optional
Signals whether an option can be passed multiple times.
```
isRepeatable?: boolean | number
```

```

--------------------------------

### Configure Argument as a Module Spec

Source: https://fig.io/docs/reference/arg

This snippet demonstrates using `isModule: "prefix/"` to specify that an argument corresponds to a module. Fig will prepend the given prefix to the user's input and look for a completion spec in the `~/.fig/autocomplete/` directory, enabling module-specific completions.

```typescript
{
  name: "python",
  args: [
    {
      name: "module",
      isModule: "python/",
    },
  ],
}
```

--------------------------------

### Load Completion Specification

Source: https://fig.io/docs/reference/arg

Defines how to load the completion specification. It can be a string path, a Subcommand object, or a function that resolves to a SpecLocation or Subcommand. Useful for dynamically loading specs.

```typescript
loadSpec?:
  | string
  | Subcommand
  | ((token: string, executeShellCommand: (commandToExecute: string, cwd?: string) => Promise<string>) => Promise<SpecLocation | SpecLocation[] | Subcommand>)
```

--------------------------------

### Generate Git Branch Suggestions with TypeScript

Source: https://fig.io/docs/getting-started/generating-argument-suggestions

This TypeScript code defines a Fig generator to fetch and process Git branches. It captures the output of 'git branch --no-color', handles potential errors, and formats the branch names for use in command-line completions. Dependencies: Fig types.

```typescript
const branches: Fig.Generator = {
  script: "git branch --no-color",
  postProcess: (output) => {
    if (output.startsWith("fatal:")) {
      return [];
    }
    return output.split("\n").map((branch) => {
      return { name: branch.replace("*", "").trim(), description: "branch" };
    });
  },
};

const completionSpec: Fig.Spec = {
  name: "git",
  description: "the stupid content tracker",
  subcommands: [
    {
      name: "checkout",
      description: "Switch branches or restore working tree files",
      args: {
        name: "branch",
        description: "the branch you want to checkout",
        isOptional: true,
        generators: branches,
      },
      options: [
        {
          name: ["-b"],
          description: "create and checkout a new branch",
          args: {
            name: "New branch",
          },
        },
      ],
    },
    {
      name: "add",
      description: "Stage files to commit",
      args: {
        template: "filepaths",
      },
    },
  ],
};

```

--------------------------------

### Specify Preview Component Path

Source: https://fig.io/docs/reference/suggestion

Explains how to specify a custom component for rendering the preview window for a suggestion. The `previewComponent` property should be the path to the component within the `src` directory, excluding the file extension.

```fig
previewComponent?: string

'ls/filepathPreview'
```

--------------------------------

### Argument Suggestions Property - Fig CLI

Source: https://fig.io/docs/reference/arg

The 'suggestions' property allows for a static list of Suggestion objects or strings to be displayed when a user is typing an argument. These are predefined suggestions known at spec creation time, useful for common or expected argument values.

```typescript
suggestions?: (string | Suggestion)[]
```

--------------------------------

### Process File List to Suggestion Objects (JavaScript)

Source: https://fig.io/docs/reference/generator/contextual

This JavaScript function takes a raw string of file and folder paths, splits it into individual entries, and transforms each into a Suggestion object. It determines if an entry is a folder or a file to set the appropriate name and description, and constructs a 'fig://' URL for the icon. It assumes the input is a newline-delimited string.

```javascript
postProcess: function(files) {
  return files.split('\n').map(path => {
    let components = path.split('/')
    let filename = components[components.length - 1]

    let isFolder = path.endsWith('/')
    if (isFolder) {
      filename = components[components.length - 2] + '/'
    }

    return {
      name: filename,
      icon: 'fig://' + path,
      description: isFolder ? 'folder' : 'file'
    }
  })

}
```

--------------------------------

### Generate Standalone Icons - Fig Template API

Source: https://fig.io/docs/reference/suggestion/icon-api

Create standalone icons using the template functionality. Customize the icon's background color with the 'color' parameter and add a badge with the 'badge' parameter.

```fig
fig://template?color=2ecc71&badge=✓
```

--------------------------------

### Dynamically Load External Spec - Fig Spec

Source: https://fig.io/docs/reference/subcommand

This demonstrates using 'loadSpec' to dynamically load another completion spec at runtime. This is useful for wrapper CLIs or for modularizing large specs, such as including the 'kubectl' spec within a 'kube' command.

```json
{
  "name": "kube",
  "description": "a wrapper around kubectl"
  "loadSpec": "kubectl"
}
```

```json
{
  "name": "s3",
  "loadSpec": "aws/s3"
}
```

--------------------------------

### Git Mixin Completion Spec (TypeScript)

Source: https://fig.io/docs/guides/personal-mixins

A TypeScript definition for a Fig completion spec that adds custom suggestions and shortcuts for the 'git' command, including 'commit', 'stash', 'push', and 'log'. It demonstrates nesting suggestions within subcommands and arguments.

```typescript
const completionSpec: Fig.Spec = {
  name: "git",
  additionalSuggestions: [
    {
      name: "commit -m 'msg'",
      insertValue: "commit -m '{cursor}'",
      description: "Git commit shortcut",
    },
    {
      name: "stash, pull, pop",
      description: "Git stash, pull, and pip shortcut",
      insertValue: "stash; git pull; git stash pop",
      type: "shortcut"
    },
    {
      name: "add, commit, & push",
      description: "Git add, commit, and push shortcut",
      insertValue: "commit -a --allow-empty-message -m ''; git push;",
      type: "shortcut"
    },
    {
      name: "undo most recent commit",
      description: "Git commit shortcut",
      insertValue: "reset --soft HEAD~1",
      type: "shortcut"
    },
    {
      name: "log (pretty print)",
      insertValue: "log --graph --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) %C(dim white)- %an%C(reset)%C(bold yellow)%d%C(reset)' --all",
      description: "Pretty print git log",
    },
  ],
  subcommands: [
    {
      name: "push",
      additionalSuggestions: [
        {
          name: "origin/main",
          insertValue: "origin main"
          description: "Git push origin main",
        }
      ]
    },
    {
      name: "commit",
      options: [
        {
          name: "-m",
          args: {
            suggestions: [{ 
              name: "feat: ",
              insertValue: "'feat: {cursor}'"
            },
            {
              name: "fix: ",
              insertValue: "'fix: {cursor}'"
            }]
          }
        }
      ]
    }
  ]
}

export default completionSpec;

```

--------------------------------

### Git Commit Subcommand Spec (TypeScript)

Source: https://fig.io/docs/concepts/cli-skeleton

A simplified completion spec for the Git CLI, demonstrating the structure for a subcommand ('commit') and an option ('-m' or '--message') that accepts an argument. This spec maps the CLI's structure for Fig's parsing and suggestion rendering.

```typescript
const completionSpec: Fig.Spec = {
  name: "git",
  subcommands: [
    {
      name: "commit",
      options: [
        {
          name: ["-m", "--message"],
          args: [
            {
              name: "message"
            }
          ]
        }
      ]
    }
  ]
}

```

--------------------------------

### dependsOn Option

Source: https://fig.io/docs/reference/option

Specifies options that must be met before this option can be used. If dependencies are not met, they are prioritized in suggestions.

```APIDOC
## dependsOn Option

### Description
Signals that an option requires other options to be present first. If the user has selected an option with unmet dependencies, those dependencies will be boosted in priority in the suggestion list.

### Method
N/A (Configuration property)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **dependsOn** (string[]) - Optional - An array of strings, where each string is the name of another option that this option depends on.

### Request Example
```json
{
  "name": "--extension",
  "dependsOn": ["--project"]
}
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Access Standard Fig Icons

Source: https://fig.io/docs/reference/suggestion/icon-api

Access a bundled library of standard icons provided by Fig. The icon is specified using the 'type' query parameter.

```fig
fig://icon?type=NAME
```

--------------------------------

### Icon API - Adding Badges to Icons

Source: https://fig.io/docs/reference/suggestion/icon-api

Customize icons by adding colored badges using the `color` and `badge` query parameters.

```APIDOC
## GET fig://[PATH or icon]

### Description
Retrieves an icon with an optional badge and custom color.

### Method
GET

### Endpoint
`fig://[PATH or icon]`

### Parameters
#### Query Parameters
- **color** (string) - Optional - A 6-character hex color code (without '#') for the badge background. Defaults to red (`ff0000`).
- **badge** (string) - Optional - A unicode string or emoji to display as the badge.

### Request Example
```
fig:///Users/mschrage/Desktop/hello-world.txt?color=2ecc71&badge=✓
fig://icon?type=txt&color=2ecc71&badge=✓
```

### Response
#### Success Response (200)
Returns the icon with the applied badge and color.

#### Response Example
(Icon image data with badge)
```

--------------------------------

### Icon API - Template Icons

Source: https://fig.io/docs/reference/suggestion/icon-api

Generate standalone icons with a custom background color and an optional badge.

```APIDOC
## GET fig://template

### Description
Generates a standalone icon with a specified background color and an optional badge.

### Method
GET

### Endpoint
`fig://template`

### Parameters
#### Query Parameters
- **color** (string) - Optional - A 6-character hex color code (without '#') for the icon background. Defaults to white (`ffffff`).
- **badge** (string) - Optional - A unicode string or emoji to display on the icon.

### Request Example
```
fig://template?color=2ecc71&badge=✓
```

### Response
#### Success Response (200)
Returns the generated icon.

#### Response Example
(Generated icon image data)
```

--------------------------------

### Specify Preview Component in Fig.io

Source: https://fig.io/docs/reference/option

The 'previewComponent' field allows developers to specify a custom component for rendering the preview window in Fig.io. This component should be referenced by its path relative to the 'src' directory, excluding the file extension.

```typescript
previewComponent?: string
```

--------------------------------

### icon Option

Source: https://fig.io/docs/reference/option

Specifies an icon to visually represent a suggestion. Icons can be simple characters, URLs, or use Fig's protocol.

```APIDOC
## icon Option

### Description
Determines the icon displayed alongside a suggestion. Icons can be single characters, emojis, image URLs, or generated using Fig's custom icon protocol.

### Method
N/A (Configuration property)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **icon** (string) - Optional - The icon to display. Can be a character, URL, or `fig://` protocol string.

### Request Example
```json
{
  "name": "file_icon",
  "icon": "fig://icon?type=file"
}
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### displayName API

Source: https://fig.io/docs/reference/subcommand

The string that is displayed in the UI for a given suggestion. Allows for custom, user-friendly names for suggestions.

```APIDOC
## displayName API

### Description
The string that is displayed in the UI for a given suggestion.

### Method
N/A (String within a spec)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **displayName** (string) - Optional - The custom text to display for a suggestion in the UI.

### Request Example
```json
{
  "name": "install",
  "displayName": "Install an NPM package 📦"
}
```

### Response
#### Success Response (N/A)
No direct response, this is a display configuration.

#### Response Example
N/A
```

--------------------------------

### Define Git Checkout Subcommand Spec - TypeScript

Source: https://fig.io/docs/getting-started/generating-argument-suggestions

Defines the basic structure for the 'git checkout' subcommand within a Fig completion spec. It includes the subcommand name, description, and an optional argument for the branch name.

```typescript
const completionSpec: Fig.Spec = {
  name: "git",
  description: "the stupid content tracker",
  subcommands: [
    {
      name: "checkout",
      description: "Switch branches or restore working tree files",
      args: {
        name: "branch",
        description: "the branch you want to checkout",
        isOptional: true,
      },
    },
  ],
};

```

--------------------------------

### Generate Filepath and Post-process for Fig Generator (TypeScript)

Source: https://fig.io/docs/reference/generator/contextual

This TypeScript code defines a Fig.Generator object used for autocompletion. The `script` function generates a command to list files in a given directory, escaping spaces in the path. The `postProcess` function (identical to the one above) then formats this output into Suggestion objects for the Fig autocompletion system. It triggers on '/' and filters terms by '/'.

```typescript
const filepathGenerator: Fig.Generator = {
      script: function(context) {
        let path = context[context.length - 1]

        if (path.includes('/')) {
          let components = path.split('/')
          components.pop()
          path = components.join('/')
        } else {
          path = '.'
        }

        // escape spaces in path
        path = path.split(" ").join("\\")

        // output full filepath for each item in `path` folder
        return `ls -1AF ${path} | xargs -I '{}' echo $PWD/{}`
      },

      postProcess: function(files) {
        return files.split('\n').map(path => {
          let components = path.split('/')
          let filename = components[components.length - 1]

          let isFolder = path.endsWith('/')
          if (isFolder) {
            filename = components[components.length - 2] + '/'
          }

          return {
            name: filename,
            icon: 'fig://' + path,
            description: isFolder ? 'folder' : 'file'
          }
        })
      },


      trigger: "/",
      filterTerm: "/"

}
```

--------------------------------

### Implementing a Dynamic Filepath Generator Script in Fig (JavaScript)

Source: https://fig.io/docs/reference/generator/contextual

This JavaScript function generates a list of file and folder suggestions dynamically. It processes the user's current path, handling nested directories and spaces within paths, and outputs full file paths suitable for display with native icons. The script runs whenever the trigger condition is met.

```javascript
script: function(context) {
      let path = context[context.length - 1]

      if (path.includes('/')) {
        let components = path.split('/')
        components.pop()
        path = components.join('/')
      } else {
        path = '.'
      }

      // escape spaces in path
      path = path.split(" ").join("\\ ")

      // output full filepath for each item in `path` folder
      return `ls -1AF ${path} | xargs -I '{}' echo $PWD/{}`
    }
```

--------------------------------

### Configure Git Commit Message Suggestion - JSON

Source: https://fig.io/docs/reference/suggestion/customizing-suggestions

This JSON object configures a suggestion for the `-m` flag in `git commit`. It specifies the flag's names, the text to insert into the terminal (including cursor placement), a description, and an argument name.

```json
{
  "name": [ "-m", "--message"],
  "insertValue": "-m \'{cursor}\'",
  "description": "Add a commit message",
  "args": {
    "name": "message"
  }
}
```
Tokens:
Raw