cli-forge 0.11.0 → 1.0.0

package/dist/lib/public-api.d.ts

@@ -1,4 +1,28 @@
-import { type ConfigurationFiles, OptionConfig, OptionConfigToType, ParsedArgs, EnvOptionConfig, ObjectOptionConfig, StringOptionConfig, NumberOptionConfig, BooleanOptionConfig, ArrayOptionConfig, ResolveProperties, AdditionalPropertiesType, WithOptional } from '@cli-forge/parser';
+import { type ConfigurationFiles, OptionConfig, OptionConfigToType, ParsedArgs, EnvOptionConfig, ObjectOptionConfig, StringOptionConfig, NumberOptionConfig, BooleanOptionConfig, ArrayOptionConfig, ResolveProperties, WithOptional, MakeUndefinedPropertiesOptional } from '@cli-forge/parser';
+import { InternalCLI } from './internal-cli';
+/**
+ * Extracts the command name from a Command type.
+ * Works with both CLI instances and command config objects.
+ */
+export type ExtractCommandName<T> = T extends CLI<any, any, any> ? T extends InternalCLI<any, any, any> ? string : string : T extends {
+    name: infer N;
+} ? N extends string ? N : string : string;
+/**
+ * Extracts the args type from a Command.
+ * Works with both CLI instances and command config objects.
+ */
+export type ExtractCommandArgs<T> = T extends CLI<infer A, any, any> ? A : T extends CLICommandOptions<any, infer A, any, any> ? A : ParsedArgs;
+/**
+ * Extracts the handler return type from a Command.
+ */
+export type ExtractCommandHandlerReturn<T> = T extends CLI<any, infer R, any> ? R : T extends CLICommandOptions<any, any, infer R, any> ? R : void;
+/**
+ * Converts a Command to its child CLI entry for TChildren tracking.
+ * TParentCLI is the parent CLI type that will be set as the child's TParent.
+ */
+export type CommandToChildEntry<T, TParentCLI = undefined> = {
+    [K in ExtractCommandName<T>]: CLI<ExtractCommandArgs<T>, ExtractCommandHandlerReturn<T>, {}, TParentCLI>;
+};
 /**
  * The interface for a CLI application or subcommands.
  *
@@ -18,37 +42,48 @@ import { type ConfigurationFiles, OptionConfig, OptionConfigToType, ParsedArgs,
  *   }).forge();
  * ```
  */
