incur 0.3.4 → 0.3.6

package/src/Cli.ts

@@ -1,13 +1,19 @@
+import * as fs from 'node:fs/promises'
+import * as os from 'node:os'
+import * as path from 'node:path'
 import { estimateTokenCount, sliceByTokens } from 'tokenx'
 import type { z } from 'zod'
 
 import * as Completions from './Completions.js'
 import type { FieldError } from './Errors.js'
-import { IncurError, ValidationError } from './Errors.js'
+import { IncurError, ParseError, ValidationError } from './Errors.js'
 import * as Fetch from './Fetch.js'
 import * as Filter from './Filter.js'
 import * as Formatter from './Formatter.js'
 import * as Help from './Help.js'
+import { builtinCommands, type CommandMeta, type Shell, shells } from './internal/command.js'
+import * as Command from './internal/command.js'
+import { isRecord } from './internal/helpers.js'
 import { detectRunner } from './internal/pm.js'
 import type { OneOf } from './internal/types.js'
 import * as Mcp from './Mcp.js'
@@ -257,10 +263,13 @@ export function create(
     async fetch(req: Request) {
       if (pending.length > 0) await Promise.all(pending)
       return fetchImpl(name, commands, req, {
+        envSchema: def.env,
         mcpHandler,
         middlewares,
+        name,
         rootCommand: rootDef,
         vars: def.vars,
+        version: def.version,
       })
     },
 
@@ -269,6 +278,7 @@ export function create(
       return serveImpl(name, commands, argv, {
         ...serveOptions,
         aliases: def.aliases,
+        config: def.config,
         description: def.description,
         envSchema: def.env,
         format: def.format,
@@ -290,6 +300,8 @@ export function create(
   }
 
   if (rootDef) toRootDefinition.set(cli as unknown as Root, rootDef)
+  if (def.options) toRootOptions.set(cli, def.options)
+  if (def.config !== undefined) toConfigEnabled.set(cli, true)
   if (def.outputPolicy) toOutputPolicy.set(cli, def.outputPolicy)
   toMiddlewares.set(cli, middlewares)
   toCommands.set(cli, commands)
@@ -313,6 +325,24 @@ export declare namespace create {
     aliases?: string[] | undefined
     /** Zod schema for positional arguments. */
     args?: args | undefined
+    /** Enable config-file defaults for command options. */
+    config?:
+      | {
+          /** Global flag name for specifying a config file path (e.g. `'config'` → `--config <path>`). Omit to auto-load only, with no CLI flag. */
+          flag?: string | undefined
+          /** Ordered list of file paths to search. First existing file wins. Supports `~` for home dir. Defaults to `['<cli>.json']` relative to cwd. */
+          files?: string[] | undefined
+          /** Custom config loader. Receives the resolved file path (or `undefined` if no file was found). Returns the parsed config tree, or `undefined` for no defaults. When omitted, the framework reads and parses JSON. */
+          loader?:
+            | ((
+                path: string | undefined,
+              ) =>
+                | Record<string, unknown>
+                | undefined
+                | Promise<Record<string, unknown> | undefined>)
+            | undefined
+        }
+      | undefined
     /** A short description of what the CLI does. */
     description?: string | undefined
     /** Zod schema for environment variables. Keys are the variable names (e.g. `NPM_TOKEN`). */
@@ -422,6 +452,24 @@ async function serveImpl(
 ) {
   const stdout = options.stdout ?? ((s: string) => process.stdout.write(s))
   const exit = options.exit ?? ((code: number) => process.exit(code))
+  const human = process.stdout.isTTY === true
+  const configEnabled = options.config !== undefined
+  const configFlag = options.config?.flag
+
+  function writeln(s: string) {
+    stdout(s.endsWith('\n') ? s : `${s}\n`)
+  }
+
+  let builtinFlags: ReturnType<typeof extractBuiltinFlags>
+  try {
+    builtinFlags = extractBuiltinFlags(argv, { configFlag })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (human) writeln(formatHumanError({ code: 'UNKNOWN', message }))
+    else writeln(Formatter.format({ code: 'UNKNOWN', message }, 'toon'))
+    exit(1)
+    return
+  }
 
   const {
     verbose,
@@ -437,17 +485,24 @@ async function serveImpl(
     help,
     version,
     schema,
+    configPath,
+    configDisabled,
     rest: filtered,
-  } = extractBuiltinFlags(argv)
+  } = builtinFlags
 
   // --mcp: start as MCP stdio server
   if (mcpFlag) {
-    await Mcp.serve(name, options.version ?? '0.0.0', commands)
+    await Mcp.serve(name, options.version ?? '0.0.0', commands, {
+      middlewares: options.middlewares,
+      env: options.envSchema,
+      vars: options.vars,
+      version: options.version,
+    })
     return
   }
 
   // COMPLETE: dynamic shell completions (called by shell hook at tab-press)
-  const completeShell = process.env.COMPLETE as Completions.Shell | undefined
+  const completeShell = process.env.COMPLETE as Shell | undefined
   if (completeShell) {
     // Remove separator `--` from argv
     const sepIdx = argv.indexOf('--')
@@ -459,19 +514,32 @@ async function serveImpl(
     } else {
       const index = Number(process.env._COMPLETE_INDEX ?? words.length - 1)
       const candidates = Completions.complete(commands, options.rootCommand, words, index)
+      // Add built-in commands (completions, mcp, skills) to completions
+      const current = words[index] ?? ''
+      const nonFlags = words.slice(0, index).filter((w) => !w.startsWith('-'))
+      if (nonFlags.length <= 1) {
+        for (const b of builtinCommands) {
+          if (b.name.startsWith(current) && !candidates.some((c) => c.value === b.name))
+            candidates.push({
+              value: b.name,
+              description: b.description,
+              ...(b.subcommands ? { noSpace: true } : undefined),
+            })
+        }
+      } else if (nonFlags.length === 2) {
+        const parent = nonFlags[nonFlags.length - 1]
+        const builtin = builtinCommands.find((b) => b.name === parent && b.subcommands)
+        if (builtin?.subcommands)
+          for (const sub of builtin.subcommands)
+            if (sub.name.startsWith(current))
+              candidates.push({ value: sub.name, description: sub.description })
+      }
       const out = Completions.format(completeShell, candidates)
       if (out) stdout(out)
     }
     return
   }
 
-  // Human mode: stdout is a TTY.
-  const human = process.stdout.isTTY === true
-
-  function writeln(s: string) {
-    stdout(s.endsWith('\n') ? s : `${s}\n`)
-  }
-
   // Skills staleness check (skip for built-in commands)
   if (!llms && !llmsFull && !schema && !help && !version) {
     const isSkillsAdd =
@@ -544,73 +612,48 @@ async function serveImpl(
     // not a completions invocation
     return -1
   })()
+  // TODO: refactor built-in command handlers (completions, skills, mcp) into a generic dispatch loop on `builtinCommands`
   if (completionsIdx !== -1 && filtered[completionsIdx] === 'completions') {
-    if (help) {
+    const shell = filtered[completionsIdx + 1]
+    if (help || !shell) {
+      const b = builtinCommands.find((c) => c.name === 'completions')!
       writeln(
-        [
-          `${name} completions — Generate shell completion script`,
-          '',
-          `Usage: ${name} completions <shell>`,
-          '',
-          'Shells:',
-          '  bash',
-          '  fish',
-          '  nushell',
-          '  zsh',
-          '',
-          'Setup:',
-          ...(() => {
-            const rows = [
-              ['bash', `eval "$(${name} completions bash)"`, '# add to ~/.bashrc'],
-              ['zsh', `eval "$(${name} completions zsh)"`, '# add to ~/.zshrc'],
-              ['fish', `${name} completions fish | source`, '# add to ~/.config/fish/config.fish'],
-              ['nushell', `see \`${name} completions nushell\``, '# add to config.nu'],
-            ]
-            const shellW = Math.max(...rows.map((r) => r[0]!.length))
-            const cmdW = Math.max(...rows.map((r) => r[1]!.length))
-            return rows.map(
-              ([shell, cmd, comment]) =>
-                `  ${shell!.padEnd(shellW)}  ${cmd!.padEnd(cmdW)}  ${comment}`,
-            )
-          })(),
-        ].join('\n'),
+        Help.formatCommand(`${name} completions`, {
+          args: b.args,
+          description: b.description,
+          hideGlobalOptions: true,
+          hint: b.hint?.(name),
+        }),
       )
       return
     }
-    const shell = filtered[completionsIdx + 1]
-    if (!shell || !['bash', 'fish', 'nushell', 'zsh'].includes(shell)) {
+    if (!shells.includes(shell as any)) {
       writeln(
         formatHumanError({
           code: 'INVALID_SHELL',
-          message: shell
-            ? `Unknown shell '${shell}'. Supported: bash, fish, nushell, zsh`
-            : `Missing shell argument. Usage: ${name} completions <bash|fish|nushell|zsh>`,
+          message: `Unknown shell '${shell}'. Supported: ${shells.join(', ')}`,
         }),
       )
       exit(1)
       return
     }
     const names = [name, ...(options.aliases ?? [])]
-    writeln(names.map((n) => Completions.register(shell as Completions.Shell, n)).join('\n'))
+    writeln(names.map((n) => Completions.register(shell as Shell, n)).join('\n'))
     return
   }
 
   // skills add: generate skill files and install via `<pm>x skills add` (only when sync is configured)
   const skillsIdx =
     filtered[0] === 'skills' ? 0 : filtered[0] === name && filtered[1] === 'skills' ? 1 : -1
-  if (skillsIdx !== -1 && filtered[skillsIdx] === 'skills' && filtered[skillsIdx + 1] === 'add') {
+  if (skillsIdx !== -1 && filtered[skillsIdx] === 'skills') {
+    if (filtered[skillsIdx + 1] !== 'add') {
+      const b = builtinCommands.find((c) => c.name === 'skills')!
+      writeln(formatBuiltinHelp(name, b))
+      return
+    }
     if (help) {
-      writeln(
-        [
-          `${name} skills add — Sync skill files to agents`,
-          '',
-          `Usage: ${name} skills add [options]`,
-          '',
-          'Options:',
-          '  --depth <number>  Grouping depth for skill files (default: 1)',
-          '  --no-global       Install to project instead of globally',
-        ].join('\n'),
-      )
+      const b = builtinCommands.find((c) => c.name === 'skills')!
+      writeln(formatBuiltinSubcommandHelp(name, b, 'add'))
       return
     }
     const rest = filtered.slice(skillsIdx + 2)
@@ -674,20 +717,15 @@ async function serveImpl(
 
   // mcp add: register CLI as MCP server via `npx add-mcp`
   const mcpIdx = filtered[0] === 'mcp' ? 0 : filtered[0] === name && filtered[1] === 'mcp' ? 1 : -1
-  if (mcpIdx !== -1 && filtered[mcpIdx] === 'mcp' && filtered[mcpIdx + 1] === 'add') {
+  if (mcpIdx !== -1 && filtered[mcpIdx] === 'mcp') {
+    if (filtered[mcpIdx + 1] !== 'add') {
+      const b = builtinCommands.find((c) => c.name === 'mcp')!
+      writeln(formatBuiltinHelp(name, b))
+      return
+    }
     if (help) {
-      writeln(
-        [
-          `${name} mcp add — Register as MCP server for your agent`,
-          '',
-          `Usage: ${name} mcp add [options]`,
-          '',
-          'Options:',
-          '  -c, --command <cmd>  Override the command agents will run (e.g. "pnpm my-cli --mcp")',
-          '  --no-global          Install to project instead of globally',
-          '  --agent <agent>      Target a specific agent (e.g. claude-code, cursor)',
-        ].join('\n'),
-      )
+      const b = builtinCommands.find((c) => c.name === 'mcp')!
+      writeln(formatBuiltinSubcommandHelp(name, b, 'add'))
       return
     }
     const rest = filtered.slice(mcpIdx + 2)
@@ -759,6 +797,7 @@ async function serveImpl(
         Help.formatCommand(name, {
           alias: cmd.alias as Record<string, string> | undefined,
           aliases: options.aliases,
+          configFlag,
           description: cmd.description ?? options.description,
           version: options.version,
           args: cmd.args,
@@ -780,6 +819,7 @@ async function serveImpl(
       writeln(
         Help.formatRoot(name, {
           aliases: options.aliases,
+          configFlag,
           description: options.description,
           version: options.version,
           commands: collectHelpCommands(commands),
@@ -828,6 +868,7 @@ async function serveImpl(
           Help.formatCommand(name, {
             alias: cmd.alias as Record<string, string> | undefined,
             aliases: options.aliases,
+            configFlag,
             description: cmd.description ?? options.description,
             version: options.version,
             args: cmd.args,
@@ -845,6 +886,7 @@ async function serveImpl(
         writeln(
           Help.formatRoot(helpName, {
             aliases: isRoot ? options.aliases : undefined,
+            configFlag,
             description: helpDesc,
             version: isRoot ? options.version : undefined,
             commands: collectHelpCommands(helpCmds),
@@ -864,6 +906,7 @@ async function serveImpl(
         Help.formatCommand(commandName, {
           alias: cmd.alias as Record<string, string> | undefined,
           aliases: isRootCmd ? options.aliases : undefined,
+          configFlag,
           description: cmd.description,
           version: isRootCmd ? options.version : undefined,
           args: cmd.args,
@@ -886,6 +929,7 @@ async function serveImpl(
     if ('help' in resolved) {
       writeln(
         Help.formatRoot(`${name} ${resolved.path}`, {
+          configFlag,
           description: resolved.description,
           commands: collectHelpCommands(resolved.commands),
         }),
@@ -917,6 +961,7 @@ async function serveImpl(
   if ('help' in resolved) {
     writeln(
       Help.formatRoot(`${name} ${resolved.path}`, {
+        configFlag,
         description: resolved.description,
         commands: collectHelpCommands(resolved.commands),
       }),
@@ -1198,211 +1243,150 @@ async function serveImpl(
     ...((command.middleware as MiddlewareHandler[] | undefined) ?? []),
   ]
 
-  // Initialize vars from schema defaults
-  const varsMap: Record<string, unknown> = options.vars ? options.vars.parse({}) : {}
-  const envSource = options.env ?? process.env
-
-  const runCommand = async () => {
-    const { args, options: parsedOptions } = Parser.parse(rest, {
-      alias: command.alias as Record<string, string> | undefined,
-      args: command.args,
-      options: command.options,
-    })
-
-    if (human)
-      emitDeprecationWarnings(
-        rest,
-        command.options,
-        command.alias as Record<string, string> | undefined,
-      )
-
-    const env = command.env ? Parser.parseEnv(command.env, envSource) : {}
-
-    const okFn = (data: unknown, meta: { cta?: CtaBlock | undefined } = {}): never => {
-      return { [sentinel]: 'ok', data, cta: meta.cta } as never
-    }
-    const errorFn = (opts: {
-      code: string
-      exitCode?: number | undefined
-      message: string
-      retryable?: boolean | undefined
-      cta?: CtaBlock | undefined
-    }): never => {
-      return { [sentinel]: 'error', ...opts } as never
-    }
-
-    const result = command.run({
-      agent: !human,
-      args,
-      env,
-      error: errorFn,
-      format,
-      formatExplicit,
-      name,
-      ok: okFn,
-      options: parsedOptions,
-      var: varsMap,
-      version: options.version,
-    })
+  if (human)
+    emitDeprecationWarnings(
+      rest,
+      command.options,
+      command.alias as Record<string, string> | undefined,
+    )
 
-    // Streaming path — async generator
-    if (isAsyncGenerator(result)) {
-      await handleStreaming(result, {
-        name,
-        path,
-        start,
-        format,
-        formatExplicit,
-        human,
-        renderOutput,
-        verbose,
-        truncate,
-        write,
-        writeln,
-        exit,
+  let defaults: Record<string, unknown> | undefined
+  if (configEnabled) {
+    try {
+      defaults = await loadCommandOptionDefaults(name, path, {
+        configDisabled,
+        configPath,
+        files: options.config?.files,
+        loader: options.config?.loader,
       })
-      return
-    }
-
-    const awaited = await result
-
-    if (isSentinel(awaited)) {
-      const cta = formatCtaBlock(name, awaited.cta)
-      if (awaited[sentinel] === 'ok') {
-        write({
-          ok: true,
-          data: awaited.data,
-          meta: {
-            command: path,
-            duration: `${Math.round(performance.now() - start)}ms`,
-            ...(cta ? { cta } : undefined),
-          },
-        })
-      } else {
-        const err = awaited as ErrorResult
-        write({
-          ok: false,
-          error: {
-            code: err.code,
-            message: err.message,
-            ...(err.retryable !== undefined ? { retryable: err.retryable } : undefined),
-          },
-          meta: {
-            command: path,
-            duration: `${Math.round(performance.now() - start)}ms`,
-            ...(cta ? { cta } : undefined),
-          },
-        })
-        exit(err.exitCode ?? 1)
-      }
-    } else {
+    } catch (error) {
       write({
-        ok: true,
-        data: awaited,
-        meta: {
-          command: path,
-          duration: `${Math.round(performance.now() - start)}ms`,
+        ok: false,
+        error: {
+          code: error instanceof IncurError ? error.code : 'UNKNOWN',
+          message: error instanceof Error ? error.message : String(error),
         },
+        meta: { command: path, duration: `${Math.round(performance.now() - start)}ms` },
       })
+      exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1)
+      return
     }
   }
 
-  try {
-    const cliEnv = options.envSchema ? Parser.parseEnv(options.envSchema, envSource) : {}
+  const result = await Command.execute(command, {
+    agent: !human,
+    argv: rest,
+    defaults,
+    env: options.envSchema,
+    envSource: options.env,
+    format,
+    formatExplicit,
+    inputOptions: {},
+    middlewares: allMiddleware,
+    name,
+    path,
+    vars: options.vars,
+    version: options.version,
+  })
 
-    if (allMiddleware.length > 0) {
-      const errorFn = (opts: {
-        code: string
-        exitCode?: number | undefined
-        message: string
-        retryable?: boolean | undefined
-        cta?: CtaBlock | undefined
-      }): never => {
-        return { [sentinel]: 'error', ...opts } as never
-      }
-      const mwCtx: MiddlewareContext = {
-        agent: !human,
+  const duration = `${Math.round(performance.now() - start)}ms`
+
+  // Streaming path — async generator
+  if ('stream' in result) {
+    await handleStreaming(result.stream, {
+      name,
+      path,
+      start,
+      format,
+      formatExplicit,
+      human,
+      renderOutput,
+      verbose,
+      truncate,
+      write,
+      writeln,
+      exit,
+    })
+    return
+  }
+
+  if (result.ok) {
+    const cta = formatCtaBlock(name, result.cta as CtaBlock | undefined)
+    write({
+      ok: true,
+      data: result.data,
+      meta: {
         command: path,
-        env: cliEnv,
-        error: errorFn,
-        format,
-        formatExplicit,
-        name,
-        set(key: string, value: unknown) {
-          varsMap[key] = value
-        },
-        var: varsMap,
-        version: options.version,
-      }
-      const handleMwSentinel = (result: unknown) => {
-        if (!isSentinel(result) || result[sentinel] !== 'error') return
-        const err = result as ErrorResult
-        const cta = formatCtaBlock(name, err.cta)
-        write({
-          ok: false,
-          error: {
-            code: err.code,
-            message: err.message,
-            ...(err.retryable !== undefined ? { retryable: err.retryable } : undefined),
-          },
-          meta: {
-            command: path,
-            duration: `${Math.round(performance.now() - start)}ms`,
-            ...(cta ? { cta } : undefined),
-          },
-        })
-        exit(err.exitCode ?? 1)
-      }
-      const composed = allMiddleware.reduceRight(
-        (next: () => Promise<void>, mw) => async () => {
-          handleMwSentinel(await mw(mwCtx, next))
-        },
-        runCommand,
+        duration,
+        ...(cta ? { cta } : undefined),
+      },
+    })
+  } else {
+    const cta = formatCtaBlock(name, result.cta as CtaBlock | undefined)
+
+    if (human && !formatExplicit && result.error.fieldErrors) {
+      writeln(
+        formatHumanValidationError(
+          name,
+          path,
+          command,
+          new ValidationError({
+            message: result.error.message,
+            fieldErrors: result.error.fieldErrors,
+          }),
+          options.env,
+          configFlag,
+        ),
       )
-      await composed()
-    } else {
-      await runCommand()
+      exit(1)
+      return
     }
-  } catch (error) {
-    const errorOutput: Output = {
+
+    write({
       ok: false,
       error: {
-        code:
-          error instanceof IncurError
-            ? error.code
-            : error instanceof ValidationError
-              ? 'VALIDATION_ERROR'
-              : 'UNKNOWN',
-        message: error instanceof Error ? error.message : String(error),
-        ...(error instanceof IncurError ? { retryable: error.retryable } : undefined),
-        ...(error instanceof ValidationError ? { fieldErrors: error.fieldErrors } : undefined),
+        code: result.error.code,
+        message: result.error.message,
+        ...(result.error.retryable !== undefined
+          ? { retryable: result.error.retryable }
+          : undefined),
+        ...(result.error.fieldErrors ? { fieldErrors: result.error.fieldErrors } : undefined),
       },
       meta: {
         command: path,
-        duration: `${Math.round(performance.now() - start)}ms`,
+        duration,
+        ...(cta ? { cta } : undefined),
       },
-    }
-
-    if (human && !formatExplicit && error instanceof ValidationError) {
-      writeln(formatHumanValidationError(name, path, command, error, options.env))
-      exit(1)
-      return
-    }
-
-    write(errorOutput)
-    exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1)
+    })
+    exit(result.exitCode ?? 1)
   }
 }
 
 /** @internal Options for fetchImpl. */
 declare namespace fetchImpl {
   type Options = {
+    /** CLI-level env schema. */
+    envSchema?: z.ZodObject<any> | undefined
+    /** Group-level middleware collected during command resolution. */
+    groupMiddlewares?: MiddlewareHandler[] | undefined
     mcpHandler?:
-      | ((req: Request, commands: Map<string, CommandEntry>) => Promise<Response>)
+      | ((
+          req: Request,
+          commands: Map<string, CommandEntry>,
+          mcpOptions?: {
+            middlewares?: MiddlewareHandler[] | undefined
+            env?: z.ZodObject<any> | undefined
+            vars?: z.ZodObject<any> | undefined
+          },
+        ) => Promise<Response>)
       | undefined
     middlewares?: MiddlewareHandler[] | undefined
+    /** CLI name. */
+    name?: string | undefined
     rootCommand?: CommandDefinition<any, any, any> | undefined
     vars?: z.ZodObject<any> | undefined
+    /** CLI version string. */
+    version?: string | undefined
   }
 }
 
@@ -1410,7 +1394,15 @@ declare namespace fetchImpl {
 function createMcpHttpHandler(name: string, version: string) {
   let transport: any
 
-  return async (req: Request, commands: Map<string, CommandEntry>): Promise<Response> => {
+  return async (
+    req: Request,
+    commands: Map<string, CommandEntry>,
+    mcpOptions?: {
+      middlewares?: MiddlewareHandler[] | undefined
+      env?: z.ZodObject<any> | undefined
+      vars?: z.ZodObject<any> | undefined
+    },
+  ): Promise<Response> => {
     if (!transport) {
       const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js')
       const { WebStandardStreamableHTTPServerTransport } =
@@ -1433,7 +1425,13 @@ function createMcpHttpHandler(name: string, version: string) {
           },
           async (...callArgs: any[]) => {
             const params = hasInput ? (callArgs[0] as Record<string, unknown>) : {}
-            return Mcp.callTool(tool, params)
+            return Mcp.callTool(tool, params, {
+              name,
+              version,
+              middlewares: mcpOptions?.middlewares,
+              env: mcpOptions?.env,
+              vars: mcpOptions?.vars,
+            })
           },
         )
       }
@@ -1462,7 +1460,11 @@ async function fetchImpl(
 
   // MCP over HTTP: route /mcp to the MCP transport
   if (segments[0] === 'mcp' && segments.length === 1 && options.mcpHandler)
-    return options.mcpHandler(req, commands)
+    return options.mcpHandler(req, commands, {
+      middlewares: options.middlewares,
+      env: options.envSchema,
+      vars: options.vars,
+    })
 
   // .well-known/skills/ — Agent Skills Discovery (RFC)
   if (
@@ -1571,7 +1573,11 @@ async function fetchImpl(
   if ('fetchGateway' in resolved) return resolved.fetchGateway.fetch(req)
 
   const { command, path, rest } = resolved
-  return executeCommand(path, command, rest, inputOptions, start, options)
+  const groupMiddlewares = 'middlewares' in resolved ? resolved.middlewares : []
+  return executeCommand(path, command, rest, inputOptions, start, {
+    ...options,
+    groupMiddlewares,
+  })
 }
 
 /** @internal Executes a resolved command for the fetch handler and returns a JSON Response. */
@@ -1590,200 +1596,107 @@ async function executeCommand(
     })
   }
 
-  const sentinel_ = Symbol.for('incur.sentinel')
-  const varsMap: Record<string, unknown> = options.vars ? options.vars.parse({}) : {}
-  let response: Response | undefined
+  const allMiddleware = [
+    ...(options.middlewares ?? []),
+    ...((options.groupMiddlewares as MiddlewareHandler[] | undefined) ?? []),
+    ...((command.middleware as MiddlewareHandler[] | undefined) ?? []),
+  ]
 
-  const runCommand = async () => {
-    const { args } = Parser.parse(rest, { args: command.args })
-    const parsedOptions = command.options ? command.options.parse(inputOptions) : {}
+  const result = await Command.execute(command, {
+    agent: true,
+    argv: rest,
+    env: options.envSchema,
+    format: 'json',
+    formatExplicit: true,
+    inputOptions,
+    middlewares: allMiddleware,
+    name: options.name ?? path,
+    parseMode: 'split',
+    path,
+    vars: options.vars,
+    version: options.version,
+  })
 
-    const okFn = (data: unknown): never => ({ [sentinel_]: 'ok', data }) as never
-    const errorFn = (opts: {
-      code: string
-      message: string
-      exitCode?: number | undefined
-    }): never => ({ [sentinel_]: 'error', ...opts }) as never
-
-    const result = command.run({
-      agent: true,
-      args,
-      env: {},
-      error: errorFn,
-      format: 'json',
-      formatExplicit: true,
-      name: path,
-      ok: okFn,
-      options: parsedOptions,
-      var: varsMap,
-      version: undefined,
-    })
+  const duration = `${Math.round(performance.now() - start)}ms`
 
-    // Streaming path — async generator → NDJSON response
-    if (isAsyncGenerator(result)) {
-      const stream = new ReadableStream({
-        async start(controller) {
-          const encoder = new TextEncoder()
-          try {
-            let returnValue: unknown
-            while (true) {
-              const { value, done } = await result.next()
-              if (done) {
-                returnValue = value
-                break
-              }
-              if (isSentinel(value) && (value as any)[sentinel] === 'error') {
-                const tagged = value as any
-                controller.enqueue(
-                  encoder.encode(
-                    JSON.stringify({
-                      type: 'error',
-                      ok: false,
-                      error: { code: tagged.code, message: tagged.message },
-                    }) + '\n',
-                  ),
-                )
-                controller.close()
-                return
-              }
-              controller.enqueue(
-                encoder.encode(JSON.stringify({ type: 'chunk', data: value }) + '\n'),
-              )
-            }
-            const meta: Record<string, unknown> = { command: path }
-            if (isSentinel(returnValue) && (returnValue as any)[sentinel] === 'error') {
-              const tagged = returnValue as any
-              controller.enqueue(
-                encoder.encode(
-                  JSON.stringify({
-                    type: 'error',
-                    ok: false,
-                    error: { code: tagged.code, message: tagged.message },
-                  }) + '\n',
-                ),
-              )
-            } else {
-              controller.enqueue(
-                encoder.encode(JSON.stringify({ type: 'done', ok: true, meta }) + '\n'),
-              )
-            }
-          } catch (error) {
+  // Streaming path — async generator → NDJSON response
+  if ('stream' in result) {
+    const stream = new ReadableStream({
+      async start(controller) {
+        const encoder = new TextEncoder()
+        try {
+          for await (const value of result.stream) {
             controller.enqueue(
-              encoder.encode(
-                JSON.stringify({
-                  type: 'error',
-                  ok: false,
-                  error: {
-                    code: 'UNKNOWN',
-                    message: error instanceof Error ? error.message : String(error),
-                  },
-                }) + '\n',
-              ),
+              encoder.encode(JSON.stringify({ type: 'chunk', data: value }) + '\n'),
             )
           }
-          controller.close()
-        },
-      })
-      response = new Response(stream, {
-        status: 200,
-        headers: { 'content-type': 'application/x-ndjson' },
-      })
-      return
-    }
-
-    const awaited = await result
-    const duration = `${Math.round(performance.now() - start)}ms`
-
-    if (typeof awaited === 'object' && awaited !== null && sentinel_ in awaited) {
-      const tagged = awaited as any
-      if (tagged[sentinel_] === 'error')
-        response = jsonResponse(
-          {
-            ok: false,
-            error: { code: tagged.code, message: tagged.message },
-            meta: { command: path, duration },
-          },
-          500,
-        )
-      else
-        response = jsonResponse(
-          { ok: true, data: tagged.data, meta: { command: path, duration } },
-          200,
-        )
-      return
-    }
-
-    response = jsonResponse({ ok: true, data: awaited, meta: { command: path, duration } }, 200)
+          controller.enqueue(
+            encoder.encode(
+              JSON.stringify({
+                type: 'done',
+                ok: true,
+                meta: { command: path },
+              }) + '\n',
+            ),
+          )
+        } catch (error) {
+          controller.enqueue(
+            encoder.encode(
+              JSON.stringify({
+                type: 'error',
+                ok: false,
+                error: {
+                  code: 'UNKNOWN',
+                  message: error instanceof Error ? error.message : String(error),
+                },
+              }) + '\n',
+            ),
+          )
+        }
+        controller.close()
+      },
+    })
+    return new Response(stream, {
+      status: 200,
+      headers: { 'content-type': 'application/x-ndjson' },
+    })
   }
 
-  try {
-    const allMiddleware = options.middlewares ?? []
-    if (allMiddleware.length > 0) {
-      const errorFn = (opts: {
-        code: string
-        message: string
-        exitCode?: number | undefined
-      }): never => {
-        const duration = `${Math.round(performance.now() - start)}ms`
-        response = jsonResponse(
-          {
-            ok: false,
-            error: { code: opts.code, message: opts.message },
-            meta: { command: path, duration },
-          },
-          500,
-        )
-        return undefined as never
-      }
-      const mwCtx: MiddlewareContext = {
-        agent: true,
-        command: path,
-        env: {},
-        error: errorFn,
-        format: 'json',
-        formatExplicit: true,
-        name: path,
-        set(key: string, value: unknown) {
-          varsMap[key] = value
-        },
-        var: varsMap,
-        version: undefined,
-      }
-      const composed = allMiddleware.reduceRight(
-        (next: () => Promise<void>, mw) => async () => {
-          await mw(mwCtx, next)
-        },
-        runCommand,
-      )
-      await composed()
-    } else {
-      await runCommand()
-    }
-  } catch (error) {
-    const duration = `${Math.round(performance.now() - start)}ms`
-    if (error instanceof ValidationError)
-      return jsonResponse(
-        {
-          ok: false,
-          error: { code: 'VALIDATION_ERROR', message: error.message },
-          meta: { command: path, duration },
-        },
-        400,
-      )
+  if (!result.ok) {
+    const cta = formatCtaBlock(options.name ?? path, result.cta as CtaBlock | undefined)
     return jsonResponse(
       {
         ok: false,
         error: {
-          code: error instanceof IncurError ? error.code : 'UNKNOWN',
-          message: error instanceof Error ? error.message : String(error),
+          code: result.error.code,
+          message: result.error.message,
+          ...(result.error.retryable !== undefined
+            ? { retryable: result.error.retryable }
+            : undefined),
+        },
+        meta: {
+          command: path,
+          duration,
+          ...(cta ? { cta } : undefined),
         },
-        meta: { command: path, duration },
       },
-      500,
+      result.error.code === 'VALIDATION_ERROR' ? 400 : 500,
     )
   }
 
-  return response!
+  const cta = formatCtaBlock(options.name ?? path, result.cta as CtaBlock | undefined)
+  return jsonResponse(
+    {
+      ok: true,
+      data: result.data,
+      meta: {
+        command: path,
+        duration,
+        ...(cta ? { cta } : undefined),
+      },
+    },
+    200,
+  )
 }
 
 /** @internal Formats a validation error for TTY with usage hint. */
@@ -1793,6 +1706,7 @@ function formatHumanValidationError(
   command: CommandDefinition<any, any, any>,
   error: ValidationError,
   envSource?: Record<string, string | undefined>,
+  configFlag?: string,
 ): string {
   const lines: string[] = []
   for (const fe of error.fieldErrors) lines.push(`Error: missing required argument <${fe.path}>`)
@@ -1801,6 +1715,7 @@ function formatHumanValidationError(
   lines.push(
     Help.formatCommand(path === cli ? cli : `${cli} ${path}`, {
       alias: command.alias as Record<string, string> | undefined,
+      configFlag,
       description: command.description,
       args: command.args,
       env: command.env,
@@ -1910,6 +1825,20 @@ declare namespace serveImpl {
   type Options = serve.Options & {
     /** Alternative binary names for this CLI. */
     aliases?: string[] | undefined
+    config?:
+      | {
+          flag?: string | undefined
+          files?: string[] | undefined
+          loader?:
+            | ((
+                path: string | undefined,
+              ) =>
+                | Record<string, unknown>
+                | undefined
+                | Promise<Record<string, unknown> | undefined>)
+            | undefined
+        }
+      | undefined
     description?: string | undefined
     /** CLI-level env schema. Parsed before middleware runs. */
     envSchema?: z.ZodObject<any> | undefined
@@ -1944,7 +1873,7 @@ declare namespace serveImpl {
 }
 
 /** @internal Extracts built-in flags (--verbose, --format, --json, --llms, --help, --version) from argv. */
-function extractBuiltinFlags(argv: string[]) {
+function extractBuiltinFlags(argv: string[], options: extractBuiltinFlags.Options = {}) {
   let verbose = false
   let llms = false
   let llmsFull = false
@@ -1954,12 +1883,18 @@ function extractBuiltinFlags(argv: string[]) {
   let schema = false
   let format: Formatter.Format = 'toon'
   let formatExplicit = false
+  let configPath: string | undefined
+  let configDisabled = false
   let filterOutput: string | undefined
   let tokenLimit: number | undefined
   let tokenOffset: number | undefined
   let tokenCount = false
   const rest: string[] = []
 
+  const cfgFlag = options.configFlag ? `--${options.configFlag}` : undefined
+  const cfgFlagEq = options.configFlag ? `--${options.configFlag}=` : undefined
+  const noCfgFlag = options.configFlag ? `--no-${options.configFlag}` : undefined
+
   for (let i = 0; i < argv.length; i++) {
     const token = argv[i]!
     if (token === '--verbose') verbose = true
@@ -1976,6 +1911,22 @@ function extractBuiltinFlags(argv: string[]) {
       format = argv[i + 1] as Formatter.Format
       formatExplicit = true
       i++
+    } else if (cfgFlag && token === cfgFlag) {
+      const value = argv[i + 1]
+      if (value === undefined)
+        throw new ParseError({ message: `Missing value for flag: ${cfgFlag}` })
+      configPath = value
+      configDisabled = false
+      i++
+    } else if (cfgFlagEq && token.startsWith(cfgFlagEq)) {
+      const value = token.slice(cfgFlagEq.length)
+      if (value.length === 0)
+        throw new ParseError({ message: `Missing value for flag: ${cfgFlag}` })
+      configPath = value
+      configDisabled = false
+    } else if (noCfgFlag && token === noCfgFlag) {
+      configPath = undefined
+      configDisabled = true
     } else if (token === '--filter-output' && argv[i + 1]) {
       filterOutput = argv[i + 1]!
       i++
@@ -1993,6 +1944,8 @@ function extractBuiltinFlags(argv: string[]) {
     verbose,
     format,
     formatExplicit,
+    configPath,
+    configDisabled,
     filterOutput,
     tokenLimit,
     tokenOffset,
@@ -2007,6 +1960,145 @@ function extractBuiltinFlags(argv: string[]) {
   }
 }
 
+declare namespace extractBuiltinFlags {
+  type Options = {
+    configFlag?: string | undefined
+  }
+}
+
+/** @internal Loads config-backed option defaults for the active command. */
+async function loadCommandOptionDefaults(
+  cli: string,
+  path: string,
+  options: loadCommandOptionDefaults.Options = {},
+): Promise<Record<string, unknown> | undefined> {
+  if (options.configDisabled) return undefined
+
+  const { loader } = options
+
+  // Resolve the target file path
+  let targetPath: string | undefined
+  if (options.configPath) {
+    targetPath = resolveConfigPath(options.configPath)
+  } else {
+    const searchPaths = options.files ?? [`${cli}.json`]
+    targetPath = await findFirstExisting(searchPaths)
+  }
+
+  // Load and parse the config
+  let parsed: Record<string, unknown>
+  if (loader) {
+    const result = await loader(targetPath)
+    if (result === undefined) return undefined
+    if (!isRecord(result))
+      throw new ParseError({ message: 'Config loader must return a plain object or undefined' })
+    parsed = result
+  } else {
+    if (!targetPath) return undefined
+    const result = await readJsonConfig(targetPath, !!options.configPath)
+    if (!result) return undefined
+    parsed = result
+  }
+
+  // Extract the command section from the config tree
+  return extractCommandSection(parsed, cli, path)
+}
+
+declare namespace loadCommandOptionDefaults {
+  type Options = {
+    configDisabled?: boolean | undefined
+    configPath?: string | undefined
+    files?: string[] | undefined
+    loader?:
+      | ((
+          path: string | undefined,
+        ) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>)
+      | undefined
+  }
+}
+
+/** @internal Resolves a config file path, expanding `~` to home dir. */
+function resolveConfigPath(filePath: string): string {
+  if (filePath.startsWith('~/') || filePath === '~') {
+    return path.join(os.homedir(), filePath.slice(1))
+  }
+  return path.resolve(process.cwd(), filePath)
+}
+
+/** @internal Returns the first readable file from a list of paths, or `undefined`. */
+async function findFirstExisting(paths: string[]): Promise<string | undefined> {
+  for (const p of paths) {
+    const resolved = resolveConfigPath(p)
+    try {
+      await fs.access(resolved, fs.constants.R_OK)
+      return resolved
+    } catch {}
+  }
+  return undefined
+}
+
+/** @internal Reads and parses a JSON config file. */
+async function readJsonConfig(
+  targetPath: string,
+  explicit: boolean,
+): Promise<Record<string, unknown> | undefined> {
+  let raw: string
+  try {
+    raw = await fs.readFile(targetPath, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      if (explicit) throw new ParseError({ message: `Config file not found: ${targetPath}` })
+      return undefined
+    }
+    throw error
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new ParseError({
+      message: `Invalid JSON config file: ${targetPath}`,
+      cause: error instanceof Error ? error : undefined,
+    })
+  }
+
+  if (!isRecord(parsed))
+    throw new ParseError({
+      message: `Invalid config file: expected a top-level object in ${targetPath}`,
+    })
+  return parsed
+}
+
+/** @internal Walks the nested config tree to extract option defaults for a command path. */
+function extractCommandSection(
+  parsed: Record<string, unknown>,
+  cli: string,
+  path: string,
+): Record<string, unknown> | undefined {
+  const segments = path === cli ? [] : path.split(' ')
+  let node: unknown = parsed
+  for (const seg of segments) {
+    if (!isRecord(node)) return undefined
+    const commands = node.commands
+    if (!isRecord(commands)) return undefined
+    node = commands[seg]
+    if (node === undefined) return undefined
+  }
+  if (!isRecord(node))
+    throw new ParseError({
+      message: `Invalid config section for '${path}': expected an object`,
+    })
+
+  const options = node.options
+  if (options === undefined) return undefined
+  if (!isRecord(options))
+    throw new ParseError({
+      message: `Invalid config 'options' for '${path}': expected an object`,
+    })
+  return Object.keys(options).length > 0 ? options : undefined
+}
+
 /** @internal Collects immediate child commands/groups for help output. */
 function collectHelpCommands(
   commands: Map<string, CommandEntry>,
@@ -2018,6 +2110,29 @@ function collectHelpCommands(
   return result.sort((a, b) => a.name.localeCompare(b.name))
 }
 
+/** @internal Formats group-level help for a built-in command (e.g. `cli skills`). */
+function formatBuiltinHelp(cli: string, builtin: (typeof builtinCommands)[number]): string {
+  return Help.formatRoot(`${cli} ${builtin.name}`, {
+    description: builtin.description,
+    commands: builtin.subcommands?.map((s) => ({ name: s.name, description: s.description })),
+  })
+}
+
+/** @internal Formats subcommand-level help for a built-in command (e.g. `cli skills add --help`). */
+function formatBuiltinSubcommandHelp(
+  cli: string,
+  builtin: (typeof builtinCommands)[number],
+  subName: string,
+): string {
+  const sub = builtin.subcommands?.find((s) => s.name === subName)
+  return Help.formatCommand(`${cli} ${builtin.name} ${subName}`, {
+    alias: sub?.alias,
+    description: sub?.description,
+    hideGlobalOptions: true,
+    options: sub?.options,
+  })
+}
+
 /** @internal Formats help text for a fetch gateway command. */
 function formatFetchHelp(name: string, description?: string): string {
   const lines: string[] = []
@@ -2087,7 +2202,13 @@ export const toCommands = new WeakMap<Cli, Map<string, CommandEntry>>()
 const toMiddlewares = new WeakMap<Cli, MiddlewareHandler[]>()
 
 /** @internal Maps root CLI instances to their command definitions. */
-const toRootDefinition = new WeakMap<Root, CommandDefinition<any, any, any>>()
+export const toRootDefinition = new WeakMap<Root, CommandDefinition<any, any, any>>()
+
+/** @internal Maps CLI instances to their root options schema. */
+export const toRootOptions = new WeakMap<Cli, z.ZodObject<any>>()
+
+/** @internal Maps CLI instances to whether config file loading is enabled. */
+export const toConfigEnabled = new WeakMap<Cli, boolean>()
 
 /** @internal Maps CLI instances to their output policy. */
 const toOutputPolicy = new WeakMap<Cli, OutputPolicy>()
@@ -2155,16 +2276,6 @@ function isSentinel(value: unknown): value is OkResult | ErrorResult {
   return typeof value === 'object' && value !== null && sentinel in value
 }
 
-/** @internal Type guard for async generators returned by streaming `run` handlers. */
-function isAsyncGenerator(value: unknown): value is AsyncGenerator<unknown, unknown, unknown> {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    Symbol.asyncIterator in value &&
-    typeof (value as any).next === 'function'
-  )
-}
-
 /** @internal Handles streaming output from an async generator `run` handler. */
 async function handleStreaming(
   generator: AsyncGenerator<unknown, unknown, unknown>,
@@ -2649,15 +2760,9 @@ type CommandDefinition<
   output extends z.ZodType | undefined = undefined,
   vars extends z.ZodObject<any> | undefined = undefined,
   cliEnv extends z.ZodObject<any> | undefined = undefined,
-> = {
-  /** Map of option names to single-char aliases. */
-  alias?: options extends z.ZodObject<any>
-    ? Partial<Record<keyof z.output<options>, string>>
-    : Record<string, string> | undefined
+> = CommandMeta<options> & {
   /** Zod schema for positional arguments. */
   args?: args | undefined
-  /** A short description of what the command does. */
-  description?: string | undefined
   /** Zod schema for environment variables. Keys are the variable names (e.g. `NPM_TOKEN`). */
   env?: env | undefined
   /** Usage examples for this command. */
@@ -2666,8 +2771,6 @@ type CommandDefinition<
   format?: Formatter.Format | undefined
   /** Plain text hint displayed after examples and before global options. */
   hint?: string | undefined
-  /** Zod schema for named options/flags. */
-  options?: options | undefined
   /** Zod schema for the command's return value. */
   output?: output | undefined
   /**