DocsVersioning completion specs

Link completion specs to different versions of CLI tools

As CLI tools often change, it's important that users get the right completion spec for the specific version of a CLI tool they are one.

There are two main methods of doing spec versioning:

  1. Normal completions handling versions using JS constructs (better for few changes)
  2. Diff-versioned specs handled by the autocomplete engine (better for frequently changing CLIs)

Normal completions

  1. To get the version, Fig defines a special export called getVersionCommand that allows you to execute a shell command and then return the current version of a user's CLI tool.
  2. To return the right completion spec, Fig allows the Fig.Spec type to be a function that takes in a version, and outputs a normal Fig.Spec object.

Example For instance, yarn has major version 1 and major version 2. There are several commands that exist in v1 but not v2 and vice versa.

The completion spec for yarn looks a little like this:

// The completion spec is a function that returns a Fig.spec object
const completionSpec: Fig.Spec = (version: string): Fig.Spec => {
  var global_subcommands: Fig.Subcommand[] = [
    { name: "subcommand_one" },
    { name: "subcommand_two" },
  ];

  var version_one_subcommands: Fig.Subcommand[] = [{ name: "version_one" }];

  var version_two_subcommands: Fig.Subcommand[] = [{ name: "version_two" }];

  if (version === "1.0.0")
    return {
      name: "yarn",
      subcommands: [...global_subcommands, ...version_one_subcommands],
    };
  else
    return {
      name: "yarn",
      subcommands: [...global_subcommands, ...version_two_subcommands],
    };
};

export default completionSpec;

// Function that returns the semantic version for a given CLI tool,
// then used to load up the relevant completion spec.
export const getVersionCommand: Fig.GetVersionCommand = async (
  executeShellCommand: Fig.ExecuteShellCommandFunction
) => {
  const version: string = await executeShellCommand("yarn --version");
  return version;
};

Diff-versioned specs

Diff-versioned specs are mostly updated and edited through the autocomplete-tools CLI, prefer to these docs to learn how to use them.