`fig build`

fig build lets you visually build a CLI tool. Under the hood, it edits a .fig 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 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

    • You can do this in 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. You can do this in 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: $SELECTEDPATHdoes not have a trailing forward slash

Attaching Interactive Runbooks 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 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

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

Previous⚒️ Build your own CLINext.fig Files

Last updated