Skip to content

Experimental commands

Adam Wolfe edited this page Aug 1, 2024 · 1 revision

Imperative CLI Framework lets you flag groups and commands as experimental when you develop CLI applications and plug-ins. You might want to specify commands as experimental when a command is not tested fully or when users might receive unexpected results when they issue the command.

As a best practice, We recommend that you define the term experimental for your application and plug-ins and describe your definition in the experimental command help text.

Note: A command that you specify as experimental displays in the help text with the prefix (experimental). When you define a command group as experimental, all commands in that group inherit the experimental flag.

Flagging commands as experimental

To flag commands as experimental, specify true on the experimental parameter in the command definition.

Example:

The following example illustrates the syntax to flag commands as experimental:

const definition: ICommandDefinition = {
  name: "cook", type: "group",
  description: "cook food",
  children: [
    {
      name: "fruit", aliases: ["frt"],
      description: "Cooks a fruit... with a chance of failure",
      type: "command",
      handler: __dirname + "/Handler",
      experimental: true,
    }
  ]
};
module.exports = definition;

More Information:

  • For information about how to define commands for a new application, see Defining Commands.
  • For information about how to define commands for a plug-in, see Developing plugins.

Defining the help text for experimental commands

You can define the global help text that displays on experimental commands. Specify your text on the experimentalCommandDescription parameter in your Imperative CLI Framework configuration.

Example:

The following example illustrates the syntax to use when defining your help text:

  progressBarSpinner: ".oO0Oo.",
  experimentalCommandDescription: "These commands may damage your fruits."

Note: You define the configuration in configurationModule, which is inline where you call the Init() function, or in package.json.

The help text displays when a user issues --help on an experimental command. For example:

Experimental Command Help Text