goke 6.2.3 → 6.3.0

package/README.md

@@ -11,10 +11,11 @@
 ## Features
 
 - **Super light-weight**: No dependency, just a single file.
-- **Easy to learn**. There are only 4 APIs you need to learn for building simple CLIs: `cli.option` `cli.version` `cli.help` `cli.parse`.
+- **Easy to learn**. There are only 5 APIs you need to learn for building simple CLIs: `cli.option` `cli.use` `cli.version` `cli.help` `cli.parse`.
 - **Yet so powerful**. Enable features like default command, git-like subcommands, validation for required arguments and options, variadic arguments, dot-nested options, automated help message generation and so on.
 - **Space-separated subcommands**: Support multi-word commands like `mcp login`, `git remote add`.
 - **Schema-based type coercion**: Use Zod, Valibot, ArkType, or plain JSON Schema for automatic type coercion and TypeScript type inference. Description and default values are extracted from the schema automatically.
+- **Type-safe middleware**: Register `.use()` callbacks that run before commands with full type inference from global options.
 - **Developer friendly**. Written in TypeScript.
 
 ## Install
@@ -346,6 +347,73 @@ deploy logs abc123 --follow     # subcommand with args + options
 deploy --help                   # shows all commands
 ```
 
+### Global Options and Middleware
+
+Global options are defined on the CLI instance and apply to all commands. Use `.use()` to register middleware that runs before any command action — useful for reacting to global options like setting up logging, initializing state, or configuring services.
+
+Middleware runs in registration order, after option parsing and validation, but before the matched command's `.action()` callback.
+
+```ts
+import { goke } from 'goke'
+import { z } from 'zod'
+
+const cli = goke('mycli')
+
+cli
+  .option('--verbose', z.boolean().default(false).describe('Enable verbose logging'))
+  .option('--api-url [url]', z.string().default('https://api.example.com').describe('API base URL'))
+  .use((options) => {
+    // options.verbose and options.apiUrl are fully typed here
+    if (options.verbose) {
+      process.env.LOG_LEVEL = 'debug'
+    }
+  })
+
+cli
+  .command('deploy <env>', 'Deploy to an environment')
+  .option('--dry-run', 'Preview without deploying')
+  .action((env, options) => {
+    // options includes both command options (dryRun) and global options (verbose, apiUrl)
+    console.log(`Deploying to ${env} via ${options.apiUrl}`)
+  })
+
+cli
+  .command('status', 'Show deployment status')
+  .action((options) => {
+    console.log('Checking status...')
+  })
+
+cli.help()
+cli.parse()
+```
+
+Type safety is positional — each `.use()` callback only sees options declared before it in the chain:
+
+```ts
+cli
+  .option('--verbose', z.boolean().default(false).describe('Verbose'))
+  .use((options) => {
+    options.verbose   // boolean — typed
+    options.port      // TypeScript error — not declared yet
+  })
+  .option('--port <port>', z.number().describe('Port'))
+  .use((options) => {
+    options.verbose   // boolean — still visible
+    options.port      // number — now visible
+  })
+```
+
+Middleware supports async functions. If any middleware is async, the remaining middleware and command action are chained as promises:
+
+```ts
+cli
+  .option('--token <token>', z.string().describe('API token'))
+  .use(async (options) => {
+    const client = await connectToApi(options.token)
+    globalState.client = client
+  })
+```
+
 ### Command-specific Options
 
 You can attach options to a command.
@@ -630,6 +698,12 @@ Add a global option. The second argument is either:
 - A **string** used as the description text
 - A **Standard Schema** (e.g. `z.number().describe('Port')`) — description and default are extracted from the schema automatically
 
+#### cli.use(callback)
+
+- Type: `(callback: (options: Opts) => void | Promise<void>) => CLI`
+
+Register a middleware function that runs before the matched command action. Middleware runs in registration order, after option parsing and validation. The callback receives the parsed global options, typed according to all `.option()` calls that precede the `.use()` in the chain.
+
 #### cli.parse(argv?)
 
 - Type: `(argv = process.argv) => ParsedArgv`

package/dist/__test__/index.test.js

@@ -1467,3 +1467,181 @@ describe('helpText()', () => {
         expect(text).toContain('--coverage');
     });
 });
+describe('middleware', () => {
+    test('middleware runs before command action', () => {
+        const cli = goke('mycli');
+        const order = [];
+        cli
+            .option('--verbose', 'Verbose')
+            .use(() => {
+            order.push('middleware');
+        });
+        cli
+            .command('build', 'Build')
+            .action(() => {
+            order.push('action');
+        });
+        cli.parse(['node', 'bin', 'build'], { run: true });
+        expect(order).toEqual(['middleware', 'action']);
+    });
+    test('multiple middleware run in registration order', () => {
+        const cli = goke('mycli');
+        const order = [];
+        cli
+            .use(() => { order.push('mw1'); })
+            .use(() => { order.push('mw2'); })
+            .use(() => { order.push('mw3'); });
+        cli
+            .command('deploy', 'Deploy')
+            .action(() => { order.push('action'); });
+        cli.parse(['node', 'bin', 'deploy'], { run: true });
+        expect(order).toEqual(['mw1', 'mw2', 'mw3', 'action']);
+    });
+    test('middleware receives parsed global options', () => {
+        const cli = goke('mycli');
+        let received = null;
+        cli
+            .option('--verbose', 'Verbose')
+            .use((options) => {
+            received = { ...options };
+        });
+        cli
+            .command('build', 'Build')
+            .action(() => { });
+        cli.parse(['node', 'bin', 'build', '--verbose'], { run: true });
+        expect(received.verbose).toBe(true);
+    });
+    test('middleware receives schema-coerced global options', () => {
+        const cli = goke('mycli');
+        let received = null;
+        cli
+            .option('--port <port>', z.number().describe('Port'))
+            .use((options) => {
+            received = { ...options };
+        });
+        cli
+            .command('serve', 'Serve')
+            .action(() => { });
+        cli.parse(['node', 'bin', 'serve', '--port', '3000'], { run: true });
+        expect(received.port).toBe(3000);
+        expect(typeof received.port).toBe('number');
+    });
+    test('async middleware awaited before command action', async () => {
+        const cli = goke('mycli');
+        const order = [];
+        cli.use(async () => {
+            await new Promise((r) => setTimeout(r, 10));
+            order.push('async-mw');
+        });
+        cli
+            .command('run', 'Run')
+            .action(() => { order.push('action'); });
+        cli.parse(['node', 'bin', 'run'], { run: true });
+        // Wait for async chain to complete
+        await new Promise((r) => setTimeout(r, 50));
+        expect(order).toEqual(['async-mw', 'action']);
+    });
+    test('async middleware error is caught and formatted', async () => {
+        const stderr = createTestOutputStream();
+        let exitCode;
+        const cli = goke('mycli', { stderr, exit: (code) => { exitCode = code; } });
+        cli.use(async () => {
+            throw new Error('middleware failed');
+        });
+        cli
+            .command('deploy', 'Deploy')
+            .action(() => { });
+        cli.parse(['node', 'bin', 'deploy'], { run: true });
+        await new Promise((r) => setTimeout(r, 10));
+        expect(exitCode).toBe(1);
+        expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: middleware failed"`);
+    });
+    test('middleware does not run with { run: false }', () => {
+        const cli = goke('mycli');
+        let middlewareCalled = false;
+        cli.use(() => { middlewareCalled = true; });
+        cli
+            .command('build', 'Build')
+            .action(() => { });
+        cli.parse(['node', 'bin', 'build'], { run: false });
+        expect(middlewareCalled).toBe(false);
+    });
+    test('middleware does not run for help', () => {
+        const stdout = createTestOutputStream();
+        const cli = goke('mycli', { stdout });
+        let middlewareCalled = false;
+        cli.use(() => { middlewareCalled = true; });
+        cli.help();
+        cli
+            .command('build', 'Build')
+            .action(() => { });
+        cli.parse(['node', 'bin', '--help'], { run: true });
+        expect(middlewareCalled).toBe(false);
+    });
+    test('middleware does not run when no command matched', () => {
+        const stdout = createTestOutputStream();
+        const cli = goke('mycli', { stdout });
+        let middlewareCalled = false;
+        cli.use(() => { middlewareCalled = true; });
+        cli.help();
+        cli
+            .command('build', 'Build')
+            .action(() => { });
+        cli.parse(['node', 'bin', 'nonexistent'], { run: true });
+        expect(middlewareCalled).toBe(false);
+    });
+    test('middleware runs for default command', () => {
+        const cli = goke('mycli');
+        const order = [];
+        cli.use(() => { order.push('mw'); });
+        cli
+            .command('', 'Default')
+            .action(() => { order.push('action'); });
+        cli.parse(['node', 'bin'], { run: true });
+        expect(order).toEqual(['mw', 'action']);
+    });
+    test('sync middleware error is caught and formatted', () => {
+        const stderr = createTestOutputStream();
+        let exitCode;
+        const cli = goke('mycli', { stderr, exit: (code) => { exitCode = code; } });
+        cli.use(() => {
+            throw new Error('middleware exploded');
+        });
+        cli
+            .command('deploy', 'Deploy')
+            .action(() => { });
+        cli.parse(['node', 'bin', 'deploy'], { run: true });
+        expect(exitCode).toBe(1);
+        expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: middleware exploded"`);
+    });
+    test('sync middleware error short-circuits command action', () => {
+        const stderr = createTestOutputStream();
+        const cli = goke('mycli', { stderr, exit: () => { } });
+        let actionCalled = false;
+        cli.use(() => {
+            throw new Error('abort');
+        });
+        cli
+            .command('build', 'Build')
+            .action(() => { actionCalled = true; });
+        cli.parse(['node', 'bin', 'build'], { run: true });
+        expect(actionCalled).toBe(false);
+    });
+    test('mixed sync and async middleware chain correctly', async () => {
+        const cli = goke('mycli');
+        const order = [];
+        cli
+            .use(() => { order.push('sync1'); })
+            .use(async () => {
+            await new Promise((r) => setTimeout(r, 10));
+            order.push('async');
+        })
+            .use(() => { order.push('sync2'); });
+        cli
+            .command('run', 'Run')
+            .action(() => { order.push('action'); });
+        cli.parse(['node', 'bin', 'run'], { run: true });
+        await new Promise((r) => setTimeout(r, 50));
+        expect(order).toEqual(['sync1', 'async', 'sync2', 'action']);
+    });
+});