-export interface CLI<TArgs extends ParsedArgs = ParsedArgs> {
-    command<TCommandArgs extends TArgs>(cmd: Command<TArgs, TCommandArgs>): CLI<TArgs>;
+export interface CLI<TArgs extends ParsedArgs = ParsedArgs, THandlerReturn = void, TChildren = {}, TParent = undefined> {
+    command<TCommandArgs extends TArgs>(cmd: Command<TArgs, TCommandArgs>): CLI<TArgs, THandlerReturn, TChildren & (typeof cmd extends Command<TArgs, infer TCommandArgs, infer TCmdName> ? {
+        [key in TCmdName]: CLI<TCommandArgs, void, {}, CLI<TArgs, THandlerReturn, TChildren, TParent>>;
+    } : {}), TParent>;
     /**
      * Registers a new command with the CLI.
      * @param key What should the new command be called?
      * @param options Settings for the new command. See {@link CLICommandOptions}.
      * @returns Updated CLI instance with the new command registered.
      */
-    command<TCommandArgs extends TArgs>(key: string, options: CLICommandOptions<TArgs, TCommandArgs>): CLI<TArgs>;
-    /**
-     * Registers multiple subcommands with the CLI.
-     * @param commands Several commands to register. Can be the result of a call to {@link cli} or a configuration object.
-     */
-    commands(commands: Command[]): CLI<TArgs>;
+    command<TCommandArgs extends TArgs, TChildHandlerReturn, TKey extends string, TChildChildren = {}>(key: TKey, options: CLICommandOptions<TArgs, TCommandArgs, TChildHandlerReturn, TChildren, CLI<TArgs, THandlerReturn, TChildren, TParent>, TChildChildren>): CLI<TArgs, THandlerReturn, TChildren & {
+        [key in TKey]: CLI<TCommandArgs, TChildHandlerReturn, TChildChildren, CLI<TArgs, THandlerReturn, TChildren, TParent>>;
+    }, TParent>;
     /**
      * Registers multiple subcommands with the CLI.
      * @param commands Several commands to register. Can be the result of a call to {@link cli} or a configuration object.
+     * @returns Updated CLI instance with the commands registered and their types tracked in TChildren.
      */
-    commands(...commands: Command[]): CLI<TArgs>;
+    commands<C1 extends Command>(c1: C1): CLI<TArgs, THandlerReturn, TChildren & CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent>>, TParent>;
+    commands<C1 extends Command, C2 extends Command>(c1: C1, c2: C2): CLI<TArgs, THandlerReturn, TChildren & CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent>>, TParent>;
+    commands<C1 extends Command, C2 extends Command, C3 extends Command>(c1: C1, c2: C2, c3: C3): CLI<TArgs, THandlerReturn, TChildren & CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent>>, TParent>;
+    commands<C1 extends Command, C2 extends Command, C3 extends Command, C4 extends Command>(c1: C1, c2: C2, c3: C3, c4: C4): CLI<TArgs, THandlerReturn, TChildren & CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent>>, TParent>;
+    commands<C1 extends Command, C2 extends Command, C3 extends Command, C4 extends Command, C5 extends Command>(c1: C1, c2: C2, c3: C3, c4: C4, c5: C5): CLI<TArgs, THandlerReturn, TChildren & CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C5, CLI<TArgs, THandlerReturn, TChildren, TParent>>, TParent>;
+    commands<C1 extends Command, C2 extends Command, C3 extends Command, C4 extends Command, C5 extends Command, C6 extends Command>(c1: C1, c2: C2, c3: C3, c4: C4, c5: C5, c6: C6): CLI<TArgs, THandlerReturn, TChildren & CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C5, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C6, CLI<TArgs, THandlerReturn, TChildren, TParent>>, TParent>;
+    commands<C1 extends Command, C2 extends Command, C3 extends Command, C4 extends Command, C5 extends Command, C6 extends Command, C7 extends Command>(c1: C1, c2: C2, c3: C3, c4: C4, c5: C5, c6: C6, c7: C7): CLI<TArgs, THandlerReturn, TChildren & CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C5, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C6, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C7, CLI<TArgs, THandlerReturn, TChildren, TParent>>, TParent>;
+    commands<C1 extends Command, C2 extends Command, C3 extends Command, C4 extends Command, C5 extends Command, C6 extends Command, C7 extends Command, C8 extends Command>(c1: C1, c2: C2, c3: C3, c4: C4, c5: C5, c6: C6, c7: C7, c8: C8): CLI<TArgs, THandlerReturn, TChildren & CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C5, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C6, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C7, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C8, CLI<TArgs, THandlerReturn, TChildren, TParent>>, TParent>;
+    commands<C1 extends Command, C2 extends Command, C3 extends Command, C4 extends Command, C5 extends Command, C6 extends Command, C7 extends Command, C8 extends Command, C9 extends Command>(c1: C1, c2: C2, c3: C3, c4: C4, c5: C5, c6: C6, c7: C7, c8: C8, c9: C9): CLI<TArgs, THandlerReturn, TChildren & CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C5, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C6, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C7, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C8, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C9, CLI<TArgs, THandlerReturn, TChildren, TParent>>, TParent>;
+    commands<C1 extends Command, C2 extends Command, C3 extends Command, C4 extends Command, C5 extends Command, C6 extends Command, C7 extends Command, C8 extends Command, C9 extends Command, C10 extends Command>(c1: C1, c2: C2, c3: C3, c4: C4, c5: C5, c6: C6, c7: C7, c8: C8, c9: C9, c10: C10): CLI<TArgs, THandlerReturn, TChildren & CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C5, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C6, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C7, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C8, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C9, CLI<TArgs, THandlerReturn, TChildren, TParent>> & CommandToChildEntry<C10, CLI<TArgs, THandlerReturn, TChildren, TParent>>, TParent>;
+    commands(commands: Command[]): CLI<TArgs, THandlerReturn, TChildren, TParent>;
+    commands(...commands: Command[]): CLI<TArgs, THandlerReturn, TChildren, TParent>;
     /**
      * Register's a configuration provider for the CLI. See {@link ConfigurationProviders} for built-in providers.
      *
      * @param provider Provider to register.
      */
-    config(provider: ConfigurationFiles.ConfigurationProvider<TArgs>): CLI<TArgs>;
+    config(provider: ConfigurationFiles.ConfigurationProvider<TArgs>): CLI<TArgs, THandlerReturn, TChildren, TParent>;
     /**
      * Enables the ability to run CLI commands that contain subcommands as an interactive shell.
      * This presents as a small shell that only knows the current command and its subcommands.
      * Any flags already consumed by the command will be passed to every subcommand invocation.
      */
-    enableInteractiveShell(): CLI<TArgs>;
+    enableInteractiveShell(): CLI<TArgs, THandlerReturn, TChildren, TParent>;
     /**
      * Registers a custom global error handler for the CLI. This handler will be called when an error is thrown
      * during the execution of the CLI and not otherwise handled. Error handlers should re-throw the error if they
@@ -57,7 +92,7 @@ export interface CLI<TArgs extends ParsedArgs = ParsedArgs> {
      * @param handler Typically called with an Error object, but you should be prepared to handle any type of error.
      * @param actions Actions that can be taken by the error handler. Prefer using these over process.exit for better support of interactive shells.
      */
-    errorHandler(handler: ErrorHandler): CLI<TArgs>;
+    errorHandler(handler: ErrorHandler): CLI<TArgs, THandlerReturn, TChildren, TParent>;
     /**
      * Registers a new option for the CLI command. This option will be accessible
      * within the command handler, as well as any subcommands.
@@ -68,24 +103,24 @@ export interface CLI<TArgs extends ParsedArgs = ParsedArgs> {
      */
     option<TOption extends string, TCoerce, const TProps extends Record<string, {
         type: string;
-    }>, TAdditionalProps extends false | 'string' | 'number' | 'boolean' = false>(name: TOption, config: ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>): CLI<TArgs & {
-        [key in TOption]: WithOptional<unknown extends TCoerce ? ResolveProperties<TProps> & AdditionalPropertiesType<TAdditionalProps> : TCoerce, ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>>;
-    }>;
-    option<TOption extends string, const TConfig extends StringOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & {
+    }>>(name: TOption, config: ObjectOptionConfig<TCoerce, TProps>): CLI<TArgs & MakeUndefinedPropertiesOptional<{
+        [key in TOption]: WithOptional<unknown extends TCoerce ? ResolveProperties<TProps> : TCoerce, ObjectOptionConfig<TCoerce, TProps>>;
+    }>, THandlerReturn, TChildren, TParent>;
+    option<TOption extends string, const TConfig extends StringOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & MakeUndefinedPropertiesOptional<{
         [key in TOption]: OptionConfigToType<TConfig>;
-    }>;
-    option<TOption extends string, const TConfig extends NumberOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & {
+    }>, THandlerReturn, TChildren, TParent>;
+    option<TOption extends string, const TConfig extends NumberOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & MakeUndefinedPropertiesOptional<{
         [key in TOption]: OptionConfigToType<TConfig>;
-    }>;
-    option<TOption extends string, const TConfig extends BooleanOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & {
+    }>, THandlerReturn, TChildren, TParent>;
+    option<TOption extends string, const TConfig extends BooleanOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & MakeUndefinedPropertiesOptional<{
         [key in TOption]: OptionConfigToType<TConfig>;
-    }>;
-    option<TOption extends string, const TConfig extends ArrayOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & {
+    }>, THandlerReturn, TChildren, TParent>;
+    option<TOption extends string, const TConfig extends ArrayOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & MakeUndefinedPropertiesOptional<{
         [key in TOption]: OptionConfigToType<TConfig>;
-    }>;
-    option<TOption extends string, const TOptionConfig extends OptionConfig<any, any, any, any>>(name: TOption, config: TOptionConfig): CLI<TArgs & {
+    }>, THandlerReturn, TChildren, TParent>;
+    option<TOption extends string, const TOptionConfig extends OptionConfig<any, any, any>>(name: TOption, config: TOptionConfig): CLI<TArgs & MakeUndefinedPropertiesOptional<{
         [key in TOption]: OptionConfigToType<TOptionConfig>;
-    }>;
+    }>, THandlerReturn, TChildren, TParent>;
     /**
      * Registers a new positional argument for the CLI command. This argument will be accessible
      * within the command handler, as well as any subcommands.
@@ -95,63 +130,63 @@ export interface CLI<TArgs extends ParsedArgs = ParsedArgs> {
      */
     positional<TOption extends string, TCoerce, const TProps extends Record<string, {
         type: string;
-    }>, TAdditionalProps extends false | 'string' | 'number' | 'boolean' = false>(name: TOption, config: ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>): CLI<TArgs & {
-        [key in TOption]: WithOptional<unknown extends TCoerce ? ResolveProperties<TProps> & AdditionalPropertiesType<TAdditionalProps> : TCoerce, ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>>;
-    }>;
-    positional<TOption extends string, const TConfig extends StringOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & {
+    }>>(name: TOption, config: ObjectOptionConfig<TCoerce, TProps>): CLI<TArgs & MakeUndefinedPropertiesOptional<{
+        [key in TOption]: WithOptional<unknown extends TCoerce ? ResolveProperties<TProps> : TCoerce, ObjectOptionConfig<TCoerce, TProps>>;
+    }>, THandlerReturn, TChildren, TParent>;
+    positional<TOption extends string, const TConfig extends StringOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & MakeUndefinedPropertiesOptional<{
         [key in TOption]: OptionConfigToType<TConfig>;
-    }>;
-    positional<TOption extends string, const TConfig extends NumberOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & {
+    }>, THandlerReturn, TChildren, TParent>;
+    positional<TOption extends string, const TConfig extends NumberOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & MakeUndefinedPropertiesOptional<{
         [key in TOption]: OptionConfigToType<TConfig>;
-    }>;
-    positional<TOption extends string, const TConfig extends BooleanOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & {
+    }>, THandlerReturn, TChildren, TParent>;
+    positional<TOption extends string, const TConfig extends BooleanOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & MakeUndefinedPropertiesOptional<{
         [key in TOption]: OptionConfigToType<TConfig>;
-    }>;
-    positional<TOption extends string, const TConfig extends ArrayOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & {
+    }>, THandlerReturn, TChildren, TParent>;
+    positional<TOption extends string, const TConfig extends ArrayOptionConfig<any, any>>(name: TOption, config: TConfig): CLI<TArgs & MakeUndefinedPropertiesOptional<{
         [key in TOption]: OptionConfigToType<TConfig>;
-    }>;
-    positional<TOption extends string, const TOptionConfig extends OptionConfig<any, any, any, any>>(name: TOption, config: TOptionConfig): CLI<TArgs & {
+    }>, THandlerReturn, TChildren, TParent>;
+    positional<TOption extends string, const TOptionConfig extends OptionConfig<any, any, any>>(name: TOption, config: TOptionConfig): CLI<TArgs & MakeUndefinedPropertiesOptional<{
         [key in TOption]: OptionConfigToType<TOptionConfig>;
-    }>;
+    }>, THandlerReturn, TChildren, TParent>;
     /**
      * Adds support for reading CLI options from environment variables.
      * @param prefix The prefix to use when looking up environment variables. Defaults to the command name.
      */
