# \`fig build\`

`fig build` lets you visually build a CLI tool. Under the hood, it edits a [.fig](https://fig.gitbook.io/fig/build-a-cli/.fig-file) file which contains the schema for the CLI. 

Fig Build helps you do 3 things:

1. Quickly define command and subcommand hierarchy with a drag and drop interface
2. Attach scripts to each command
3. Attach an [interactive runbook](https://fig.gitbook.io/fig/interactive-runbooks-2) to each command. This makes the CLI more discoverable.

The instructions are contained in the `fig build` app but are also here for reference.

## Getting Set Up

1. In your Terminal, navigate to the directory where you want to define your CLI
   * Usually this is in a scripts folder somewhere in a shared repo
2. Run `fig build`
   * Fig will create a .fig file for you (named whatever you choose to name your CLI)
3. Follow the instructions in the app (or below) to define subcommands
4. Add the directory from Step 1 to your [$FIGPATH](https://fig.gitbook.io/fig/the-fig-cli/figpath)
   * You can do this in [Settings](https://fig.gitbook.io/fig/get-started/fig-home/settings)
   * Your teammates should add their specific path to their $FIGPATH too

## Using your CLI 

Anyone who wishes to use the CLI you have built must add the path to the .fig file to their [$FIGPATH](https://fig.gitbook.io/fig/the-fig-cli/figpath). You can do this in [Settings](https://fig.gitbook.io/fig/get-started/fig-home/settings).

The general syntax for running the CLI is:

`fig [.fig file name] [subcommand 1] [subcommand 2] ... [inputs]`

e.g. If I named my .fig file `acme.fig` and had a subcommand called *deploy* which took a flag input, I would run:

`fig acme deploy --flag`

## Managing Subcommand Hierarchy

The left panel of Fig Build lets you quickly add, remove, re-order, and re-nest subcommands. Simply drag the subcommand around and release. 

Your subcommands follow the hierarchy you specify and are separated by spaces.

## Defining your Subcommands

Clicking on a subcommand will let you edit it. When you run a command through the Fig CLI, two things can happen:

1. If you pass no inputs to your subcommand it will open the Runbook you defined in the Fig window
2. If you pass inputs, it will execute the script you specify.

You can override this so the script will always execute no matter what with the checkbox at the bottom of the page.

### Attaching Scripts to Commands

Define what script to run when you execute a specific CLI command.This is a simple shell one-liner.

Fig provides you with a special variable called *$SELECTEDPATH* . This is the path to the .fig file that you added to your $FIGPATH. You don't have to use *$SELECTEDPATH*  but it lets you share CLI workflows across teams when repos may be in different directories 

* `python3 my/path/to/deploy.py` will work on your computer
* `python3 $SELECTEDPATH/deploy.py` will work on your computer and your teammates' so long as you both have added the path to the .fig file to your $FIGPATH

**Note**: `$SELECTEDPATH`does not have a trailing forward slash

### Attaching [Interactive Runbooks](https://fig.gitbook.io/fig/interactive-runbooks-2) to Commands

If you run a CLI command without passing any inputs, Fig will automatically open the interactive runbook  you define. 

For more information on writing the runbook, please refer to the [Interactive Runbook ](https://fig.gitbook.io/fig/interactive-runbooks-2)documentation.

**Why do we do this?**

We do this as it makes a CLI more approachable and discoverable to your team. It is very easy to forget or mistype flags or other inputs. It is also easy to build a script that is useful to your team but isn't documented well. It therefore never ends up getting used. Fig hopes to solve these problems by bringing its new interactive documentation to your scripts when you need it, and executing the commands as you usually do when you don't.

## Other Tips

### Whitelabel your CLI

It's a good idea to name your .fig file `acme.fig` where "acme" is the name of your company. Then you can set a shell alias (like below) to white label all subcommands referenced in the file

```bash
alias acme='fig acme'
```

Now rather than running `fig acme listpods` you can just run `acme listpods`

**Note**: You can easily set up aliases for yourself in the Fig aliases app: `fig alias`