package/dist/__test__/types.test-d.js

@@ -6,6 +6,7 @@
  * These use expectTypeOf from vitest for compile-time type assertions.
  */
 import { describe, test, expectTypeOf } from 'vitest';
+import goke from '../index.js';
 describe('type-level: ExtractOptionName', () => {
     test('extracts name from --name <value>', () => {
         expectTypeOf().toEqualTypeOf();
@@ -65,3 +66,42 @@ describe('type-level: CamelCase', () => {
         expectTypeOf().toEqualTypeOf();
     });
 });
+describe('type-level: middleware use() callback inference', () => {
+    test('use() callback receives accumulated option types', () => {
+        const schema1 = {};
+        const schema2 = {};
+        goke('test')
+            .option('--port <port>', schema1)
+            .option('--host <host>', schema2)
+            .use((options) => {
+            expectTypeOf(options.port).toEqualTypeOf();
+            expectTypeOf(options.host).toEqualTypeOf();
+        });
+    });
+    test('use() only sees options declared before it', () => {
+        const schema1 = {};
+        const schema2 = {};
+        goke('test')
+            .option('--verbose', schema1)
+            .use((options) => {
+            expectTypeOf(options.verbose).toEqualTypeOf();
+            // @ts-expect-error port is not declared yet
+            options.port;
+        })
+            .option('--port <port>', schema2)
+            .use((options) => {
+            // Now both are visible
+            expectTypeOf(options.verbose).toEqualTypeOf();
+            expectTypeOf(options.port).toEqualTypeOf();
+        });
+    });
+    test('accessing a non-existent option is a type error', () => {
+        const schema = {};
+        goke('test')
+            .option('--port <port>', schema)
+            .use((options) => {
+            // @ts-expect-error nonExistent was never defined
+            options.nonExistent;
+        });
+    });
+});

package/dist/goke.d.ts

@@ -90,7 +90,7 @@ declare class Command {
     rawName: string;
     description: string;
     config: CommandConfig;
-    cli: Goke;
+    cli: Goke<any>;
     options: Option[];
     aliasNames: string[];
     name: string;
@@ -101,7 +101,7 @@ declare class Command {
     examples: CommandExample[];
     helpCallback?: HelpCallback;
     globalCommand?: GlobalCommand;
-    constructor(rawName: string, description: string, config: CommandConfig | undefined, cli: Goke);
+    constructor(rawName: string, description: string, config: CommandConfig | undefined, cli: Goke<any>);
     usage(text: string): this;
     allowUnknownOptions(): this;
     ignoreOptionDefaultValue(): this;
@@ -160,7 +160,7 @@ declare class Command {
     checkOptionValue(): void;
 }
 declare class GlobalCommand extends Command {
-    constructor(cli: Goke);
+    constructor(cli: Goke<any>);
 }
 /**
  * Output stream interface, modeled after Node's process.stdout / process.stderr.
@@ -210,11 +210,15 @@ interface ParsedArgv {
         [k: string]: any;
     };
 }
-declare class Goke extends EventEmitter {
+declare class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
     #private;
     /** The program name to display in help and version message */
     name: string;
     commands: Command[];
+    /** Middleware functions that run before the matched command action, in registration order */
+    middlewares: Array<{
+        action: (options: any) => void | Promise<void>;
+    }>;
     globalCommand: GlobalCommand;
     matchedCommand?: Command;
     matchedCommandName?: string;
@@ -261,8 +265,34 @@ declare class Goke extends EventEmitter {
      * Add a global CLI option.
      *
      * Which is also applied to sub-commands.
+     *
+     * When a StandardJSONSchemaV1 schema is provided, the return type is narrowed
+     * to include the inferred option type — enabling type-safe `.use()` callbacks.
      */
+    option<RawName extends string, S extends StandardJSONSchemaV1>(rawName: RawName, schema: S): Goke<Opts & OptionEntry<RawName, S>>;
     option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1): this;
+    /**
+     * Register a middleware function that runs before the matched command action.
+     *
+     * Middleware runs in registration order, after option parsing and validation,
+     * but before the command's `.action()` callback. Useful for reacting to global
+     * options (e.g. setting up logging, initializing state).
+     *
+     * The callback receives the parsed options object, typed according to all
+     * `.option()` calls that precede this `.use()` in the chain.
+     *
+     * @example
+     * ```ts
+     * cli
+     *   .option('--verbose', z.boolean().default(false).describe('Verbose'))
+     *   .use((options) => {
+     *     if (options.verbose) {
+     *       process.env.LOG_LEVEL = 'debug'
+     *     }
+     *   })
+     * ```
+     */
+    use(callback: (options: Opts) => void | Promise<void>): this;
     /**
      * Show help message when `-h, --help` flags appear.
      *

package/dist/goke.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"goke.d.ts","sourceRoot":"","sources":["../src/goke.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"goke.d.ts","sourceRoot":"","sources":["../src/goke.ts"],"names":[],"mappings":"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"}

package/dist/goke.js

@@ -160,6 +160,9 @@ const getFileName = (input) => {
     const m = /([^\\\/]+)$/.exec(input);
     return m ? m[1] : '';
 };
+const isPromiseLike = (value) => value != null
+    && (typeof value === 'object' || typeof value === 'function')
+    && typeof value.then === 'function';
 const camelcaseOptionName = (name) => {
     // Camelcase the option name
     // Don't camelcase anything after the dot `.`
@@ -582,6 +585,8 @@ class Goke extends EventEmitter {
     /** The program name to display in help and version message */
     name;
     commands;
+    /** Middleware functions that run before the matched command action, in registration order */
+    middlewares;
     globalCommand;
     matchedCommand;
     matchedCommandName;
@@ -618,6 +623,7 @@ class Goke extends EventEmitter {
         super();
         this.name = name;
         this.commands = [];
+        this.middlewares = [];
         this.rawArgs = [];
         this.args = [];
         this.options = {};
@@ -648,13 +654,33 @@ class Goke extends EventEmitter {
         this.commands.push(command);
         return command;
     }
+    option(rawName, descriptionOrSchema) {
+        this.globalCommand.option(rawName, descriptionOrSchema);
+        return this;
+    }
     /**
-     * Add a global CLI option.
+     * Register a middleware function that runs before the matched command action.
+     *
+     * Middleware runs in registration order, after option parsing and validation,
+     * but before the command's `.action()` callback. Useful for reacting to global
+     * options (e.g. setting up logging, initializing state).
+     *
+     * The callback receives the parsed options object, typed according to all
+     * `.option()` calls that precede this `.use()` in the chain.
      *
-     * Which is also applied to sub-commands.
+     * @example
+     * ```ts
+     * cli
+     *   .option('--verbose', z.boolean().default(false).describe('Verbose'))
+     *   .use((options) => {
+     *     if (options.verbose) {
+     *       process.env.LOG_LEVEL = 'debug'
+     *     }
+     *   })
+     * ```
      */
-    option(rawName, descriptionOrSchema) {
-        this.globalCommand.option(rawName, descriptionOrSchema);
+    use(callback) {
+        this.middlewares.push({ action: callback });
         return this;
     }
     /**
@@ -1029,18 +1055,43 @@ class Goke extends EventEmitter {
             }
         });
         actionArgs.push(options);
-        const result = command.commandAction.apply(this, actionArgs);
-        // If the action returns a promise, catch async errors
-        if (result && typeof result === 'object' && typeof result.catch === 'function') {
-            result.catch((err) => {
-                if (err instanceof Error) {
-                    this.handleCliError(err);
+        const executeAction = () => command.commandAction.apply(this, actionArgs);
+        const handleAsyncError = (err) => {
+            if (err instanceof Error) {
+                this.handleCliError(err);
+            }
+            else {
+                this.console.error(`${pc.red(pc.bold('error:'))} ${String(err)}`);
+            }
+            this.exit(1);
+        };
+        // Run middleware in registration order, then the command action.
+        // If any middleware returns a promise, the rest of the chain
+        // (remaining middleware + command action) becomes async.
+        let asyncChain = null;
+        for (const mw of this.middlewares) {
+            if (asyncChain) {
+                asyncChain = asyncChain.then(() => mw.action(options));
+            }
+            else {
+                try {
+                    const mwResult = mw.action(options);
+                    if (isPromiseLike(mwResult)) {
+                        asyncChain = mwResult;
+                    }
                 }
-                else {
-                    this.console.error(`${pc.red(pc.bold('error:'))} ${String(err)}`);
+                catch (err) {
+                    handleAsyncError(err);
+                    return;
                 }
-                this.exit(1);
-            });
+            }
+        }
+        const result = asyncChain
+            ? asyncChain.then(executeAction)
+            : executeAction();
+        // If the result is a promise, catch async errors
+        if (isPromiseLike(result)) {
+            result.catch(handleAsyncError);
         }
         return result;
     }

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import { Command } from "./goke.js";
  * @param name The program name to display in help and version message
  * @param options Configuration for stdout, stderr, and argv
  */
-declare const goke: (name?: string, options?: GokeOptions) => Goke;
+declare const goke: (name?: string, options?: GokeOptions) => Goke<{}>;
 export default goke;
 export { goke, Goke, Command };
 export { createConsole } from "./goke.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC;;;GAGG;AACH,QAAA,MAAM,IAAI,GAAI,aAAS,EAAE,UAAU,WAAW,SAA4B,CAAA;AAE1E,eAAe,IAAI,CAAA;AACnB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAA;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC3E,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACpF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC;;;GAGG;AACH,QAAA,MAAM,IAAI,GAAI,aAAS,EAAE,UAAU,WAAW,aAA4B,CAAA;AAE1E,eAAe,IAAI,CAAA;AACnB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAA;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC3E,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACpF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goke",
-  "version": "6.2.3",
+  "version": "6.3.0",
   "type": "module",
   "description": "Simple yet powerful framework for building command-line apps. Inspired by cac.",
   "repository": {

package/src/__test__/index.test.ts

@@ -1874,3 +1874,238 @@ describe('helpText()', () => {
     expect(text).toContain('--coverage')
   })
 })
+
+describe('middleware', () => {
+  test('middleware runs before command action', () => {
+    const cli = goke('mycli')
+    const order: string[] = []
+
+    cli
+      .option('--verbose', 'Verbose')
+      .use(() => {
+        order.push('middleware')
+      })
+
+    cli
+      .command('build', 'Build')
+      .action(() => {
+        order.push('action')
+      })
+
+    cli.parse(['node', 'bin', 'build'], { run: true })
+    expect(order).toEqual(['middleware', 'action'])
+  })
+
+  test('multiple middleware run in registration order', () => {
+    const cli = goke('mycli')
+    const order: string[] = []
+
+    cli
+      .use(() => { order.push('mw1') })
+      .use(() => { order.push('mw2') })
+      .use(() => { order.push('mw3') })
+
+    cli
+      .command('deploy', 'Deploy')
+      .action(() => { order.push('action') })
+
+    cli.parse(['node', 'bin', 'deploy'], { run: true })
+    expect(order).toEqual(['mw1', 'mw2', 'mw3', 'action'])
+  })
+
+  test('middleware receives parsed global options', () => {
+    const cli = goke('mycli')
+    let received: any = null
+
+    cli
+      .option('--verbose', 'Verbose')
+      .use((options) => {
+        received = { ...options }
+      })
+
+    cli
+      .command('build', 'Build')
+      .action(() => {})
+
+    cli.parse(['node', 'bin', 'build', '--verbose'], { run: true })
+    expect(received.verbose).toBe(true)
+  })
+
+  test('middleware receives schema-coerced global options', () => {
+    const cli = goke('mycli')
+    let received: any = null
+
+    cli
+      .option('--port <port>', z.number().describe('Port'))
+      .use((options) => {
+        received = { ...options }
+      })
+
+    cli
+      .command('serve', 'Serve')
+      .action(() => {})
+
+    cli.parse(['node', 'bin', 'serve', '--port', '3000'], { run: true })
+    expect(received.port).toBe(3000)
+    expect(typeof received.port).toBe('number')
+  })
+
+  test('async middleware awaited before command action', async () => {
+    const cli = goke('mycli')
+    const order: string[] = []
+
+    cli.use(async () => {
+      await new Promise((r) => setTimeout(r, 10))
+      order.push('async-mw')
+    })
+
+    cli
+      .command('run', 'Run')
+      .action(() => { order.push('action') })
+
+    cli.parse(['node', 'bin', 'run'], { run: true })
+
+    // Wait for async chain to complete
+    await new Promise((r) => setTimeout(r, 50))
+    expect(order).toEqual(['async-mw', 'action'])
+  })
+
+  test('async middleware error is caught and formatted', async () => {
+    const stderr = createTestOutputStream()
+    let exitCode: number | undefined
+    const cli = goke('mycli', { stderr, exit: (code) => { exitCode = code } })
+
+    cli.use(async () => {
+      throw new Error('middleware failed')
+    })
+
+    cli
+      .command('deploy', 'Deploy')
+      .action(() => {})
+
+    cli.parse(['node', 'bin', 'deploy'], { run: true })
+
+    await new Promise((r) => setTimeout(r, 10))
+    expect(exitCode).toBe(1)
+    expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: middleware failed"`)
+  })
+
+  test('middleware does not run with { run: false }', () => {
+    const cli = goke('mycli')
+    let middlewareCalled = false
+
+    cli.use(() => { middlewareCalled = true })
+
+    cli
+      .command('build', 'Build')
+      .action(() => {})
+
+    cli.parse(['node', 'bin', 'build'], { run: false })
+    expect(middlewareCalled).toBe(false)
+  })
+
+  test('middleware does not run for help', () => {
+    const stdout = createTestOutputStream()
+    const cli = goke('mycli', { stdout })
+    let middlewareCalled = false
+
+    cli.use(() => { middlewareCalled = true })
+    cli.help()
+
+    cli
+      .command('build', 'Build')
+      .action(() => {})
+
+    cli.parse(['node', 'bin', '--help'], { run: true })
+    expect(middlewareCalled).toBe(false)
+  })
+
+  test('middleware does not run when no command matched', () => {
+    const stdout = createTestOutputStream()
+    const cli = goke('mycli', { stdout })
+    let middlewareCalled = false
+
+    cli.use(() => { middlewareCalled = true })
+    cli.help()
+
+    cli
+      .command('build', 'Build')
+      .action(() => {})
+
+    cli.parse(['node', 'bin', 'nonexistent'], { run: true })
+    expect(middlewareCalled).toBe(false)
+  })
+
+  test('middleware runs for default command', () => {
+    const cli = goke('mycli')
+    const order: string[] = []
+
+    cli.use(() => { order.push('mw') })
+
+    cli
+      .command('', 'Default')
+      .action(() => { order.push('action') })
+
+    cli.parse(['node', 'bin'], { run: true })
+    expect(order).toEqual(['mw', 'action'])
+  })
+
+  test('sync middleware error is caught and formatted', () => {
+    const stderr = createTestOutputStream()
+    let exitCode: number | undefined
+    const cli = goke('mycli', { stderr, exit: (code) => { exitCode = code } })
+
+    cli.use(() => {
+      throw new Error('middleware exploded')
+    })
+
+    cli
+      .command('deploy', 'Deploy')
+      .action(() => {})
+
+    cli.parse(['node', 'bin', 'deploy'], { run: true })
+
+    expect(exitCode).toBe(1)
+    expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: middleware exploded"`)
+  })
+
+  test('sync middleware error short-circuits command action', () => {
+    const stderr = createTestOutputStream()
+    const cli = goke('mycli', { stderr, exit: () => {} })
+    let actionCalled = false
+
+    cli.use(() => {
+      throw new Error('abort')
+    })
+
+    cli
+      .command('build', 'Build')
+      .action(() => { actionCalled = true })
+
+    cli.parse(['node', 'bin', 'build'], { run: true })
+
+    expect(actionCalled).toBe(false)
+  })
+
+  test('mixed sync and async middleware chain correctly', async () => {
+    const cli = goke('mycli')
+    const order: string[] = []
+
+    cli
+      .use(() => { order.push('sync1') })
+      .use(async () => {
+        await new Promise((r) => setTimeout(r, 10))
+        order.push('async')
+      })
+      .use(() => { order.push('sync2') })
+
+    cli
+      .command('run', 'Run')
+      .action(() => { order.push('action') })
+
+    cli.parse(['node', 'bin', 'run'], { run: true })
+
+    await new Promise((r) => setTimeout(r, 50))
+    expect(order).toEqual(['sync1', 'async', 'sync2', 'action'])
+  })
+})

package/src/__test__/types.test-d.ts

@@ -6,7 +6,8 @@
  * These use expectTypeOf from vitest for compile-time type assertions.
  */
 import { describe, test, expectTypeOf } from 'vitest'
-import type { StandardTypedV1 } from '../coerce.js'
+import type { StandardTypedV1, StandardJSONSchemaV1 } from '../coerce.js'
+import goke from '../index.js'
 
 // ─── Import type helpers from Command.ts ───
 // We can't import the private types directly, so we reconstruct them here
@@ -109,3 +110,48 @@ describe('type-level: CamelCase', () => {
     expectTypeOf<CamelCase<'a-b-c'>>().toEqualTypeOf<'aBC'>()
   })
 })
+
+describe('type-level: middleware use() callback inference', () => {
+  test('use() callback receives accumulated option types', () => {
+    const schema1 = {} as StandardJSONSchemaV1<unknown, number>
+    const schema2 = {} as StandardJSONSchemaV1<unknown, string>
+
+    goke('test')
+      .option('--port <port>', schema1)
+      .option('--host <host>', schema2)
+      .use((options) => {
+        expectTypeOf(options.port).toEqualTypeOf<number>()
+        expectTypeOf(options.host).toEqualTypeOf<string>()
+      })
+  })
+
+  test('use() only sees options declared before it', () => {
+    const schema1 = {} as StandardJSONSchemaV1<unknown, boolean>
+    const schema2 = {} as StandardJSONSchemaV1<unknown, number>
+
+    goke('test')
+      .option('--verbose', schema1)
+      .use((options) => {
+        expectTypeOf(options.verbose).toEqualTypeOf<boolean | undefined>()
+        // @ts-expect-error port is not declared yet
+        options.port
+      })
+      .option('--port <port>', schema2)
+      .use((options) => {
+        // Now both are visible
+        expectTypeOf(options.verbose).toEqualTypeOf<boolean | undefined>()
+        expectTypeOf(options.port).toEqualTypeOf<number>()
+      })
+  })
+
+  test('accessing a non-existent option is a type error', () => {
+    const schema = {} as StandardJSONSchemaV1<unknown, number>
+
+    goke('test')
+      .option('--port <port>', schema)
+      .use((options) => {
+        // @ts-expect-error nonExistent was never defined
+        options.nonExistent
+      })
+  })
+})

package/src/goke.ts

@@ -206,6 +206,11 @@ const getFileName = (input: string) => {
   return m ? m[1] : ''
 }
 
+const isPromiseLike = (value: unknown): value is PromiseLike<unknown> =>
+  value != null
+  && (typeof value === 'object' || typeof value === 'function')
+  && typeof (value as any).then === 'function'
+
 const camelcaseOptionName = (name: string) => {
   // Camelcase the option name
   // Don't camelcase anything after the dot `.`
@@ -373,7 +378,7 @@ class Command {
     public rawName: string,
     public description: string,
     public config: CommandConfig = {},
-    public cli: Goke
+    public cli: Goke<any>
   ) {
     this.options = []
     this.aliasNames = []
@@ -750,7 +755,7 @@ class Command {
 }
 
 class GlobalCommand extends Command {
-  constructor(cli: Goke) {
+  constructor(cli: Goke<any>) {
     super('@@global@@', '', {}, cli)
   }
 }
@@ -841,10 +846,12 @@ interface ParsedArgv {
   }
 }
 
-class Goke extends EventEmitter {
+class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
   /** The program name to display in help and version message */
   name: string
   commands: Command[]
+  /** Middleware functions that run before the matched command action, in registration order */
+  middlewares: Array<{ action: (options: any) => void | Promise<void> }>
   globalCommand: GlobalCommand
   matchedCommand?: Command
   matchedCommandName?: string
@@ -885,6 +892,7 @@ class Goke extends EventEmitter {
     super()
     this.name = name
     this.commands = []
+    this.middlewares = []
     this.rawArgs = []
     this.args = []
     this.options = {}
@@ -922,12 +930,46 @@ class Goke extends EventEmitter {
    * Add a global CLI option.
    *
    * Which is also applied to sub-commands.
+   *
+   * When a StandardJSONSchemaV1 schema is provided, the return type is narrowed
+   * to include the inferred option type — enabling type-safe `.use()` callbacks.
    */
-  option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1) {
+  option<
+    RawName extends string,
+    S extends StandardJSONSchemaV1
+  >(rawName: RawName, schema: S): Goke<Opts & OptionEntry<RawName, S>>
+  option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1): this
+  option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1): any {
     this.globalCommand.option(rawName, descriptionOrSchema as any)
     return this
   }
 
+  /**
+   * Register a middleware function that runs before the matched command action.
+   *
+   * Middleware runs in registration order, after option parsing and validation,
+   * but before the command's `.action()` callback. Useful for reacting to global
+   * options (e.g. setting up logging, initializing state).
+   *
+   * The callback receives the parsed options object, typed according to all
+   * `.option()` calls that precede this `.use()` in the chain.
+   *
+   * @example
+   * ```ts
+   * cli
+   *   .option('--verbose', z.boolean().default(false).describe('Verbose'))
+   *   .use((options) => {
+   *     if (options.verbose) {
+   *       process.env.LOG_LEVEL = 'debug'
+   *     }
+   *   })
+   * ```
+   */
+  use(callback: (options: Opts) => void | Promise<void>): this {
+    this.middlewares.push({ action: callback })
+    return this
+  }
+
   /**
    * Show help message when `-h, --help` flags appear.
    *
@@ -1353,18 +1395,45 @@ class Goke extends EventEmitter {
     })
     actionArgs.push(options)
 
-    const result = command.commandAction.apply(this, actionArgs)
+    const executeAction = () => command.commandAction!.apply(this, actionArgs)
 
-    // If the action returns a promise, catch async errors
-    if (result && typeof result === 'object' && typeof result.catch === 'function') {
-      result.catch((err: unknown) => {
-        if (err instanceof Error) {
-          this.handleCliError(err)
-        } else {
-          this.console.error(`${pc.red(pc.bold('error:'))} ${String(err)}`)
+    const handleAsyncError = (err: unknown) => {
+      if (err instanceof Error) {
+        this.handleCliError(err)
+      } else {
+        this.console.error(`${pc.red(pc.bold('error:'))} ${String(err)}`)
+      }
+      this.exit(1)
+    }
+
+    // Run middleware in registration order, then the command action.
+    // If any middleware returns a promise, the rest of the chain
+    // (remaining middleware + command action) becomes async.
+    let asyncChain: Promise<any> | null = null
+
+    for (const mw of this.middlewares) {
+      if (asyncChain) {
+        asyncChain = asyncChain.then(() => mw.action(options))
+      } else {
+        try {
+          const mwResult = mw.action(options)
+          if (isPromiseLike(mwResult)) {
+            asyncChain = mwResult as Promise<any>
+          }
+        } catch (err) {
+          handleAsyncError(err)
+          return
         }
-        this.exit(1)
-      })
+      }
+    }
+
+    const result = asyncChain
+      ? asyncChain.then(executeAction)
+      : executeAction()
+
+    // If the result is a promise, catch async errors
+    if (isPromiseLike(result)) {
+      (result as Promise<any>).catch(handleAsyncError)
     }
 
     return result