-    env(prefix?: string): CLI<TArgs>;
-    env(options: EnvOptionConfig): CLI<TArgs>;
+    env(prefix?: string): CLI<TArgs, THandlerReturn, TChildren, TParent>;
+    env(options: EnvOptionConfig): CLI<TArgs, THandlerReturn, TChildren, TParent>;
     /**
      * Sets a group of options as mutually exclusive. If more than one option is provided, there will be a validation error.
      * @param options The options that should be mutually exclusive.
      */
-    conflicts(...options: [string, string, ...string[]]): CLI<TArgs>;
+    conflicts(...options: [string, string, ...string[]]): CLI<TArgs, THandlerReturn, TChildren, TParent>;
     /**
      * Sets a group of options as mutually inclusive. If one option is provided, all other options must also be provided.
      * @param option The option that implies the other options.
      * @param impliedOptions The options which become required when the option is provided.
      */
-    implies(option: string, ...impliedOptions: string[]): CLI<TArgs>;
+    implies(option: string, ...impliedOptions: string[]): CLI<TArgs, THandlerReturn, TChildren, TParent>;
     /**
      * Requires a command to be provided when executing the CLI. Useful if your parent command
      * cannot be executed on its own.
      * @returns Updated CLI instance.
      */
-    demandCommand(): CLI<TArgs>;
+    demandCommand(): CLI<TArgs, THandlerReturn, TChildren, TParent>;
     /**
      * Sets the usage text for the CLI. This text will be displayed in place of the default usage text
      * @param usageText Text displayed in place of the default usage text for `--help` and in generated docs.
      */
