effect 4.0.0-beta.65 → 4.0.0-beta.67

package/dist/unstable/cli/Command.d.ts

@@ -1,4 +1,32 @@
 /**
+ * The `Command` module provides the core building block for defining and
+ * running Effect-based command-line applications. A `Command` combines a name,
+ * typed flags and positional arguments, optional subcommands, metadata for help
+ * output, and an effectful handler.
+ *
+ * **Common tasks**
+ *
+ * - Create commands with {@link make}
+ * - Add handlers with {@link withHandler}
+ * - Build nested command trees with {@link withSubcommands}
+ * - Share parent flags with subcommands using {@link withSharedFlags}
+ * - Add command-scoped global flags with {@link withGlobalFlags}
+ * - Attach help metadata with {@link withDescription}, {@link withShortDescription},
+ *   {@link withAlias}, and {@link withExamples}
+ * - Provide handler dependencies with {@link provide}, {@link provideSync},
+ *   {@link provideEffect}, and {@link provideEffectDiscard}
+ * - Execute commands with {@link run} or test them with {@link runWith}
+ *
+ * **Gotchas**
+ *
+ * - `withSharedFlags` accepts only flags, not positional arguments, and the
+ *   parsed values are available to descendants by yielding the parent command.
+ * - Shared flags may be written before or after the selected subcommand name.
+ * - Duplicate flags across command scopes are rejected so parsing and help
+ *   output remain unambiguous.
+ * - `runWith` is the preferred entry point for tests because it accepts an
+ *   explicit argument array instead of reading from the `Stdio` service.
+ *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts";
@@ -8,10 +36,9 @@ import type * as FileSystem from "../../FileSystem.ts";
 import type * as Layer from "../../Layer.ts";
 import * as Option from "../../Option.ts";
 import type * as Path from "../../Path.ts";
-import type { Pipeable } from "../../Pipeable.ts";
 import * as Stdio from "../../Stdio.ts";
 import * as Terminal from "../../Terminal.ts";
-import type { NoInfer, Simplify } from "../../Types.ts";
+import type { Contravariant, Covariant, NoInfer, Simplify } from "../../Types.ts";
 import type { ChildProcessSpawner } from "../process/ChildProcessSpawner.ts";
 import * as CliError from "./CliError.ts";
 import * as GlobalFlag from "./GlobalFlag.ts";
@@ -26,7 +53,8 @@ import * as Param from "./Param.ts";
  * - Handler function for execution
  * - Optional subcommands for hierarchical structures
  *
- * @example
+ * **Example** (Defining CLI commands)
+ *
  * ```ts
  * import { Console } from "effect"
  * import { Argument, Command, Flag } from "effect/unstable/cli"
@@ -59,11 +87,11 @@ import * as Param from "./Param.ts";
  * }, (config) => Console.log(`Hello, ${config.name}!`))
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
-export interface Command<Name extends string, Input, ContextInput = {}, E = never, R = never> extends Pipeable, Effect.Yieldable<Command<Name, Input, ContextInput, E, R>, ContextInput, never, CommandContext<Name>> {
-    readonly [TypeId]: typeof TypeId;
+export interface Command<in out Name extends string, in Input, out ContextInput = {}, out E = never, out R = never> extends Effect.Effect<ContextInput, never, CommandContext<Name>> {
+    readonly [TypeId]: Command.Variance<Input, E, R>;
     /**
      * The name of the command.
      */
