Extending the CLI

It is possible to extend the Compas CLI in projects with custom commands. Giving your collaborators the power to do tasks with a consistent experience of discovery and error handling.

Locations

The Compas CLI checks two places for extra commands: the compas config file, and the top level scripts directory.

Files in the scripts directory can export a cli definition and be upgraded from compas run $name --script-args "--arg 1 to compas $name --arg 1. This is advisable to do for any script requiring arguments to be passed. Making it consistent to document, but also validate these values.

The config/compas.{js,json} is loaded by the config loader. And expects the following config object:

{
  "cli": {
    "commandDirectories": [
      "./directory/relative/to/project/root",
      "./and/another"
    ]
  }
}

All files in the specified directories should also export a cli definition object to be loaded. When checking if a custom file is indeed a command fails, the file is skipped. This also results in files depending on missing dependencies, like dev dependencies in production environments, not registering as a command.

CLI Definition

// Export a cliDefinition to be seen as a command.
/** @type {import("@compas/cli").CliCommandDefinitionInput} */
export const cliDefinition = {
  // `compas todo`
  // required
  name: "todo",

  // Description that is printed in line in the command list
  // required
  shortDescription: "Manage todo items",

  // Used for `compas todo --help` or `compas help todo`
  longDescription: "",

  // Optional object
  modifiers: {
    // Prints the command help output if no sub command is passed.
    // Defaults to false
    isCosmetic: true,

    // When set to true, instead of matching on the name any value can be passed, i.e `compas run generate`, `compas run foo`.
    // Defaults to false.
    isDynamic: false,

    // When set to true, this command allows '--watch' and `cli watch [command.name]`, see 'watchSettings' below, to tune the behaviour.
    // Defaults to false.
    isWatchable: false,
  },

  // Optional flag array. Sub commands also allow the flags defined by their parents.
  flags: [
    {
      // This name is used to store the value
      // required
      name: "namespace",

      // The flag name, requires to be prefixed with `--`
      // requirered
      rawName: "--namespace",

      // Description to show in help output.
      description: "Only return todo's in this namespace",

      // Optional modifiers object
      modifiers: {
        // Make this flag required.
        isRequired: false

        // This flag can be repeated, resulting in an array that is passed to the executor.
        isRepeatable: false,

        // This flag will not show up in any help output.
        isInternal: false,
      },

      // Optional value specification
      value: {
        // Give a type to the value that can be passed. The parser also does the conversion.
        // "boolean" (default): accepts no value, 'true', '1', 'false' and '0'.
        // "number" accepts any value that converts to a number
        // "string" Accept any value.
        // "booleanOrString" A combination of "boolean" and "string", giving the "boolean" parser precedence.
        specification: "string",

        // Optional validator, can return a Promise.
        // This example checks if the flag value is a path.
        validator: (value) => {
          const isValid = existsSync(value);

          if (isValid) {
            return {
              isValid,
            };
          }

          return {
            isValid, error: {
              message: `Could not find the specified file relative to the current working directory. Make sure it exists.`,
            },
          };
        },

        // Optional completions function, see below at 'dynamicValue.completions'.
        // completions: () => {},
      },
    },
  ],

  // Optional sub commands, this is required if this command is `modifiers.isCosmetic`.
  subCommands: [
    // Minimal command definition
    {
      name: "list", shortDescription: "List all todo's."
    }
  ],

  // An optional executor. If a command does not have an executor, the executor of it's (recursive) parent is used.
  executor: cliExecutor,

  // Extra properties for 'modifiers.isWatchable' commands
  // Defaults to
  // { extensions: ["js", "json"], ignorePatterns: [".cache", "coverage", "node_modules"], }
  watchSettings: {
    // Specific extensions to watch for
    // Is optional
    extensions: [ "js", "json" ],

    // Specific patterns to filter out.
    // Use this if your program or another program writes files that you don't want this command to be restarted for.
    ignorePatterns: [ ".cache" ],
  },

  // Extra prperties for 'modifiers.isDynamic' commands
  dynamicValue: {
    // Called when parsing the command. May return a Promise.
    validator: (value) => {
      const isValid = [ "toggle", "add" ].includes(value);

      if (isValid) {
        return {
          isValid,
        }
      }

      // Full error message: "Invalid sub command 'xxx' for 'compas todo'. Allowed values are 'toggle' and 'add'.
      return {
        isValid, error: {
          message: "Allowed values are 'toggle' and 'add'.",
        }
      }
    },

    // Called for shell auto-complete, may return a promise.
    // Depending on the shell that is used, some features may or may not work.
    completions: () => {
      return {
        completions: [
          {
            // Get directory completions
            type: "directory",
          }, {
            // Get file completions
            type: "file",
          }, {
            // A direct completion for the user
            type: "completion", name: "toggle",
          }, {
            // A direct completion for the user
            type: "completion", name: "add",

            // optional
            description: "Add a new todo",
          }, {
            // Print message with specification and description
            type: "value", specification: "string",

            // Optional
            description: "A todo name",
          }
        ]
      }
    }
  },
};

/**
 * Is called when this command or a sub command is matched.
 *
 * @param {import("@compas/stdlib").Logger} logger
 * @param {import("@compas/cli").CliExecutorState} state
 * @returns {Promise<import("@compas/cli").CliResult>}
 */
async function cliExecutor(logger, state) {
  logger.info(state.command);
  logger.info(state.flags);

  return {
    exitStatus: "passed",
  }
}