-    usage(usageText: string): CLI<TArgs>;
+    usage(usageText: string): CLI<TArgs, THandlerReturn, TChildren, TParent>;
     /**
      * Sets the description for the CLI. This text will be displayed in the help text and generated docs.
      * @param examples Examples to display in the help text and generated docs.
      */
-    examples(...examples: string[]): CLI<TArgs>;
+    examples(...examples: string[]): CLI<TArgs, THandlerReturn, TChildren, TParent>;
     /**
      * Allows overriding the version displayed when passing `--version`. Defaults to crawling
      * the file system to get the package.json of the currently executing command.
      * @param override
      */
-    version(override?: string): CLI<TArgs>;
+    version(override?: string): CLI<TArgs, THandlerReturn, TChildren, TParent>;
     /**
      * Prints help text to stdout.
      */
@@ -160,19 +195,100 @@ export interface CLI<TArgs extends ParsedArgs = ParsedArgs> {
         label: string;
         keys: (keyof TArgs)[];
         sortOrder: number;
-    }): CLI<TArgs>;
-    group(label: string, keys: (keyof TArgs)[]): CLI<TArgs>;
-    middleware<TArgs2>(callback: MiddlewareFunction<TArgs, TArgs2>): CLI<TArgs2 extends void ? TArgs : TArgs & TArgs2>;
+    }): CLI<TArgs, THandlerReturn, TChildren, TParent>;
+    group(label: string, keys: (keyof TArgs)[]): CLI<TArgs, THandlerReturn, TChildren, TParent>;
+    middleware<TArgs2>(callback: MiddlewareFunction<TArgs, TArgs2>): CLI<TArgs2 extends void ? TArgs : TArgs & TArgs2, THandlerReturn, TChildren, TParent>;
     /**
      * Parses argv and executes the CLI
      * @param args argv. Defaults to process.argv.slice(2)
      * @returns Promise that resolves when the handler completes.
      */
     forge(args?: string[]): Promise<TArgs>;
