DocsAutocomplete for teamsSwift argument parser

Fig Autocomplete & swift-argument-parser

This tutorial will walk you through setting up Fig's integration with Apple CLI framework, swift-argument-parser.

How does it work?

  1. Add the fig-swift-argument-parser dependency to your CLI target
  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)

Add the --generateFigSpec option to your command

Add the fig-swift-argument-parser module as a dependency in your Package.swift file:

let package = Package(
  name: "my-cli",
  dependencies: [
    .package(url: "", from: "1.0.0"),
    .package(url: "", .upToNextMinor(from: "0.1.0")),
    // other dependencies
  targets: [
    .executableTarget(name: "my-cli", dependencies: [
      .product(name: "ArgumentParser", package: "swift-argument-parser"),
      .product(name: "FigSwiftArgumentParser", package: "fig-swift-argument-parser"),
      // other dependencies
    // other targets

Add an @OptionGroup property to the root of your command:

import ArgumentParser
import FigSwiftArgumentParser

public struct MyCli: ParsableCommand {
  @OptionGroup var generateFigSpec: GenerateFigSpec<Self>
  // other variables and methods...

NOTE: ensure that generateFigSpec is the first (instance) variable declaration.

Now when you compile and run my-cli --generateFigSpec you will see the output spec.

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 > .fig/autocomplete/src/my-cli.ts

(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 swift-argument-parser

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
npx @withfig/autocomplete-tools@latest merge build/my-cli.ts <(my-cli --generateFigSpec) --preset swift-argument-parser

# 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?