Invalid plugin name "${name}". Plugin names must start with

Error message

Invalid plugin name "${name}". Plugin names must start with a lowercase letter and contain only lowercase letters, digits, and hyphens.

What it means

createPluginScaffold validates the requested plugin name against /^[a-z][a-z0-9-]*$/ before creating anything. Names must start with a lowercase letter and contain only lowercase letters, digits, and hyphens; anything else (uppercase, underscores, leading digits or hyphens, spaces) throws this Error. The constraint keeps plugin names valid as npm-style package names and directory names.

Source

Thrown at src/plugin-scaffold.ts:38

  /** Directory to create the plugin in. Defaults to `./<name>` */
  dir?: string;
  /** Plugin description */
  description?: string;
}

export interface ScaffoldResult {
  name: string;
  dir: string;
  files: string[];
}

/**
 * Create a new plugin scaffold directory.
 */
export function createPluginScaffold(name: string, opts: ScaffoldOptions = {}): ScaffoldResult {
  // Validate name
  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
    throw new Error(
      `Invalid plugin name "${name}". ` +
      `Plugin names must start with a lowercase letter and contain only lowercase letters, digits, and hyphens.`
    );
  }

  const targetDir = opts.dir
    ? path.resolve(opts.dir)
    : path.resolve(name);

  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
    throw new Error(`Directory "${targetDir}" already exists and is not empty.`);
  }

  fs.mkdirSync(targetDir, { recursive: true });

  const files: string[] = [];

  // opencli-plugin.json

View on GitHub (pinned to 49907e53dc)

Solutions

Rewrite the name in lowercase, replacing underscores with hyphens (e.g. 'My_Plugin' -> 'my-plugin')
Strip leading digits or hyphens so it starts with a lowercase letter
Pre-validate/normalize user-supplied names with the same regex before calling createPluginScaffold

Example fix

// before
createPluginScaffold('My_CoolPlugin');
// after
createPluginScaffold('my-coolplugin');

Defensive patterns

Strategy: validation

Validate before calling

const PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
if (!PLUGIN_NAME_RE.test(name)) throw new Error(`invalid plugin name: ${name}`);

Type guard

function isValidPluginName(name: string): boolean {
  return /^[a-z][a-z0-9-]*$/.test(name);
}

Try / catch

try {
  createPluginScaffold(name, opts);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Invalid plugin name')) {
    console.error(`"${name}" is invalid — use lowercase letters, digits, hyphens; start with a letter.`);
  } else throw e;
}

Prevention

Normalize names with toLowerCase().replace(/_/g, '-') before scaffolding
Keep a shared isValidPluginName helper and run it on all user input
Never pass raw CLI args or CamelCase project names straight into the scaffold
Mirror npm package-name rules when choosing plugin names

When it happens

Trigger: Calling createPluginScaffold with names like 'MyPlugin', 'my_plugin', '1st-plugin', '-foo', or 'my plugin'. Also triggered when the name comes from user input or a template variable that has not been normalized.

Common situations: Developer passes a CamelCase project name out of habit, uses underscores because other tools allow them, or interpolates an unvalidated CLI argument into the scaffold call.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/64581525698467d6. Report an issue: GitHub.