+    /**
+     * Returns the typed children commands registered with this CLI.
+     * The return type is determined by the commands registered via `command()` or `commands()`.
+     *
+     * @example
+     * ```ts
+     * const app = cli('app')
+     *   .command('init', { ... })
+     *   .command('build', { ... });
+     *
+     * const children = app.getChildren();
+     * // children.init and children.build are typed CLI instances
+     * const initHandler = children.init.getHandler();
+     * ```
+     */
+    getChildren(): TChildren;
+    /**
+     * Returns the parent CLI instance, if this command was registered as a subcommand.
+     * Returns undefined for root-level CLI instances.
+     *
+     * @example
+     * ```ts
+     * const build = cli('build', {
+     *   handler: (args, ctx) => {
+     *     const parent = ctx.command.getParent();
+     *     const siblings = parent?.getChildren();
+     *     // Access sibling commands
+     *   }
+     * });
+     * ```
+     */
+    getParent(): TParent;
+    /**
+     * Returns a programmatic SDK for invoking this CLI and its subcommands.
+     * The SDK provides typed function calls instead of argv parsing.
+     *
+     * @example
+     * ```ts
+     * const myCLI = cli('my-app')
+     *   .option('verbose', { type: 'boolean' })
+     *   .command('build', {
+     *     builder: (cmd) => cmd.option('watch', { type: 'boolean' }),
+     *     handler: (args) => ({ success: true, files: ['a.js'] })
+     *   });
+     *
+     * const sdk = myCLI.sdk();
+     *
+     * // Invoke root command (if it has a handler)
+     * await sdk({ verbose: true });
+     *
+     * // Invoke subcommand with typed args
+     * const result = await sdk.build({ watch: true });
+     * console.log(result.files);       // ['a.js']
+     * console.log(result.$args.watch); // true
+     *
+     * // Use CLI-style args for -- support
+     * await sdk.build(['--watch', '--', 'extra-arg']);
+     * ```
+     *
+     * @returns An SDK object that is callable (if this command has a handler)
+     *          and has properties for each subcommand.
+     */
+    sdk(): SDKCommand<TArgs, THandlerReturn, TChildren>;
+    /**
+     * Returns the builder function for this command as a composable builder.
+     * The returned function can be used with `chain` to compose multiple builders.
+     *
+     * @example
+     * ```ts
+     * const siblings = args.getParent().getChildren();
+     * const withBuildArgs = siblings.build.getBuilder()!;
+     * const withServeArgs = siblings.serve.getBuilder()!;
+     * return chain(args, withBuildArgs, withServeArgs);
+     * ```
+     */
+    getBuilder(): (<TInit extends ParsedArgs, TInitHandlerReturn, TInitChildren, TInitParent>(parser: CLI<TInit, TInitHandlerReturn, TInitChildren, TInitParent>) => CLI<TInit & TArgs, TInitHandlerReturn, TInitChildren & TChildren, TInitParent>) | undefined;
+    getHandler(): ((args: Omit<TArgs, keyof ParsedArgs>) => THandlerReturn) | undefined;
 }
