@kubb/cli 5.0.0-beta.1 → 5.0.0-beta.10

package/package.json

@@ -1,20 +1,15 @@
 {
   "name": "@kubb/cli",
-  "version": "5.0.0-beta.1",
-  "description": "Command-line interface for Kubb, enabling easy generation of TypeScript, React-Query, Zod, and other code from OpenAPI specifications.",
+  "version": "5.0.0-beta.10",
+  "description": "Official CLI for Kubb. Run kubb generate, kubb init, kubb validate, kubb mcp, and kubb agent to manage the full code generation lifecycle from OpenAPI/Swagger specs.",
   "keywords": [
     "cli",
     "code-generator",
     "codegen",
-    "command-line",
-    "command-line-tool",
     "kubb",
-    "oas",
     "openapi",
-    "plugins",
     "sdk-generator",
     "swagger",
-    "terminal",
     "typescript"
   ],
   "license": "MIT",
@@ -55,17 +50,30 @@
     "@clack/prompts": "^1.3.0",
     "chokidar": "^5.0.0",
     "cosmiconfig": "^9.0.1",
+    "jiti": "^2.7.0",
     "tinyexec": "^1.1.2",
-    "unrun": "^0.2.37",
-    "@kubb/adapter-oas": "5.0.0-beta.1",
-    "@kubb/core": "5.0.0-beta.1"
+    "@kubb/core": "5.0.0-beta.10"
   },
   "devDependencies": {
-    "@internals/utils": "0.0.0"
+    "@internals/shared": "0.0.0",
+    "@internals/utils": "0.0.0",
+    "@kubb/adapter-oas": "5.0.0-beta.10"
   },
