Docs›Versioning 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:
- Normal completions handling versions using JS constructs (better for few changes)
- Diff-versioned specs handled by the autocomplete engine (better for frequently changing CLIs)
Normal completions
- 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. - 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.