{"record":{"id":"293d1b5d218daf99","repo":"mastra-ai/mastra","slug":"the-llm-api-key-option-can-only-be-used-with-the","errorCode":null,"errorMessage":"The --llm-api-key option can only be used with the default template","messagePattern":"The --llm-api-key option can only be used with the default template","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/create/command.ts","lineNumber":115,"sourceCode":"}\n\nexport function getCreateMode(options: Pick<NormalizedCreateOptions, 'empty' | 'template'>): CreateMode {\n  if (options.empty) return 'empty';\n  if (options.template !== undefined) return 'template';\n  return 'managed';\n}\n\nexport function validateCreateOptionConflicts(options: NormalizedCreateOptions): CreateMode {\n  if (options.empty && options.template !== undefined) {\n    throw new Error(`The --empty and --template options can't be used together`);\n  }\n\n  const mode = getCreateMode(options);\n  if (mode !== 'managed' && options.llmProvider !== undefined) {\n    throw new Error('The --llm option can only be used with the default template');\n  }\n  if (mode !== 'managed' && options.llmApiKey !== undefined) {\n    throw new Error('The --llm-api-key option can only be used with the default template');\n  }\n\n  return mode;\n}\n\nconst WINDOWS_RESERVED_BASENAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\\..*)?$/i;\nconst PROJECT_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;\n\nexport function validateProjectName(value: string): string {\n  const projectName = value.trim();\n\n  if (\n    projectName.length < 1 ||\n    projectName.length > 214 ||\n    path.isAbsolute(projectName) ||\n    projectName.includes('/') ||\n    projectName.includes('\\\\') ||\n    projectName === '.' ||","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/create/command.ts#L97-L133","documentation":"`validateCreateOptionConflicts` in packages/cli/src/commands/create/command.ts:115 throws when `--llm-api-key <key>` is passed with `--empty` or `--template`. The API key is only consumed by the managed default-template flow (it gets written into the adapted scaffold), so supplying it in other modes is a no-op the CLI rejects instead of silently ignoring.","triggerScenarios":"`mastra create --empty -k sk-...` or `mastra create -t <slug> -k sk-...` (or programmatic `{ empty/template, llmApiKey }`): mode !== 'managed' while llmApiKey is defined.","commonSituations":"Scripts that export an API key and always append `-k $MASTRA_KEY`; combining template scaffolding with credentials meant for the default flow; users hardcoding keys into CI commands for all create variants.","solutions":["Remove `-k/--llm-api-key` when using `--empty` or `--template`","Use the default flow if you want the key wired in: `mastra create my-app --llm openai --llm-api-key sk-...`","Prefer environment variables (e.g. OPENAI_API_KEY) in the generated project instead of passing keys via flags"],"exampleFix":"// before\nmastra create my-app --empty --llm-api-key sk-abc123\n// after\nmastra create my-app --empty","handlingStrategy":"validation","validationCode":"if ((opts.empty || opts.template !== undefined) && process.argv.some(a => a === '-k' || a === '--llm-api-key')) {\n  throw new Error('--llm-api-key only applies to the default template flow');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await create(opts);\n} catch (error) {\n  if (error instanceof Error && error.message.includes('--llm-api-key')) {\n    console.error('Remove -k/--llm-api-key or use the default flow');\n  } else throw error;\n}","preventionTips":["Never pass secrets via flags in scripts; use env vars in the generated project","Only emit -k when no --empty/--template flag is present","Audit CI templates that template-out the full create command"],"tags":["cli","input-validation","flag-conflict","api-key"],"backgroundTag":"mutually-exclusive-flags","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}