-  "optionalDependencies": {
-    "@kubb/agent": "5.0.0-beta.1",
-    "@kubb/mcp": "5.0.0-beta.1"
+  "peerDependencies": {
+    "@kubb/adapter-oas": "5.0.0-beta.10",
+    "@kubb/agent": "5.0.0-beta.10",
+    "@kubb/mcp": "5.0.0-beta.10"
+  },
+  "peerDependenciesMeta": {
+    "@kubb/adapter-oas": {
+      "optional": true
+    },
+    "@kubb/agent": {
+      "optional": true
+    },
+    "@kubb/mcp": {
+      "optional": true
+    }
   },
   "size-limit": [
     {

package/src/commands/agent/start.ts

@@ -4,26 +4,29 @@ import { agentDefaults } from '../../constants.ts'
 
 export const command = defineCommand({
   name: 'start',
-  description: 'Start the Agent server',
+  description:
+    'Start the Kubb Agent HTTP server. Exposes a REST API that accepts a kubb.config.ts patch and returns generated code as a stream. Use --allow-write to also write files to disk.',
+  examples: ['kubb agent start', 'kubb agent start --port 4000', 'kubb agent start --allow-write', 'kubb agent start --config ./kubb.config.ts --allow-all'],
   options: {
     config: {
       type: 'string',
-      description: 'Path to the Kubb config',
+      description: 'Path to the Kubb config file',
       short: 'c',
     },
     port: {
       type: 'string',
-      description: `Port for the server (default: ${agentDefaults.port})`,
+      description: 'Port the HTTP server listens on',
       short: 'p',
+      default: agentDefaults.port,
     },
     host: {
       type: 'string',
-      description: 'Host for the server',
+      description: 'Hostname the HTTP server binds to',
       default: agentDefaults.host,
     },
     'allow-write': {
       type: 'boolean',
-      description: 'Allow writing generated files to the filesystem. When not set, no files are written and the config patch is not persisted.',
+      description: 'Write generated files to the filesystem. When omitted, output is streamed only and no files are written.',
       default: false,
     },
     'allow-all': {
@@ -33,9 +36,9 @@ export const command = defineCommand({
     },
   },
   async run({ values }) {
-    const { runAgentStart } = await import('../../runners/agent.ts')
+    const { run } = await import('../../runners/agent/run.ts')
 
-    await runAgentStart({
+    await run({
       port: values.port !== undefined ? values.port : undefined,
       host: values.host,
       configPath: values.config,

package/src/commands/agent.ts

@@ -3,6 +3,8 @@ import { command as startCommand } from './agent/start.ts'
 
 export const command = defineCommand({
   name: 'agent',
-  description: 'Manage the Kubb Agent server',
+  description:
+    'Manage the Kubb Agent — an HTTP server that lets AI agents trigger code generation programmatically via a REST API. Useful when an AI workflow needs to generate code without direct CLI access.',
+  examples: ['kubb agent start', 'kubb agent start --port 4000 --allow-write', 'kubb agent start --config ./kubb.config.ts --allow-all'],
   subCommands: [startCommand],
 })

package/src/commands/generate.ts

@@ -2,8 +2,10 @@ import { defineCommand } from '@internals/utils'
 
 export const command = defineCommand({
   name: 'generate',
-  description: "[input] Generate files based on a 'kubb.config.ts' file",
+  description:
+    'Generate TypeScript types, API clients, React Query hooks, Zod schemas, and more from an OpenAPI specification. Reads kubb.config.ts by default. Pass an OpenAPI file path as the first argument to override the input without editing the config.',
   arguments: ['[input]'],
+  examples: ['kubb generate', 'kubb generate ./openapi.yaml', 'kubb generate --config kubb.config.ts', 'kubb generate --watch'],
   options: {
     config: {
       type: 'string',
@@ -45,9 +47,9 @@ export const command = defineCommand({
   },
   async run({ values, positionals }) {
     const logLevel = values.debug ? 'debug' : values.verbose ? 'verbose' : values.silent ? 'silent' : values.logLevel
-    const { runGenerateCommand } = await import('../runners/generate.ts')
+    const { run } = await import('../runners/generate/run.ts')
 
-    await runGenerateCommand({
+    await run({
       input: positionals[0],
       configPath: values.config,
       logLevel,

package/src/commands/init.ts

@@ -3,7 +3,14 @@ import { version } from '../../package.json'
 
 export const command = defineCommand({
   name: 'init',
-  description: 'Initialize a new Kubb project with interactive setup',
+  description:
+    'Scaffold a kubb.config.ts and install plugins for code generation from an OpenAPI spec. Run without flags for interactive setup, or pass --input, --output, and --plugins to skip the prompts.',
+  examples: [
+    'kubb init',
+    'kubb init --yes',
+    'kubb init --input ./openapi.yaml --output ./src/gen --plugins plugin-ts,plugin-zod',
+    'kubb init --plugins plugin-ts,plugin-client,plugin-react-query',
+  ],
   options: {
     yes: {
       type: 'boolean',
@@ -11,10 +18,34 @@ export const command = defineCommand({
       short: 'y',
       default: false,
     },
+    input: {
+      type: 'string',
+      description: 'Path to the OpenAPI specification',
+      short: 'i',
+      hint: 'path',
+    },
+    output: {
+      type: 'string',
+      description: 'Output directory for generated files',
+      short: 'o',
+      hint: 'path',
+    },
+    plugins: {
+      type: 'string',
+      description:
+        'Comma-separated list of plugins to use (plugin-ts, plugin-client, plugin-react-query, plugin-vue-query, plugin-zod, plugin-faker, plugin-msw, plugin-cypress, plugin-mcp, plugin-redoc)',
+      hint: 'plugin-ts,plugin-zod,...',
+    },
   },
   async run({ values }) {
-    const { runInit } = await import('../runners/init.ts')
+    const { run } = await import('../runners/init/run.ts')
 
-    await runInit({ yes: values.yes, version })
+    await run({
+      yes: values.yes,
+      version,
+      input: values.input,
+      output: values.output,
+      plugins: values.plugins,
+    })
   },
 })

package/src/commands/mcp.ts

@@ -3,10 +3,34 @@ import { version } from '../../package.json'
 
 export const command = defineCommand({
   name: 'mcp',
-  description: 'Start the server to enable the MCP client to interact with the LLM.',
-  async run() {
-    const { runMcp } = await import('../runners/mcp.ts')
+  description:
+    'Start a Model Context Protocol (MCP) server that exposes Kubb code generation as tools for AI assistants. Once running, configure your AI client (Claude, Cursor, Windsurf, etc.) to connect to it — the assistant can then call kubb generate directly without leaving the chat.',
+  examples: [
+    'kubb mcp',
+    'kubb mcp --port 3001',
+    '# Then add to your MCP client config:',
+    '# { "mcpServers": { "kubb": { "command": "npx", "args": ["kubb", "mcp"] } } }',
+  ],
+  options: {
+    port: {
+      type: 'string',
+      short: 'p',
+      description: 'Port for HTTP MCP server (omit for stdio)',
+      hint: 'number',
+    },
+    host: {
+      type: 'string',
+      description: 'Hostname to bind to (HTTP mode only)',
+      default: 'localhost',
+    },
+  },
+  async run({ values }) {
+    const { run } = await import('../runners/mcp/run.ts')
 
-    await runMcp({ version })
+    await run({
+      version,
+      port: values.port,
+      host: values.host,
+    })
   },
 })

package/src/commands/validate.ts

@@ -3,18 +3,20 @@ import { version } from '../../package.json'
 
 export const command = defineCommand({
   name: 'validate',
-  description: 'Validate a Swagger/OpenAPI file',
+  description:
+    'Parse and validate an OpenAPI/Swagger file for structural correctness. Reports schema errors, missing required fields, and malformed references. Use this before running generate to catch spec issues early.',
+  examples: ['kubb validate --input ./openapi.yaml', 'kubb validate --input https://petstore3.swagger.io/api/v3/openapi.json'],
   options: {
     input: {
       type: 'string',
-      description: 'Path to Swagger/OpenAPI file',
+      description: 'Path or URL to the OpenAPI/Swagger file to validate',
       short: 'i',
       required: true,
     },
   },
   async run({ values }) {
-    const { runValidate } = await import('../runners/validate.ts')
+    const { run } = await import('../runners/validate/run.ts')
 
-    await runValidate({ input: values.input, version })
+    await run({ input: values.input, version })
   },
 })

package/src/constants.ts

@@ -1,9 +1,4 @@
-/**
- * Default filename for the Kubb configuration file.
- *
- * Used by the `init` command when scaffolding new projects and by the `agent` default config.
- */
-export const KUBB_CONFIG_FILENAME = 'kubb.config.ts' as const
+import { KUBB_CONFIG_FILENAME } from '@internals/shared'
 
 /**
  * NPM registry endpoint used to check for @kubb/cli updates.
@@ -45,60 +40,9 @@ export const agentDefaults = {
   host: 'localhost',
   configFile: KUBB_CONFIG_FILENAME,
   retryTimeout: '30000',
-  studioUrl: 'https://studio.kubb.dev',
+  studioUrl: 'https://kubb.studio',
   /**
    * Relative path from the @kubb/agent package root to the server entry.
    */
   serverEntryPath: '.output/server/index.mjs',
 } as const
-
-/**
- * Default values used during interactive `init` scaffolding.
- */
-export const initDefaults = {
-  inputPath: './openapi.yaml',
-  outputPath: './src/gen',
-  plugins: ['plugin-ts'],
-} as const
-
-/**
- * Maps each plugin value to the default config snippet inserted by `init`.
- * The `satisfies` constraint ensures all values remain plain strings while
- * `as const` keeps the object deeply immutable.
- */
-export const pluginDefaultConfigs = {
-  'plugin-ts': `pluginTs({
-      output: { path: 'models' },
-    })`,
-  'plugin-client': `pluginClient({
-      output: { path: 'clients' },
-    })`,
-  'plugin-react-query': `pluginReactQuery({
-      output: { path: 'hooks' },
-    })`,
-  'plugin-vue-query': `pluginVueQuery({
-      output: { path: 'hooks' },
-    })`,
-  'plugin-zod': `pluginZod({
-      output: { path: 'zod' },
-    })`,
-  'plugin-faker': `pluginFaker({
-      output: { path: 'mocks' },
-    })`,
-  'plugin-msw': `pluginMsw({
-      output: { path: 'msw' },
-    })`,
-  'plugin-cypress': `pluginCypress({
-      output: { path: 'cypress' },
-    })`,
-  'plugin-mcp': `pluginMcp({
-      output: { path: 'mcp' },
-    })`,
-  'plugin-redoc': `pluginRedoc({
-      output: { path: 'redoc' },
-    })`,
-} as const satisfies Record<string, string>
-
-/**
- * Color palette used by randomCliColor() for deterministic plugin name coloring.
- */

package/src/index.ts

@@ -1,9 +1,8 @@
 import { styleText } from 'node:util'
-import { createCLI } from '@internals/utils'
+import { createCLI, isFlag } from '@internals/utils'
 import { version } from '../package.json'
 import { QUIET_FLAGS } from './constants.ts'
-import { isFlag } from './utils/flags.ts'
-import { isTelemetryDisabled } from './utils/telemetry.ts'
+import { isTelemetryDisabled } from './telemetry.ts'
 
 const cli = createCLI()
 
@@ -11,14 +10,17 @@ function shouldShowTelemetryNotice(argv: Array<string>): boolean {
   if (isTelemetryDisabled()) {
     return false
   }
+
   // Skip when the user is just asking for help or version info
   if (argv.some((arg) => isFlag(QUIET_FLAGS, arg))) {
     return false
   }
+
   // Skip in non-interactive / scripting contexts
   if (!process.stdout.isTTY) {
     return false
   }
+
   return true
 }
 

package/src/loggers/clackLogger.ts

@@ -4,10 +4,27 @@ import { styleText } from 'node:util'
 import * as clack from '@clack/prompts'
 import { formatMs, formatMsWithColor, getIntro, toCause } from '@internals/utils'
 import { defineLogger, logLevel as logLevelMap } from '@kubb/core'
-import { getSummary } from '../utils/getSummary.ts'
-import { runHook } from '../utils/runHook.ts'
-import { ClackWritable } from '../utils/Writables.ts'
+import { getSummary } from './utils.ts'
 import { buildProgressLine, formatCommandWithArgs, formatMessage } from './utils.ts'
+import { Writable } from 'node:stream'
+import type { WritableOptions } from 'node:stream'
+
+/**
+ * Node.js `Writable` stream that forwards each chunk to a clack `taskLog` message.
+ * Used to pipe hook subprocess output into the clack task log UI.
+ */
+class ClackWritable extends Writable {
+  taskLog: ReturnType<typeof clack.taskLog>
+  constructor(taskLog: ReturnType<typeof clack.taskLog>, opts?: WritableOptions) {
+    super(opts)
+
+    this.taskLog = taskLog
+  }
+  _write(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    this.taskLog.message(`${styleText('dim', chunk.toString())}`)
+    callback()
+  }
+}
 
 /**
  * TTY logger with beautiful UI and progress indicators for local development.
@@ -364,51 +381,15 @@ Run \`npm install -g @kubb/cli\` to update`,
       clack.outro(text)
     })
 
-    context.on('kubb:hook:start', async ({ id, command, args }) => {
-      const commandWithArgs = formatCommandWithArgs(command, args)
-      const text = getMessage(`Hook ${styleText('dim', commandWithArgs)} started`)
-
-      // Skip hook execution if no id is provided (e.g., during benchmarks or tests)
-      if (!id) {
-        return
-      }
-
+    context.on('kubb:hook:start', ({ command, args }) => {
       if (logLevel <= logLevelMap.silent) {
-        await runHook({
-          id,
-          command,
-          args,
-          commandWithArgs,
-          context,
-          sink: {
-            onStderr: (s) => console.error(s),
-            onStdout: (s) => console.log(s),
-          },
-        })
         return
       }
 
-      clack.intro(text)
-
-      const logger = clack.taskLog({
-        title: getMessage(['Executing hook', logLevel >= logLevelMap.info ? styleText('dim', commandWithArgs) : undefined].filter(Boolean).join(' ')),
-      })
-
-      const writable = new ClackWritable(logger)
+      const commandWithArgs = formatCommandWithArgs(command, args)
+      const text = getMessage(`Hook ${styleText('dim', commandWithArgs)} started`)
 
-      await runHook({
-        id,
-        command,
-        args,
-        commandWithArgs,
-        context,
-        stream: true,
-        sink: {
-          onLine: (line) => writable.write(line),
-          onStderr: (s) => logger.error(s),
-          onStdout: (s) => logger.message(s),
-        },
-      })
+      clack.intro(text)
     })
 
     context.on('kubb:hook:end', ({ command, args }) => {
@@ -454,5 +435,26 @@ Run \`npm install -g @kubb/cli\` to update`,
     context.on('kubb:lifecycle:end', () => {
       reset()
     })
+
+    return (commandWithArgs: string) => {
+      if (logLevel <= logLevelMap.silent) {
+        return {
+          onStdout: (s: string) => console.log(s),
+          onStderr: (s: string) => console.error(s),
+        }
+      }
+
+      const logger = clack.taskLog({
+        title: getMessage(['Executing hook', logLevel >= logLevelMap.info ? styleText('dim', commandWithArgs) : undefined].filter(Boolean).join(' ')),
+      })
+      const writable = new ClackWritable(logger)
+
+      return {
+        stream: true,
+        onLine: (line: string) => writable.write(line),
+        onStdout: (s: string) => logger.message(s),
+        onStderr: (s: string) => logger.error(s),
+      }
+    }
   },
 })

package/src/loggers/fileSystemLogger.ts

@@ -4,14 +4,24 @@ import { formatMs, write } from '@internals/utils'
 import { defineLogger } from '@kubb/core'
 
 type CachedEvent = {
+  /**
+   * Timestamp when this event was captured, used to derive the log filename.
+   */
   date: Date
+  /**
+   * Accumulated log lines for this event.
+   */
   logs: string[]
+  /**
+   * Optional override for the output filename inside `.kubb/`. When omitted, the filename is derived from `date`.
+   */
   fileName?: string
 }
 
 /**
  * FileSystem logger that captures debug events and writes them to `.kubb` directory files.
- * Note: Logs write on `lifecycle:end` or process exit. Cached logs may be lost if the process crashes before these events.
+ *
+ * @note Logs are written on `kubb:lifecycle:end` or process exit. Cached logs may be lost if the process crashes before either event.
  */
 export const fileSystemLogger = defineLogger({
   name: 'filesystem',
@@ -42,13 +52,15 @@ export const fileSystemLogger = defineLogger({
         }
 
         if (log.logs.length > 0) {
-          const timestamp = log.date.toLocaleString()
-          files[pathName].push(`[${timestamp}]\n${log.logs.join('\n')}`)
+          const prefix = `[${log.date.toLocaleString()}] `
+          const indent = ' '.repeat(prefix.length)
+          const [first, ...rest] = log.logs
+          files[pathName].push([prefix + first, ...rest.map((line) => indent + line)].join('\n'))
         }
       }
 
       for (const [fileName, logs] of Object.entries(files)) {
-        await write(fileName, logs.join('\n\n'))
+        await write(fileName, logs.join('\n'))
       }
 
       return Object.keys(files)
@@ -57,21 +69,21 @@ export const fileSystemLogger = defineLogger({
     context.on('kubb:info', ({ message, info }) => {
       state.cachedLogs.add({
         date: new Date(),
-        logs: [`ℹ ${message} ${info}`],
+        logs: [`ℹ ${[message, info].filter(Boolean).join(' ')}`],
       })
     })
 
     context.on('kubb:success', ({ message, info }) => {
       state.cachedLogs.add({
         date: new Date(),
-        logs: [`✓ ${message} ${info}`],
+        logs: [`✓ ${[message, info].filter(Boolean).join(' ')}`],
       })
     })
 
     context.on('kubb:warn', ({ message, info }) => {
       state.cachedLogs.add({
         date: new Date(),
-        logs: [`⚠ ${message} ${info}`],
+        logs: [`⚠ ${[message, info].filter(Boolean).join(' ')}`],
       })
     })
 
@@ -82,17 +94,18 @@ export const fileSystemLogger = defineLogger({
       })
     })
 
-    context.on('kubb:debug', (message) => {
+    context.on('kubb:debug', ({ date, fileName, logs }) => {
       state.cachedLogs.add({
-        date: new Date(),
-        logs: message.logs,
+        date,
+        fileName,
+        logs,
       })
     })
 
     context.on('kubb:plugin:start', ({ plugin }) => {
       state.cachedLogs.add({
         date: new Date(),
-        logs: [`Generating ${plugin.name}`],
+        logs: [`► Generating ${plugin.name}`],
       })
     })
 
@@ -101,14 +114,14 @@ export const fileSystemLogger = defineLogger({
 
       state.cachedLogs.add({
         date: new Date(),
-        logs: [success ? `${plugin.name} completed in ${durationStr}` : `${plugin.name} failed in ${durationStr}`],
+        logs: [success ? `✓ ${plugin.name} completed in ${durationStr}` : `✗ ${plugin.name} failed in ${durationStr}`],
       })
     })
 
     context.on('kubb:files:processing:start', ({ files }) => {
       state.cachedLogs.add({
         date: new Date(),
-        logs: [`Start ${files.length} writing:`, ...files.map((file) => file.path)],
+        logs: [`► Writing ${files.length} files`, ...files.map((file) => `  ${file.path}`)],
       })
     })
 

package/src/loggers/githubActionsLogger.ts

@@ -1,7 +1,6 @@
 import { styleText } from 'node:util'
 import { formatHrtime, formatMs, formatMsWithColor, toCause } from '@internals/utils'
 import { type Config, defineLogger, logLevel as logLevelMap } from '@kubb/core'
-import { runHook } from '../utils/runHook.ts'
 import { buildProgressLine, formatCommandWithArgs, formatMessage } from './utils.ts'
 
 /**
@@ -307,34 +306,18 @@ export const githubActionsLogger = defineLogger({
       }
     })
 
-    context.on('kubb:hook:start', async ({ id, command, args }) => {
+    context.on('kubb:hook:start', ({ command, args }) => {
+      if (logLevel <= logLevelMap.silent) {
+        return
+      }
+
       const commandWithArgs = formatCommandWithArgs(command, args)
       const text = getMessage(`Hook ${styleText('dim', commandWithArgs)} started`)
 
-      if (logLevel > logLevelMap.silent) {
-        if (state.currentConfigs.length === 1) {
-          openGroup(`Hook ${commandWithArgs}`)
-        }
-        console.log(text)
-      }
-
-      // Skip hook execution if no id is provided (e.g., during benchmarks or tests)
-      if (!id) {
-        return
+      if (state.currentConfigs.length === 1) {
+        openGroup(`Hook ${commandWithArgs}`)
       }
-
-      await runHook({
-        id,
-        command,
-        args,
-        commandWithArgs,
-        context,
-        sink: {
-          // GHA formats errors with the ::error:: annotation
-          onStdout: logLevel > logLevelMap.silent ? (s) => console.log(s) : undefined,
-          onStderr: logLevel > logLevelMap.silent ? (s) => console.error(`::error::${s}`) : undefined,
-        },
-      })
+      console.log(text)
     })
 
     context.on('kubb:hook:end', ({ command, args }) => {
@@ -375,5 +358,10 @@ export const githubActionsLogger = defineLogger({
     context.on('kubb:lifecycle:end', () => {
       reset()
     })
+
+    return (_commandWithArgs: string) => ({
+      onStdout: logLevel > logLevelMap.silent ? (s: string) => console.log(s) : undefined,
+      onStderr: logLevel > logLevelMap.silent ? (s: string) => console.error(`::error::${s}`) : undefined,
+    })
   },
 })