@@ -97,14 +125,31 @@ export interface Command<Name extends string, Input, ContextInput = {}, E = neve
     readonly annotations: Context.Context<never>;
 }
 /**
+ * Companion namespace containing type-level helpers and configuration shapes
+ * used by `Command`.
+ *
  * @since 4.0.0
  */
 export declare namespace Command {
     /**
-     * Represents a concrete usage example for a command.
+     * Type-level variance marker for `Command`.
      *
+     * The parsed input type is contravariant, while the command error and service
+     * requirement types are covariant.
+     *
+     * @category models
      * @since 4.0.0
+     */
+    interface Variance<in Input, out E, out R> {
+        readonly Input: Contravariant<Input>;
+        readonly E: Covariant<E>;
+        readonly R: Covariant<R>;
+    }
+    /**
+     * Represents a concrete usage example for a command.
+     *
      * @category models
+     * @since 4.0.0
      */
     interface Example {
         readonly command: string;
@@ -118,7 +163,8 @@ export declare namespace Command {
      * - Nested configuration objects for organization
      * - Arrays of parameters for repeated elements
      *
-     * @example
+     * **Example** (Configuring command input)
+     *
      * ```ts
      * import { Argument, Flag } from "effect/unstable/cli"
      * import type * as CliCommand from "effect/unstable/cli/Command"
@@ -143,8 +189,8 @@ export declare namespace Command {
      * }
      * ```
      *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     interface Config {
         readonly [key: string]: Param.Param<Param.ParamKind, any> | ReadonlyArray<Param.Param<Param.ParamKind, any> | Config> | Config;
@@ -154,8 +200,8 @@ export declare namespace Command {
      *
      * Only flags are allowed here; arguments are intentionally excluded.
      *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     interface FlagConfig {
         readonly [key: string]: Param.Param<typeof Param.flagKind, any> | ReadonlyArray<Param.Param<typeof Param.flagKind, any> | FlagConfig> | FlagConfig;
@@ -164,7 +210,6 @@ export declare namespace Command {
      * Utilities for working with command configurations.
      *
      * @since 4.0.0
-     * @category models
      */
     namespace Config {
         /**
@@ -173,7 +218,8 @@ export declare namespace Command {
          * This type utility extracts the final configuration type that handlers will receive,
          * preserving the nested structure while converting Param types to their values.
          *
-         * @example
+         * **Example** (Inferring command input)
+         *
          * ```ts
          * import { Flag } from "effect/unstable/cli"
          * import type * as CliCommand from "effect/unstable/cli/Command"
@@ -196,8 +242,8 @@ export declare namespace Command {
          * // }
          * ```
          *
-         * @since 4.0.0
          * @category models
+         * @since 4.0.0
          */
         type Infer<A extends Config> = Simplify<{
             readonly [Key in keyof A]: InferValue<A[Key]>;
@@ -205,8 +251,8 @@ export declare namespace Command {
         /**
          * Helper type utility for recursively inferring types from Config values.
          *
-         * @since 4.0.0
          * @category models
+         * @since 4.0.0
          */
         type InferValue<A> = A extends ReadonlyArray<any> ? {
             readonly [Key in keyof A]: InferValue<A[Key]>;
@@ -215,15 +261,27 @@ export declare namespace Command {
     /**
      * Represents any Command regardless of its type parameters.
      *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
-    type Any = Command<string, unknown, unknown, unknown, unknown>;
+    interface Any extends Effect.Effect<any, never, any> {
+        readonly [TypeId]: any;
+        readonly name: string;
+        readonly description: string | undefined;
+        readonly shortDescription: string | undefined;
+        readonly alias: string | undefined;
+        readonly examples: ReadonlyArray<Command.Example>;
+        readonly subcommands: ReadonlyArray<{
+            readonly group: string | undefined;
+            readonly commands: NonEmptyReadonlyArray<Command.Any>;
+        }>;
+        readonly annotations: Context.Context<never>;
+    }
     /**
      * A grouped set of subcommands used by `Command.withSubcommands`.
      *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     interface SubcommandGroup<Commands extends ReadonlyArray<Any> = ReadonlyArray<Any>> {
         readonly group: string;
@@ -232,23 +290,27 @@ export declare namespace Command {
     /**
      * Entry type accepted by `Command.withSubcommands`.
      *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     type SubcommandEntry = Any | SubcommandGroup<ReadonlyArray<Any>>;
 }
 /**
- * The environment required by CLI commands, including file system and path operations.
+ * Services required by CLI parsing and execution.
+ *
+ * This includes file-system and path services for arguments, terminal and
+ * stdio services for running commands, and child-process spawning for
+ * process-related CLI features.
  *
- * @since 4.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal | ChildProcessSpawner | Stdio.Stdio;
 /**
  * A utility type to extract the error type from a `Command`.
  *
- * @since 4.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type Error<C> = C extends Command<infer _Name, infer _Input, infer _ContextInput, infer _Error, infer _Requirements> ? _Error : never;
 /**
@@ -259,7 +321,8 @@ export type Error<C> = C extends Command<infer _Name, infer _Input, infer _Conte
  * Effect's service system - each command automatically creates a service that provides
  * its parsed input to child commands.
  *
- * @example
+ * **Example** (Accessing parent command context)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
@@ -286,8 +349,8 @@ export type Error<C> = C extends Command<infer _Name, infer _Input, infer _Conte
  * // Usage: app --verbose --config prod.json deploy --target staging
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface CommandContext<Name extends string> {
     readonly _: unique symbol;
@@ -296,8 +359,8 @@ export interface CommandContext<Name extends string> {
 /**
  * Represents the parsed tokens from command-line input before validation.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ParsedTokens {
     readonly flags: Record<string, ReadonlyArray<string>>;
@@ -309,18 +372,22 @@ export interface ParsedTokens {
     }>;
 }
 /**
- * @since 4.0.0
+ * Returns `true` if the provided value is a `Command`.
+ *
  * @category Guards
+ * @since 4.0.0
  */
 export declare const isCommand: (u: unknown) => u is Command.Any;
 /**
- * Creates a Command from a name, optional config, optional handler function, and optional description.
+ * Creates a `Command` from a name, an optional configuration, and an optional
+ * handler.
  *
- * The make function is the primary constructor for CLI commands. It provides multiple overloads
- * to support different patterns of command creation, from simple commands with no configuration
- * to complex commands with nested configurations and error handling.
+ * Use `withDescription` and related metadata combinators to add help text. The
+ * overloads support simple commands, configured commands, and commands with
+ * effectful handlers.
+ *
+ * **Example** (Creating commands)
  *
- * @example
  * ```ts
  * import { Console, Effect } from "effect"
  * import { Argument, Command, Flag } from "effect/unstable/cli"
@@ -363,18 +430,20 @@ export declare const isCommand: (u: unknown) => u is Command.Any;
  *   }))
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const make: {
     /**
-     * Creates a Command from a name, optional config, optional handler function, and optional description.
+     * Creates a `Command` from a name, an optional configuration, and an optional
+     * handler.
      *
-     * The make function is the primary constructor for CLI commands. It provides multiple overloads
-     * to support different patterns of command creation, from simple commands with no configuration
-     * to complex commands with nested configurations and error handling.
+     * Use `withDescription` and related metadata combinators to add help text. The
+     * overloads support simple commands, configured commands, and commands with
+     * effectful handlers.
+     *
+     * **Example** (Creating commands)
      *
-     * @example
      * ```ts
      * import { Console, Effect } from "effect"
      * import { Argument, Command, Flag } from "effect/unstable/cli"
@@ -417,18 +486,20 @@ export declare const make: {
      *   }))
      * ```
      *
-     * @since 4.0.0
      * @category constructors
+     * @since 4.0.0
      */
     <Name extends string>(name: Name): Command<Name, {}, {}, never, never>;
     /**
-     * Creates a Command from a name, optional config, optional handler function, and optional description.
+     * Creates a `Command` from a name, an optional configuration, and an optional
+     * handler.
      *
-     * The make function is the primary constructor for CLI commands. It provides multiple overloads
-     * to support different patterns of command creation, from simple commands with no configuration
-     * to complex commands with nested configurations and error handling.
+     * Use `withDescription` and related metadata combinators to add help text. The
+     * overloads support simple commands, configured commands, and commands with
+     * effectful handlers.
+     *
+     * **Example** (Creating commands)
      *
-     * @example
      * ```ts
      * import { Console, Effect } from "effect"
      * import { Argument, Command, Flag } from "effect/unstable/cli"
@@ -471,18 +542,20 @@ export declare const make: {
      *   }))
      * ```
      *
-     * @since 4.0.0
      * @category constructors
+     * @since 4.0.0
      */
     <Name extends string, const Config extends Command.Config>(name: Name, config: Config): Command<Name, Command.Config.Infer<Config>, {}, never, never>;
     /**
-     * Creates a Command from a name, optional config, optional handler function, and optional description.
+     * Creates a `Command` from a name, an optional configuration, and an optional
+     * handler.
+     *
+     * Use `withDescription` and related metadata combinators to add help text. The
+     * overloads support simple commands, configured commands, and commands with
+     * effectful handlers.
      *
-     * The make function is the primary constructor for CLI commands. It provides multiple overloads
-     * to support different patterns of command creation, from simple commands with no configuration
-     * to complex commands with nested configurations and error handling.
+     * **Example** (Creating commands)
      *
-     * @example
      * ```ts
      * import { Console, Effect } from "effect"
      * import { Argument, Command, Flag } from "effect/unstable/cli"
@@ -525,15 +598,16 @@ export declare const make: {
      *   }))
      * ```
      *
-     * @since 4.0.0
      * @category constructors
+     * @since 4.0.0
      */
     <Name extends string, const Config extends Command.Config, R, E>(name: Name, config: Config, handler: (config: Command.Config.Infer<Config>) => Effect.Effect<void, E, R>): Command<Name, Command.Config.Infer<Config>, {}, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>;
 };
 /**
  * Adds or replaces the handler for a command.
  *
- * @example
+ * **Example** (Adding command handlers)
+ *
  * ```ts
  * import { Console } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
@@ -551,14 +625,15 @@ export declare const make: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withHandler: {
     /**
      * Adds or replaces the handler for a command.
      *
-     * @example
+     * **Example** (Adding command handlers)
+     *
      * ```ts
      * import { Console } from "effect"
      * import { Command, Flag } from "effect/unstable/cli"
@@ -576,14 +651,15 @@ export declare const withHandler: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, R, E>(handler: (value: A) => Effect.Effect<void, E, R>): <Name extends string, XR, XE, ContextInput>(self: Command<Name, A, ContextInput, XE, XR>) => Command<Name, A, ContextInput, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>;
     /**
      * Adds or replaces the handler for a command.
      *
-     * @example
+     * **Example** (Adding command handlers)
+     *
      * ```ts
      * import { Console } from "effect"
      * import { Command, Flag } from "effect/unstable/cli"
@@ -601,8 +677,8 @@ export declare const withHandler: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <Name extends string, A, XR, XE, R, E, ContextInput>(self: Command<Name, A, ContextInput, XE, XR>, handler: (value: A) => Effect.Effect<void, E, R>): Command<Name, A, ContextInput, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>;
 };
@@ -613,7 +689,8 @@ export declare const withHandler: {
  * command within their handler. This enables shared parent flags that affect
  * all subcommands.
  *
- * @example
+ * **Example** (Adding subcommands)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
@@ -641,8 +718,8 @@ export declare const withHandler: {
  * // Usage: git --verbose clone --repo github.com/foo/bar
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withSubcommands: {
     /**
@@ -652,7 +729,8 @@ export declare const withSubcommands: {
      * command within their handler. This enables shared parent flags that affect
      * all subcommands.
      *
-     * @example
+     * **Example** (Adding subcommands)
+     *
      * ```ts
      * import { Console, Effect } from "effect"
      * import { Command, Flag } from "effect/unstable/cli"
@@ -680,8 +758,8 @@ export declare const withSubcommands: {
      * // Usage: git --verbose clone --repo github.com/foo/bar
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <const Subcommands extends ReadonlyArray<Command.SubcommandEntry>>(subcommands: Subcommands): <Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Simplify<Input | ContextInput>, ContextInput, E | ExtractSubcommandErrors<Subcommands>, R | Exclude<ExtractSubcommandContext<Subcommands>, CommandContext<Name>>>;
     /**
@@ -691,7 +769,8 @@ export declare const withSubcommands: {
      * command within their handler. This enables shared parent flags that affect
      * all subcommands.
      *
-     * @example
+     * **Example** (Adding subcommands)
+     *
      * ```ts
      * import { Console, Effect } from "effect"
      * import { Command, Flag } from "effect/unstable/cli"
@@ -719,8 +798,8 @@ export declare const withSubcommands: {
      * // Usage: git --verbose clone --repo github.com/foo/bar
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <Name extends string, Input, E, R, ContextInput, const Subcommands extends ReadonlyArray<Command.SubcommandEntry>>(self: Command<Name, Input, ContextInput, E, R>, subcommands: Subcommands): Command<Name, Simplify<Input | ContextInput>, ContextInput, E | ExtractSubcommandErrors<Subcommands>, R | Exclude<ExtractSubcommandContext<Subcommands>, CommandContext<Name>>>;
 };
@@ -731,8 +810,8 @@ export declare const withSubcommands: {
  * handlers via `yield* parentCommand`. Shared flags are accepted both before
  * and after a selected subcommand name (npm-style).
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withSharedFlags: {
     /**
@@ -742,8 +821,8 @@ export declare const withSharedFlags: {
      * handlers via `yield* parentCommand`. Shared flags are accepted both before
      * and after a selected subcommand name (npm-style).
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <const SharedFlags extends Command.FlagConfig>(sharedFlags: SharedFlags): <Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Simplify<Input & Command.Config.Infer<SharedFlags>>, Simplify<ContextInput & Command.Config.Infer<SharedFlags>>, E, R>;
     /**
@@ -753,8 +832,8 @@ export declare const withSharedFlags: {
      * handlers via `yield* parentCommand`. Shared flags are accepted both before
      * and after a selected subcommand name (npm-style).
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <Name extends string, Input, E, R, ContextInput, const SharedFlags extends Command.FlagConfig>(self: Command<Name, Input, ContextInput, E, R>, sharedFlags: SharedFlags): Command<Name, Simplify<Input & Command.Config.Infer<SharedFlags>>, Simplify<ContextInput & Command.Config.Infer<SharedFlags>>, E, R>;
 };
@@ -763,8 +842,8 @@ export declare const withSharedFlags: {
  *
  * Declared global flags apply to the command and all of its descendants.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withGlobalFlags: {
     /**
@@ -772,8 +851,8 @@ export declare const withGlobalFlags: {
      *
      * Declared global flags apply to the command and all of its descendants.
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <const GlobalFlags extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>>(globalFlags: GlobalFlags): <Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Input, ContextInput, E, Exclude<R, ExtractGlobalFlagContext<GlobalFlags>>>;
     /**
@@ -781,8 +860,8 @@ export declare const withGlobalFlags: {
      *
      * Declared global flags apply to the command and all of its descendants.
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <Name extends string, Input, E, R, ContextInput, const GlobalFlags extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>>(self: Command<Name, Input, ContextInput, E, R>, globalFlags: GlobalFlags): Command<Name, Input, ContextInput, E, Exclude<R, ExtractGlobalFlagContext<GlobalFlags>>>;
 };
@@ -796,7 +875,8 @@ type ExtractSubcommandContext<T extends ReadonlyArray<Command.SubcommandEntry>>
  * Descriptions provide users with information about what the command does
  * when they view help documentation.
  *
- * @example
+ * **Example** (Setting descriptions)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
@@ -811,8 +891,8 @@ type ExtractSubcommandContext<T extends ReadonlyArray<Command.SubcommandEntry>>
  *   )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withDescription: {
     /**
@@ -821,7 +901,8 @@ export declare const withDescription: {
      * Descriptions provide users with information about what the command does
      * when they view help documentation.
      *
-     * @example
+     * **Example** (Setting descriptions)
+     *
      * ```ts
      * import { Console, Effect } from "effect"
      * import { Command, Flag } from "effect/unstable/cli"
@@ -836,8 +917,8 @@ export declare const withDescription: {
      *   )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     (description: string): <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Input, ContextInput, E, R>;
     /**
@@ -846,7 +927,8 @@ export declare const withDescription: {
      * Descriptions provide users with information about what the command does
      * when they view help documentation.
      *
-     * @example
+     * **Example** (Setting descriptions)
+     *
      * ```ts
      * import { Console, Effect } from "effect"
      * import { Command, Flag } from "effect/unstable/cli"
@@ -861,8 +943,8 @@ export declare const withDescription: {
      *   )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>, description: string): Command<Name, Input, ContextInput, E, R>;
 };
@@ -873,8 +955,8 @@ export declare const withDescription: {
  * shell completions. If no short description is provided, the full
  * `description` is used as a fallback.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withShortDescription: {
     /**
@@ -884,8 +966,8 @@ export declare const withShortDescription: {
      * shell completions. If no short description is provided, the full
      * `description` is used as a fallback.
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     (shortDescription: string): <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Input, ContextInput, E, R>;
     /**
@@ -895,8 +977,8 @@ export declare const withShortDescription: {
      * shell completions. If no short description is provided, the full
      * `description` is used as a fallback.
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>, shortDescription: string): Command<Name, Input, ContextInput, E, R>;
 };
@@ -906,8 +988,8 @@ export declare const withShortDescription: {
  * Aliases are accepted as alternate subcommand names during parsing and are
  * shown in help output as `name, alias`.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withAlias: {
     /**
@@ -916,8 +998,8 @@ export declare const withAlias: {
      * Aliases are accepted as alternate subcommand names during parsing and are
      * shown in help output as `name, alias`.
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     (alias: string): <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Input, ContextInput, E, R>;
     /**
@@ -926,52 +1008,52 @@ export declare const withAlias: {
      * Aliases are accepted as alternate subcommand names during parsing and are
      * shown in help output as `name, alias`.
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>, alias: string): Command<Name, Input, ContextInput, E, R>;
 };
 /**
  * Adds a custom annotation to a command.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const annotate: {
     /**
      * Adds a custom annotation to a command.
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <I, S>(service: Context.Key<I, S>, value: NoInfer<S>): <Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Input, ContextInput, E, R>;
     /**
      * Adds a custom annotation to a command.
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <Name extends string, Input, E, R, ContextInput, I, S>(self: Command<Name, Input, ContextInput, E, R>, service: Context.Key<I, S>, value: NoInfer<S>): Command<Name, Input, ContextInput, E, R>;
 };
 /**
  * Merges a Context of annotations into a command.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const annotateMerge: {
     /**
      * Merges a Context of annotations into a command.
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <I>(annotations: Context.Context<I>): <Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Input, ContextInput, E, R>;
     /**
      * Merges a Context of annotations into a command.
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <Name extends string, Input, E, R, ContextInput, I>(self: Command<Name, Input, ContextInput, E, R>, annotations: Context.Context<I>): Command<Name, Input, ContextInput, E, R>;
 };
@@ -981,7 +1063,8 @@ export declare const annotateMerge: {
  * Examples are exposed in structured `HelpDoc` data and rendered by the
  * default formatter in an `EXAMPLES` section.
  *
- * @example
+ * **Example** (Adding usage examples)
+ *
  * ```ts
  * import { Command } from "effect/unstable/cli"
  *
@@ -993,8 +1076,8 @@ export declare const annotateMerge: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withExamples: {
     /**
@@ -1003,7 +1086,8 @@ export declare const withExamples: {
      * Examples are exposed in structured `HelpDoc` data and rendered by the
      * default formatter in an `EXAMPLES` section.
      *
-     * @example
+     * **Example** (Adding usage examples)
+     *
      * ```ts
      * import { Command } from "effect/unstable/cli"
      *
@@ -1015,8 +1099,8 @@ export declare const withExamples: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     (examples: ReadonlyArray<Command.Example>): <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Input, ContextInput, E, R>;
     /**
@@ -1025,7 +1109,8 @@ export declare const withExamples: {
      * Examples are exposed in structured `HelpDoc` data and rendered by the
      * default formatter in an `EXAMPLES` section.
      *
-     * @example
+     * **Example** (Adding usage examples)
+     *
      * ```ts
      * import { Command } from "effect/unstable/cli"
      *
@@ -1037,8 +1122,8 @@ export declare const withExamples: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>, examples: ReadonlyArray<Command.Example>): Command<Name, Input, ContextInput, E, R>;
 };
@@ -1046,7 +1131,8 @@ export declare const withExamples: {
  * Provides the handler of a command with the services produced by a layer
  * that optionally depends on the command-line input to be created.
  *
- * @example
+ * **Example** (Providing command services)
+ *
  * ```ts
  * import { Effect, FileSystem, PlatformError } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
@@ -1075,15 +1161,16 @@ export declare const withExamples: {
  *   )
  * ```
  *
- * @since 4.0.0
  * @category providing services
+ * @since 4.0.0
  */
 export declare const provide: {
     /**
      * Provides the handler of a command with the services produced by a layer
      * that optionally depends on the command-line input to be created.
      *
-     * @example
+     * **Example** (Providing command services)
+     *
      * ```ts
      * import { Effect, FileSystem, PlatformError } from "effect"
      * import { Command, Flag } from "effect/unstable/cli"
@@ -1112,8 +1199,8 @@ export declare const provide: {
      *   )
      * ```
      *
-     * @since 4.0.0
      * @category providing services
+     * @since 4.0.0
      */
     <Input, LR, LE, LA>(layer: Layer.Layer<LA, LE, LR> | ((input: Input) => Layer.Layer<LA, LE, LR>), options?: {
         readonly local?: boolean | undefined;
@@ -1122,7 +1209,8 @@ export declare const provide: {
      * Provides the handler of a command with the services produced by a layer
      * that optionally depends on the command-line input to be created.
      *
-     * @example
+     * **Example** (Providing command services)
+     *
      * ```ts
      * import { Effect, FileSystem, PlatformError } from "effect"
      * import { Command, Flag } from "effect/unstable/cli"
@@ -1151,8 +1239,8 @@ export declare const provide: {
      *   )
      * ```
      *
-     * @since 4.0.0
      * @category providing services
+     * @since 4.0.0
      */
     <const Name extends string, Input, E, R, ContextInput, LA, LE, LR>(self: Command<Name, Input, ContextInput, E, R>, layer: Layer.Layer<LA, LE, LR> | ((input: Input) => Layer.Layer<LA, LE, LR>), options?: {
         readonly local?: boolean | undefined;
@@ -1162,24 +1250,24 @@ export declare const provide: {
  * Provides the handler of a command with the implementation of a service that
  * optionally depends on the command-line input to be constructed.
  *
- * @since 4.0.0
  * @category providing services
+ * @since 4.0.0
  */
 export declare const provideSync: {
     /**
      * Provides the handler of a command with the implementation of a service that
      * optionally depends on the command-line input to be constructed.
      *
-     * @since 4.0.0
      * @category providing services
+     * @since 4.0.0
      */
     <I, S, Input>(service: Context.Key<I, S>, implementation: S | ((input: Input) => S)): <const Name extends string, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Input, ContextInput, E, Exclude<R, I>>;
     /**
      * Provides the handler of a command with the implementation of a service that
      * optionally depends on the command-line input to be constructed.
      *
-     * @since 4.0.0
      * @category providing services
+     * @since 4.0.0
      */
     <const Name extends string, Input, E, R, ContextInput, I, S>(self: Command<Name, Input, ContextInput, E, R>, service: Context.Key<I, S>, implementation: S | ((input: Input) => S)): Command<Name, Input, ContextInput, E, Exclude<R, I>>;
 };
@@ -1187,24 +1275,24 @@ export declare const provideSync: {
  * Provides the handler of a command with the service produced by an effect
  * that optionally depends on the command-line input to be created.
  *
- * @since 4.0.0
  * @category providing services
+ * @since 4.0.0
  */
 export declare const provideEffect: {
     /**
      * Provides the handler of a command with the service produced by an effect
      * that optionally depends on the command-line input to be created.
      *
-     * @since 4.0.0
      * @category providing services
+     * @since 4.0.0
      */
     <I, S, Input, R2, E2>(service: Context.Key<I, S>, effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, R2>)): <const Name extends string, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Input, ContextInput, E | E2, Exclude<R, I> | R2>;
     /**
      * Provides the handler of a command with the service produced by an effect
      * that optionally depends on the command-line input to be created.
      *
-     * @since 4.0.0
      * @category providing services
+     * @since 4.0.0
      */
     <const Name extends string, Input, E, R, ContextInput, I, S, R2, E2>(self: Command<Name, Input, ContextInput, E, R>, service: Context.Key<I, S>, effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, R2>)): Command<Name, Input, ContextInput, E | E2, Exclude<R, I> | R2>;
 };
@@ -1212,31 +1300,35 @@ export declare const provideEffect: {
  * Allows for execution of an effect, which optionally depends on command-line
  * input to be created, prior to executing the handler of a command.
  *
- * @since 4.0.0
  * @category providing services
+ * @since 4.0.0
  */
 export declare const provideEffectDiscard: {
     /**
      * Allows for execution of an effect, which optionally depends on command-line
      * input to be created, prior to executing the handler of a command.
      *
-     * @since 4.0.0
      * @category providing services
+     * @since 4.0.0
      */
     <_, Input, E2, R2>(effect: Effect.Effect<_, E2, R2> | ((input: Input) => Effect.Effect<_, E2, R2>)): <const Name extends string, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Input, ContextInput, E | E2, R | R2>;
     /**
      * Allows for execution of an effect, which optionally depends on command-line
      * input to be created, prior to executing the handler of a command.
      *
-     * @since 4.0.0
      * @category providing services
+     * @since 4.0.0
      */
     <const Name extends string, Input, E, R, ContextInput, _, E2, R2>(self: Command<Name, Input, ContextInput, E, R>, effect: Effect.Effect<_, E2, R2> | ((input: Input) => Effect.Effect<_, E2, R2>)): Command<Name, Input, ContextInput, E | E2, R | R2>;
 };
 /**
- * Runs a command with the provided input arguments.
+ * Runs a command using the arguments supplied by the `Stdio` service.
+ *
+ * Use `runWith` when you need to execute a command with an explicit argument
+ * array, such as in tests.
+ *
+ * **Example** (Running commands with standard input)
  *
- * @example
  * ```ts
  * import { Console, Effect } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
@@ -1254,14 +1346,18 @@ export declare const provideEffectDiscard: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category command execution
+ * @since 4.0.0
  */
 export declare const run: {
     /**
-     * Runs a command with the provided input arguments.
+     * Runs a command using the arguments supplied by the `Stdio` service.
+     *
+     * Use `runWith` when you need to execute a command with an explicit argument
+     * array, such as in tests.
+     *
+     * **Example** (Running commands with standard input)
      *
-     * @example
      * ```ts
      * import { Console, Effect } from "effect"
      * import { Command, Flag } from "effect/unstable/cli"
@@ -1279,16 +1375,20 @@ export declare const run: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category command execution
+     * @since 4.0.0
      */
     (config: {
         readonly version: string;
     }): <Name extends string, Input, E, R, ContextInput>(command: Command<Name, Input, ContextInput, E, R>) => Effect.Effect<void, E | CliError.CliError, R | Environment>;
     /**
-     * Runs a command with the provided input arguments.
+     * Runs a command using the arguments supplied by the `Stdio` service.
+     *
+     * Use `runWith` when you need to execute a command with an explicit argument
+     * array, such as in tests.
+     *
+     * **Example** (Running commands with standard input)
      *
-     * @example
      * ```ts
      * import { Console, Effect } from "effect"
      * import { Command, Flag } from "effect/unstable/cli"
@@ -1306,8 +1406,8 @@ export declare const run: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category command execution
+     * @since 4.0.0
      */
     <Name extends string, Input, E, R, ContextInput>(command: Command<Name, Input, ContextInput, E, R>, config: {
         readonly version: string;
@@ -1319,7 +1419,8 @@ export declare const run: {
  * This function is useful for testing CLI applications or when you want to
  * programmatically execute commands with specific arguments.
  *
- * @example
+ * **Example** (Running commands with explicit arguments)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
@@ -1349,8 +1450,8 @@ export declare const run: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category command execution
+ * @since 4.0.0
  */
 export declare const runWith: <const Name extends string, Input, E, R, ContextInput>(command: Command<Name, Input, ContextInput, E, R>, config: {
     readonly version: string;