DocsAutocomplete for internal tools

Autocomplete for internal tools

Make internal CLI tools more discoverable with Fig.

Teams add Fig to their internal tools for...

  • Powerful & intelligent autocomplete
  • Inline search for common workflows
  • Automatic documentation
  • Insights about how their internal tooling is used

1. Set up Development Environment

Navigate to your CLI tool repo and then run the following command.

yarn create completion-spec my-cli

Make sure that the name of completion spec — in this case my-cli —matches the name of the CLI executable.

This will create .fig/autocomplete and set up the development environment.

Now cd .fig/autocomplete and run your command

2. Create completion spec

There are two ways for Fig to index your CLI tool.

CLI Framework Introspection

If your CLI tools is built with one of the following frameworks, Fig can automatically generate a completion spec for you.

Manual Documentation

If you aren't using one of the supported CLI frameworks, you'll need to manually document the structure of your CLI tool.

  1. Open the .fig/autocomplete/src/my-cli.ts in your code editor.

  2. Turn on Developer Mode to view your completions.

    • Run yarn dev and changes you make to the completion spec will be reflected immediately.

      Note: while in Developer Mode, all completions are loaded locally from $REPO/.fig/autocomplete/build.

      Completions for standard tools, like cd or git, will not appear until Developer Mode is disable.

    • Type out the name of your CLI tool and then add a space. Autocomplete should appear.

      If completions aren't showing up, run which my-cli.

      If your CLI tool is aliased, change the name of the completion spec to match the name of the executable.

  3. Write the completions in .fig/autocomplete/src/my-cli.ts

    Document all of the subcommands, options and arguments.

    To learn more about the completion schema, check out "Schema Overview".

3. Publish spec

Create a Team

Once you've documented your CLI tool with a Fig completion spec, you'll need to create a new team.

You'll need to create a new team in order to distribute completions for your CLI tool.

To create a new team, run the following command:

fig team --new apple

To add members to a team, you can run:

fig team apple add steve.jobs@apple.com
Publish from the CLI

Finally, to publish your spec you can run:

npx @fig/publish-spec-to-team \
    --spec-path path/to/my-cli.ts \
  --team apple

Publishing a spec in a CI is very similar to pushing interactively from the CLI. The only difference is that rather then using your local credentials, you'll need to pass in an API token.

# Generate a Fig API token
fig user tokens generate my_ci_token \
    --expires-in=360d \
    --team apple

Then add the following job to your CI workflow.

name: 'Release new version'
  push:
    tags:        
      - 'webkit-tools@*'

jobs:
  build:
    # Build the CLI tool
  publish-spec-to-team:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Publish spec to team
        id: test
        uses: withfig/publish-spec-to-team@1
        with:
          token: ${{ secrets.FIG_API_TOKEN }} # This is the api token generated from the step 
          name: webkit-tools
          team: apple-webkit
          bin-path: ./lib/webkit-tools # This is the path to the built executable, we will run it to generate the spec
        # spec-path: ./generated/webkit-tools.ts Otherwise you can provide an already generated spec
          framework: cobra

NOTE: See more use cases and options on the publish-spec-to-team's README.