DocsAutocomplete for teamsCommander

Fig Autocomplete & Commander.js

This tutorial will walk you through setting up Fig's integration with JS CLI framework, Commander.

How does it work?

  1. Configure the @withfig/commander commander extension (discussed below)
  2. Generate & save the completion spec
  3. Customize your spec (as discussed in our getting-started guide)
  4. Deploy it (as discussed in our Autocomplete for Teams guide)

Configure the @withfig/commander commander extension

# Go to your CLI's project
cd path/to/my/project

# Install the dependency
npm i -D @withfig/commander
# or if you are using yarn
yarn add -D @withfig/commander
import { generateFigSpec } from '@withfig/commander'
import { program } from 'commander'

// Configure your program here...

if (process.env.NODE_ENV === 'development') {
  program
    .command('generateFigSpec')
    .description('Generate a fig spec')
    .action(() => {
      generateFigSpec(program, '.fig/autocomplete/src/my-cli.ts')
    })
}
program.parse()

See other ways of using @withfig/commander extension in the package README

Save and Deploy your spec

Setup Fig's Development Environment

First, we need to set up Fig's developer environment.

This is quite simple, but if you want to understand more, read this guide.

Go to the root folder of your CLI tool and run the following

npx @withfig/autocomplete-tools@latest init

This will create a .fig/ folder in the root of your CLI project.

From now on, you should build and edit your completion specs in the .fig/autocomplete/src folder.

Save your spec

Use your new generateFigSpec subcommand to generate a spec and save it to the `.fig/autocomplete/src` folder.

my-cli generateFigSpec

(Make sure you replace the occurrences of my-cli with your own CLI's name)

Test your spec

Turn on dev mode by running the following:

npm run dev

Go to a new terminal and run my-cli[space]. Suggestions for your tool will appear in Fig's autocomplete window.

Customize your spec

Customize your spec as discussed in our getting started guide.

You can do this later, but let's skip this for now.

Deploy to Fig's Cloud

This is quite simple but if you want to read more, check out Fig's Autocomplete for Team's guide.

# Create a new team
npx fig-teams@latest teams create <team>

# Add co-workers to your team
npx fig-teams@latest teams add:user <email> -t <team>   

# Compile your completion specs
npm run build

# Link your compiled completion specs to a team (use space to select / deselect)
npx fig-teams@latest manifest

# Deploy your completion specs to Fig's cloud.
npx fig-teams@latest deploy

After deploying, you and your teammates just need to restart Fig, and autocomplete for your CLI should work out of the box!

Keeping your CLI and completion spec in sync

Chances are you make regular changes to your CLI tool, e.g. you add new subcommands/options/arguments, edit descriptions etc.

Fig makes it easy to reflect these changes in your completion spec.

Our "merge tool" takes your old spec and your new one and deep merges them.

  • What is kept: All your customizations to the old spec (like generators, custom icons, parser directives etc) will be kept. Only changes to the skeleton will be merged.
  • What is changed: New subcommands/options/arguments are added. Removed subcommands/options/arguments are deleted. Descriptions are updated.
  • In general: If the completion specs are generated through one of Fig's CLI integrations, selecting the correct preset will ensure that the specs are merged correctly.

How do I do the merge

npx @withfig/autocomplete-tools@latest merge <path/to/oldSpec.ts> <path/to/newSpec.ts> --preset commander

Automating this in CI/CD

You can automate the creation and deep merging of specs in your CI/CD.

cd path/to/your/cli/tool

# Compile your completion spec
cd .fig/autocomplete/
npm run build

# Deep merge new spec into old spec
# generateFigSpec subcommand should be configured to output the new spec to build/my-new-cli.ts
my-cli generateFigSpec && npx @withfig/autocomplete-tools@latest merge build/my-cli.ts build/my-new-cli.ts --preset commander

# Deploy new spec
npx fig-teams@latest deploy

Note: The code block above assumes you build your CLI first. If you don't, your my-cli genFigSpec command won't work.

Next Steps

Customize my completion spec
Check out our Getting Started Guide guide.)

Want to associate your spec with a specific version of the CLI?
See How can my spec account for different versions of a CLI

Questions? Problems?
Email hello@fig.io