cli-module-new: add template for CLI module packages

Add a new `cli-module` template to the Backstage CLI that scaffolds
CLI module packages. This includes adding the `cli-module` role to the
template system, with proper naming conventions and prompts.

The generated package includes:
- A bin entry point for standalone execution
- An index.ts with createCliModule setup
- An example command using cleye
- Standard package.json with cli-module role

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor

.changeset/add-cli-module-template-support.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli-module-new': patch
+---
+
+Added support for the `cli-module` template role for scaffolding new CLI module packages.

.changeset/add-cli-module-template.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+Added a new `cli-module` template for creating CLI module packages.

packages/cli-module-new/src/lib/defaultTemplates.ts

@@ -23,6 +23,7 @@ export const defaultTemplates = [
   '@backstage/cli/templates/plugin-common-library',
   '@backstage/cli/templates/web-library',
   '@backstage/cli/templates/node-library',
+  '@backstage/cli/templates/cli-module',
   '@backstage/cli/templates/catalog-provider-module',
   '@backstage/cli/templates/scaffolder-backend-module',
 ];

packages/cli-module-new/src/lib/preparation/collectPortableTemplateInput.ts

@@ -160,6 +160,7 @@ export function getPromptsForRole(
     case 'web-library':
     case 'node-library':
     case 'common-library':
+    case 'cli-module':
       return [namePrompt()];
     case 'plugin-web-library':
     case 'plugin-node-library':

packages/cli-module-new/src/lib/preparation/resolvePackageParams.test.ts

@@ -37,6 +37,13 @@ describe.each([
       packagePath: 'packages/test',
     },
   ],
+  [
+    { role: 'cli-module', name: 'test' },
+    {
+      packageName: '@internal/cli-module-test',
+      packagePath: 'packages/cli-module-test',
+    },
+  ],
   [
     { role: 'plugin-web-library', pluginId: 'test' },
     {

packages/cli-module-new/src/lib/preparation/resolvePackageParams.ts

@@ -48,6 +48,8 @@ function getBaseNameForRole(
     case 'node-library':
     case 'common-library':
       return roleParams.name;
+    case 'cli-module':
+      return `cli-module-${roleParams.name}`;
     case 'plugin-web-library':
       return `${roleParams.pluginId}-react`;
     case 'plugin-node-library':

packages/cli-module-new/src/lib/types.ts

@@ -50,6 +50,7 @@ export const TEMPLATE_ROLES = [
   'web-library',
   'node-library',
   'common-library',
+  'cli-module',
   'plugin-web-library',
   'plugin-node-library',
   'plugin-common-library',
@@ -80,7 +81,7 @@ export type PortableTemplateParams = {
 
 export type PortableTemplateInputRoleParams =
   | {
-      role: 'web-library' | 'node-library' | 'common-library';
+      role: 'web-library' | 'node-library' | 'common-library' | 'cli-module';
       name: string;
     }
   | {

packages/cli/templates/cli-module/.eslintrc.js.hbs

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

packages/cli/templates/cli-module/README.md.hbs

@@ -0,0 +1,5 @@
+# {{packageName}}
+
+A CLI module that adds commands to the Backstage CLI.
+
+_This package was created through the Backstage CLI_

packages/cli/templates/cli-module/bin/{{binName}}

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/*
+ * Copyright 2025 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const path = require('node:path');
+
+/* eslint-disable-next-line no-restricted-syntax */
+const isLocal = require('node:fs').existsSync(
+  path.resolve(__dirname, '../src'),
+);
+
+if (isLocal) {
+  require('@backstage/cli-node/config/nodeTransform.cjs');
+}
+
+const { runCliModule } = require('@backstage/cli-node');
+const cliModule = require(isLocal ? '../src/index' : '..').default;
+const pkg = require('../package.json');
+runCliModule({ module: cliModule, name: pkg.name, version: pkg.version });

packages/cli/templates/cli-module/package.json.hbs

@@ -0,0 +1,35 @@
+{
+  "name": "{{packageName}}",
+  "description": "CLI module for Backstage CLI",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "cli-module"
+  },
+  "scripts": {
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "dependencies": {
+    "@backstage/cli-common": "{{versionQuery '@backstage/cli-common'}}",
+    "@backstage/cli-node": "{{versionQuery '@backstage/cli-node'}}",
+    "cleye": "^2.3.0"
+  },
+  "devDependencies": {
+    "@backstage/cli": "{{versionQuery '@backstage/cli'}}"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "bin": "bin/{{binName}}"
+}

packages/cli/templates/cli-module/portable-template.yaml

@@ -0,0 +1,5 @@
+name: cli-module
+role: cli-module
+description: A CLI module that adds commands to the Backstage CLI
+values:
+  binName: 'backstage-cli-module-{{ name }}'

packages/cli/templates/cli-module/src/commands/example.ts

@@ -0,0 +1,18 @@
+import { cli } from 'cleye';
+import type { CliCommandContext } from '@backstage/cli-node';
+
+export default async ({ args, info }: CliCommandContext) => {
+  const { flags } = cli(
+    {
+      help: info,
+      booleanFlagNegation: true,
+      flags: {},
+    },
+    undefined,
+    args,
+  );
+
+  void flags;
+
+  console.log('Hello from example command!');
+};

packages/cli/templates/cli-module/src/index.ts.hbs

@@ -0,0 +1,20 @@
+/***/
+/**
+ * CLI module for the Backstage CLI.
+ *
+ * @packageDocumentation
+ */
+
+import { createCliModule } from '@backstage/cli-node';
+import packageJson from '../package.json';
+
+export default createCliModule({
+  packageJson,
+  init: async reg => {
+    reg.addCommand({
+      path: ['example'],
+      description: 'An example command',
+      execute: { loader: () => import('./commands/example') },
+    });
+  },
+});