-export interface CLIHandlerContext {
-    command: CLI<any>;
+export interface CLIHandlerContext<TChildren = {}, TParent = any> {
+    command: CLI<any, any, TChildren, TParent>;
 }
+/**
+ * Extracts the TChildren type parameter from a CLI type.
+ */
+export type ExtractCLIChildren<T> = T extends CLI<any, any, infer C, any> ? C : {};
 /**
  * Represents the configuration needed to create a CLI command.
  */
@@ -184,7 +300,15 @@ TInitial extends ParsedArgs,
 /**
  * The type of the arguments that are registered after `builder` is invoked, and the type that is passed to the handler.
  */
-TArgs extends TInitial = TInitial> {
+TArgs extends TInitial = TInitial, THandlerReturn = void, 
+/**
+ * The children commands that exist before the builder runs.
+ */
+TInitialChildren = {}, TParent = any, 
+/**
+ * The children commands after the builder runs (includes TInitialChildren plus any added by builder).
+ */
+TChildren = {}> {
     /**
      * If set the command will be registered under the provided name and any aliases.
      *
@@ -199,13 +323,13 @@ TArgs extends TInitial = TInitial> {
      * The command builder. This function is called before the command is executed, and is used to register options and positional parameters.
      * @param parser The parser instance to register options and positionals with.
      */
-    builder?: (parser: CLI<TInitial>) => CLI<TArgs>;
+    builder?: (parser: CLI<TInitial, any, TInitialChildren, TParent>) => CLI<TArgs, any, TChildren, any>;
     /**
      * The command handler. This function is called when the command is executed.
      * @param args The parsed arguments.
      * @param context Context for the handler. Contains the command instance.
      */
-    handler?: (args: TArgs, context: CLIHandlerContext) => void | Promise<void>;
+    handler?: (args: NoInfer<TArgs>, context: CLIHandlerContext<NoInfer<TChildren>, TParent>) => THandlerReturn;
     /**
      * The usage text for the command. This text will be displayed in place of the default usage text in the help text and generated docs.
      */
@@ -223,8 +347,8 @@ TArgs extends TInitial = TInitial> {
      */
     epilogue?: string;
 }
-export type Command<TInitial extends ParsedArgs = any, TArgs extends TInitial = TInitial> = ({
-    name: string;
+export type Command<TInitial extends ParsedArgs = any, TArgs extends TInitial = TInitial, TCommandName extends string = string> = ({
+    name: TCommandName;
 } & CLICommandOptions<TInitial, TArgs>) | CLI<TArgs>;
 /**
  * Error Handler for CLI applications. Error handlers should re-throw the error if they cannot handle it.
@@ -239,12 +363,51 @@ export type ErrorHandler = (e: unknown, actions: {
      */
     exit: (code?: number) => void;
 }) => void;
+export type UnknownCLI = CLI<ParsedArgs, any, any, any>;
 export type MiddlewareFunction<TArgs extends ParsedArgs, TArgs2> = (args: TArgs) => TArgs2 | Promise<TArgs2>;
+/**
+ * Result type that conditionally includes $args.
+ * Only attaches $args when result is an object type.
+ * Uses Awaited<T> to handle async handlers that return Promise<U>.
+ */
+export type SDKResult<TArgs, THandlerReturn> = Awaited<THandlerReturn> extends object ? Awaited<THandlerReturn> & {
+    $args: TArgs;
+} : Awaited<THandlerReturn>;
+/**
+ * The callable signature for a command with a handler.
+ * Supports both object-style args (typed, skips validation) and
+ * string array args (CLI-style, full validation pipeline).
+ */
+export type SDKInvokable<TArgs, THandlerReturn> = {
+    /**
+     * Invoke the command with typed object args.
+     * Skips validation (TypeScript handles it), applies defaults, runs middleware.
+     */
+    (args?: Partial<Omit<TArgs, 'unmatched' | '--'>>): Promise<SDKResult<TArgs, THandlerReturn>>;
+    /**
+     * Invoke the command with CLI-style string args.
+     * Runs full pipeline: parse → validate → middleware → handler.
+     * Use this when you need to pass `--` extra args.
+     */
+    (args: string[]): Promise<SDKResult<TArgs, THandlerReturn>>;
+};
+/**
+ * Recursively builds SDK type from TChildren.
+ * Each child command becomes a property on the SDK object.
+ */
+export type SDKChildren<TChildren> = {
+    [K in keyof TChildren]: TChildren[K] extends CLI<infer A, infer R, infer C, infer _P> ? SDKCommand<A, R, C> : never;
+};
+/**
+ * A single SDK command - callable if it has a handler, with nested children as properties.
+ * Container commands (no handler) are not callable but still provide access to children.
+ */
+export type SDKCommand<TArgs, THandlerReturn, TChildren> = SDKInvokable<TArgs, THandlerReturn> & SDKChildren<TChildren>;
 /**
  * Constructs a CLI instance. See {@link CLI} for more information.
  * @param name Name for the top level CLI
  * @param rootCommandConfiguration Configuration used when running the bare CLI. e.g. npx my-cli, rather than npx my-cli [cmd]
  * @returns A {@link CLI} instance.
  */
-export declare function cli<TArgs extends ParsedArgs>(name: string, rootCommandConfiguration?: CLICommandOptions<ParsedArgs, TArgs>): CLI<TArgs>;
+export declare function cli<TArgs extends ParsedArgs, THandlerReturn = void, TChildren = {}, TName extends string = string>(name: TName, rootCommandConfiguration?: CLICommandOptions<ParsedArgs, TArgs, THandlerReturn, {}, any, TChildren>): CLI<TArgs, THandlerReturn, TChildren>;
 export default cli;

package/dist/lib/public-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"public-api.js","sourceRoot":"","sources":["../../src/lib/public-api.ts"],"names":[],"mappings":";;AAybA,kBAKC;AA9aD,iDAA6C;AAma7C;;;;;GAKG;AACH,SAAgB,GAAG,CACjB,IAAY,EACZ,wBAA+D;IAE/D,OAAO,IAAI,0BAAW,CAAC,IAAI,EAAE,wBAAwB,CAAsB,CAAC;AAC9E,CAAC;AAED,kBAAe,GAAG,CAAC"}
+{"version":3,"file":"public-api.js","sourceRoot":"","sources":["../../src/lib/public-api.ts"],"names":[],"mappings":";;AAk/BA,kBAsBC;AAv/BD,iDAA6C;AA29B7C;;;;;GAKG;AACH,SAAgB,GAAG,CAOjB,IAAW,EACX,wBAOC;IAED,OAAO,IAAI,0BAAW,CAAC,IAAI,EAAE,wBAA+B,CAI3D,CAAC;AACJ,CAAC;AAED,kBAAe,GAAG,CAAC"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "cli-forge",
-  "version": "0.11.0",
+  "version": "1.0.0",
   "dependencies": {
     "tslib": "^2.3.0",
-    "@cli-forge/parser": "0.11.0"
+    "@cli-forge/parser": "1.0.0"
   },
   "peerDependencies": {
     "markdown-factory": "^0.2.0",
@@ -23,10 +23,14 @@
       "optional": true
     }
   },
+  "devDependencies": {
+    "vite": "^5.4.0"
+  },
   "type": "commonjs",
   "main": "./dist/index.js",
   "typings": "./dist/index.d.ts",
   "license": "ISC",
+  "homepage": "https://craigory.dev/cli-forge/",
   "repository": {
     "type": "git",
     "directory": "packages/cli-forge",
@@ -38,7 +42,8 @@
   "exports": {
     ".": {
       "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
     "./middleware": {
       "require": "./dist/middleware.js",

package/src/bin/commands/generate-documentation.ts

@@ -47,7 +47,7 @@ export function withGenerateDocumentationArgs<T extends ParsedArgs>(
     });
 }
 
-export const generateDocumentationCommand: CLI = cli('generate-documentation', {
+export const generateDocumentationCommand: CLI<any, any, any> = cli('generate-documentation', {
   description: 'Generate documentation for the given CLI',
   examples: [
     'cli-forge generate-documentation ./bin/my-cli',

package/src/index.ts

@@ -3,5 +3,10 @@ export * from './lib/public-api';
 export { default } from './lib/public-api';
 export { chain } from '@cli-forge/parser';
 export { makeComposableBuilder } from './lib/composable-builder';
+export type {
+  ComposableBuilder,
+  ExtractArgs,
+  ExtractChildren,
+} from './lib/composable-builder';
 export type { ArgumentsOf } from './lib/utils';
 export { ConfigurationProviders } from './lib/configuration-providers';

package/src/lib/composable-builder.ts

@@ -1,9 +1,57 @@
 import { ParsedArgs } from '@cli-forge/parser';
 import { CLI } from './public-api';
 
-export function makeComposableBuilder<T2 extends ParsedArgs>(
-  fn: (init: CLI<ParsedArgs>) => CLI<T2>
+/**
+ * Extracts the TChildren type parameter from a CLI type.
+ */
+export type ExtractChildren<T> = T extends CLI<any, any, infer C, any>
+  ? C
+  : never;
+
+/**
+ * Extracts the TArgs type parameter from a CLI type.
+ */
+export type ExtractArgs<T> = T extends CLI<infer A, any, any, any> ? A : never;
+
+/**
+ * Type for a composable builder function that transforms a CLI.
+ * Used with `chain` to compose multiple builders.
+ */
+export type ComposableBuilder<
+  TArgs2 extends ParsedArgs,
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  TAddedChildren = {}
+> = <TInit extends ParsedArgs, THandlerReturn, TChildren, TParent>(
+  init: CLI<TInit, THandlerReturn, TChildren, TParent>
+) => CLI<TInit & TArgs2, THandlerReturn, TChildren & TAddedChildren, TParent>;
+
+/**
+ * Creates a composable builder function that can be used with `chain`.
+ * Can be used to add options, commands, or any other CLI modifications.
+ * Children added by the builder function are properly tracked in the type.
+ *
+ * @typeParam TArgs2 - The args type after the builder runs
+ * @typeParam TChildren2 - The children type added by the builder
+ */
+export function makeComposableBuilder<
+  TArgs2 extends ParsedArgs,
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  TChildren2 = {}
+>(
+  fn: (
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    init: CLI<ParsedArgs, any, {}, any>
+  ) => CLI<TArgs2, any, TChildren2, any>
 ) {
-  return <TInit extends ParsedArgs>(init: CLI<TInit>) =>
-    fn(init) as CLI<TInit & T2>;
+  return <TInit extends ParsedArgs, THandlerReturn, TChildren, TParent>(
+    init: CLI<TInit, THandlerReturn, TChildren, TParent>
+  ) =>
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    fn(init as unknown as CLI<ParsedArgs, any, {}, any>) as unknown as CLI<
+      TInit & TArgs2,
+      THandlerReturn,
+      TChildren & TChildren2,
+      TParent
+    >;
 }
+

package/src/lib/documentation.spec.ts

@@ -1,3 +1,4 @@
+import { it, describe, expect } from 'vitest';
 import { InternalCLI } from './internal-cli';
 import { generateDocumentation } from './documentation';
 import cli from './public-api';

package/src/lib/documentation.ts

@@ -54,7 +54,7 @@ export function generateDocumentation(
     // The cli instance here is typed a bit too well
     // for the builder function, so we need to cast it to
     // a more generic form.
-    cli.configuration.builder(cli as CLI);
+    cli.configuration.builder(cli as unknown as CLI);
   }
   const parser = cli.getParser();
 

package/src/lib/internal-cli.spec.ts

@@ -1,3 +1,4 @@
+import { it, describe, expect, afterEach } from 'vitest';
 import { InternalCLI } from './internal-cli';
 import { cli } from './public-api';
 
@@ -77,11 +78,11 @@ describe('cliForge', () => {
         alias: ['$0'],
         builder: (argv) => argv,
         handler: makeHandler('bar'),
-      }) as InternalCLI;
-    await test.clone().forge(['f']);
-    await test.clone().forge(['foo']);
-    await test.clone().forge(['bar']);
-    await test.clone().forge([]);
+      }) as Partial<InternalCLI>;
+    await test.clone?.().forge(['f']);
+    await test.clone?.().forge(['foo']);
+    await test.clone?.().forge(['bar']);
+    await test.clone?.().forge([]);
     expect(ran).toMatchInlineSnapshot(`
       {
         "bar": 2,