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

package/src/unstable/cli/Command.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 { NonEmptyArray, NonEmptyReadonlyArray } from "../../Array.ts"
@@ -10,13 +38,12 @@ import { dual } from "../../Function.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 Predicate from "../../Predicate.ts"
 import * as References from "../../References.ts"
 import * as Result from "../../Result.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 CliOutput from "./CliOutput.ts"
@@ -41,7 +68,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"
@@ -74,20 +102,18 @@ 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>
+export interface Command<in out Name extends string, in Input, out ContextInput = {}, out E = never, out R = never>
   extends
-    Pipeable,
-    Effect.Yieldable<
-      Command<Name, Input, ContextInput, E, R>,
+    Effect.Effect<
       ContextInput,
       never,
       CommandContext<Name>
     >
 {
-  readonly [TypeId]: typeof TypeId
+  readonly [TypeId]: Command.Variance<Input, E, R>
 
   /**
    * The name of the command.
@@ -129,14 +155,32 @@ export interface Command<Name extends string, Input, ContextInput = {}, E = neve
 }
 
 /**
+ * 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
+   */
+  export 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
    */
   export interface Example {
     readonly command: string
@@ -151,7 +195,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"
@@ -176,8 +221,8 @@ export declare namespace Command {
    * }
    * ```
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export interface Config {
     readonly [key: string]:
@@ -191,8 +236,8 @@ export declare namespace Command {
    *
    * Only flags are allowed here; arguments are intentionally excluded.
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export interface FlagConfig {
     readonly [key: string]:
@@ -205,7 +250,6 @@ export declare namespace Command {
    * Utilities for working with command configurations.
    *
    * @since 4.0.0
-   * @category models
    */
   export namespace Config {
     /**
@@ -214,7 +258,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"
@@ -237,8 +282,8 @@ export declare namespace Command {
      * // }
      * ```
      *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     export type Infer<A extends Config> = Simplify<
       { readonly [Key in keyof A]: InferValue<A[Key]> }
@@ -247,8 +292,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
      */
     export type InferValue<A> = A extends ReadonlyArray<any> ? { readonly [Key in keyof A]: InferValue<A[Key]> }
       : A extends Param.Param<infer _Kind, infer _Value> ? _Value
@@ -259,16 +304,28 @@ export declare namespace Command {
   /**
    * Represents any Command regardless of its type parameters.
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
-  export type Any = Command<string, unknown, unknown, unknown, unknown>
+  export 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
    */
   export interface SubcommandGroup<Commands extends ReadonlyArray<Any> = ReadonlyArray<Any>> {
     readonly group: string
@@ -278,25 +335,29 @@ export declare namespace Command {
   /**
    * Entry type accepted by `Command.withSubcommands`.
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export 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,
@@ -315,7 +376,8 @@ export type Error<C> = C extends Command<
  * 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"
@@ -342,8 +404,8 @@ export type Error<C> = C extends Command<
  * // 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
@@ -353,8 +415,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>>
@@ -367,8 +429,10 @@ export interface ParsedTokens {
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` if the provided value is a `Command`.
+ *
  * @category Guards
+ * @since 4.0.0
  */
 export const isCommand = (u: unknown): u is Command.Any => Predicate.hasProperty(u, TypeId)
 
@@ -377,13 +441,15 @@ export const isCommand = (u: unknown): u is Command.Any => Predicate.hasProperty
 /* ========================================================================== */
 
 /**
- * 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"
@@ -426,8 +492,8 @@ export const isCommand = (u: unknown): u is Command.Any => Predicate.hasProperty
  *   }))
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make: {
   /* ========================================================================== */
@@ -435,13 +501,15 @@ export 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"
@@ -484,8 +552,8 @@ export const make: {
    *   }))
    * ```
    *
-   * @since 4.0.0
    * @category constructors
+   * @since 4.0.0
    */
   <Name extends string>(name: Name): Command<Name, {}, {}, never, never>
 
@@ -494,13 +562,15 @@ export 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"
@@ -543,8 +613,8 @@ export 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>
 
@@ -553,13 +623,15 @@ export 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.
+   *
+   * 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"
@@ -602,8 +674,8 @@ export const make: {
    *   }))
    * ```
    *
-   * @since 4.0.0
    * @category constructors
+   * @since 4.0.0
    */
   <Name extends string, const Config extends Command.Config, R, E>(
     name: Name,
@@ -630,7 +702,8 @@ export const make: {
 /**
  * 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"
@@ -648,8 +721,8 @@ export const make: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withHandler: {
   /* ========================================================================== */
@@ -659,7 +732,8 @@ export 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"
@@ -677,8 +751,8 @@ export 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>
@@ -690,7 +764,8 @@ export 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"
@@ -708,8 +783,8 @@ export 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>,
@@ -719,7 +794,7 @@ export const withHandler: {
   self: Command<Name, A, ContextInput, XE, XR>,
   handler: (value: A) => Effect.Effect<void, E, R>
 ): Command<Name, A, ContextInput, E, Exclude<R, GlobalFlag.BuiltInSettingContext>> =>
-  makeCommand({ ...toImpl(self), handle: handler }))
+  makeCommand({ ...toImpl(self), handle: handler } as any))
 
 interface SubcommandGroupInternal {
   readonly group: string | undefined
@@ -779,7 +854,8 @@ const normalizeSubcommandEntries = (
  * 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"
@@ -807,8 +883,8 @@ const normalizeSubcommandEntries = (
  * // Usage: git --verbose clone --repo github.com/foo/bar
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withSubcommands: {
   /**
@@ -818,7 +894,8 @@ export 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"
@@ -846,8 +923,8 @@ export 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>
@@ -865,7 +942,8 @@ export 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"
@@ -893,8 +971,8 @@ export const withSubcommands: {
    * // Usage: git --verbose clone --repo github.com/foo/bar
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <
     Name extends string,
@@ -931,7 +1009,7 @@ export const withSubcommands: {
   checkForDuplicateFlags(self, normalized.flat)
 
   const impl = toImpl(self)
-  const byName = new Map(normalized.flat.map((s) => [s.name, toImpl(s)] as const))
+  const byName = new Map(normalized.flat.map((s) => [s.name, toImpl(s as any)] as const))
 
   type NextInput = Simplify<Input | ContextInput>
   const SubcommandStateSymbol = Symbol("effect/cli/SubcommandState")
@@ -984,7 +1062,7 @@ export const withSubcommands: {
     parse,
     parseContext: impl.parseContext,
     handle
-  })
+  }) as any
 })
 
 /**
@@ -994,8 +1072,8 @@ export 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 const withSharedFlags: {
   /**
@@ -1005,8 +1083,8 @@ export 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>
@@ -1024,8 +1102,8 @@ export 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,
@@ -1096,7 +1174,7 @@ export const withSharedFlags: {
       parse,
       parseContext,
       handle
-    })
+    }) as any
   }
 )
 
@@ -1105,8 +1183,8 @@ export 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 const withGlobalFlags: {
   /**
@@ -1114,8 +1192,8 @@ export 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>
@@ -1125,8 +1203,8 @@ export 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,
@@ -1151,7 +1229,7 @@ export const withGlobalFlags: {
   ): Command<Name, Input, ContextInput, E, Exclude<R, ExtractGlobalFlagContext<GlobalFlags>>> => {
     const impl = toImpl(self)
     const next = Array.from(new Set([...impl.globalFlags, ...globalFlags]))
-    return makeCommand({ ...impl, globalFlags: next })
+    return makeCommand({ ...impl, globalFlags: next }) as any
   }
 )
 
@@ -1173,7 +1251,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"
@@ -1188,8 +1267,8 @@ type ExtractSubcommandContext<T extends ReadonlyArray<Command.SubcommandEntry>>
  *   )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withDescription: {
   /**
@@ -1198,7 +1277,8 @@ export 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"
@@ -1213,8 +1293,8 @@ export 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>
@@ -1225,7 +1305,8 @@ export 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"
@@ -1240,8 +1321,8 @@ export 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>
 } = dual(2, <const Name extends string, Input, E, R, ContextInput>(
@@ -1256,8 +1337,8 @@ export 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 const withShortDescription: {
   /**
@@ -1267,8 +1348,8 @@ export 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>
@@ -1280,8 +1361,8 @@ export 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>
 } = dual(2, <const Name extends string, Input, E, R, ContextInput>(
@@ -1295,8 +1376,8 @@ export 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 const withAlias: {
   /**
@@ -1305,8 +1386,8 @@ export 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>
@@ -1317,8 +1398,8 @@ export 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>
 } = dual(2, <const Name extends string, Input, E, R, ContextInput>(
@@ -1329,15 +1410,15 @@ export const withAlias: {
 /**
  * Adds a custom annotation to a command.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export 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>
@@ -1345,8 +1426,8 @@ export const annotate: {
   /**
    * 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>,
@@ -1365,15 +1446,15 @@ export const annotate: {
 /**
  * Merges a Context of annotations into a command.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export 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>
@@ -1381,8 +1462,8 @@ export const annotateMerge: {
   /**
    * 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>,
@@ -1402,7 +1483,8 @@ export 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"
  *
@@ -1414,8 +1496,8 @@ export const annotateMerge: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withExamples: {
   /**
@@ -1424,7 +1506,8 @@ export 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"
    *
@@ -1436,8 +1519,8 @@ export 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>
@@ -1448,7 +1531,8 @@ export 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"
    *
@@ -1460,8 +1544,8 @@ export 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>,
@@ -1489,7 +1573,8 @@ const mapHandler = <Name extends string, Input, E, R, ContextInput, E2, R2>(
  * 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"
@@ -1518,15 +1603,16 @@ const mapHandler = <Name extends string, Input, E, R, ContextInput, E2, R2>(
  *   )
  * ```
  *
- * @since 4.0.0
  * @category providing services
+ * @since 4.0.0
  */
 export 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"
@@ -1555,8 +1641,8 @@ export 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>),
@@ -1570,7 +1656,8 @@ export 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"
@@ -1599,8 +1686,8 @@ export 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>,
@@ -1623,16 +1710,16 @@ export 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 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>
@@ -1641,8 +1728,8 @@ export 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
    */
   <const Name extends string, Input, E, R, ContextInput, I, S>(
     self: Command<Name, Input, ContextInput, E, R>,
@@ -1665,16 +1752,16 @@ export 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 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>,
@@ -1686,8 +1773,8 @@ export 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
    */
   <const Name extends string, Input, E, R, ContextInput, I, S, R2, E2>(
     self: Command<Name, Input, ContextInput, E, R>,
@@ -1709,16 +1796,16 @@ export 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 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>)
@@ -1729,8 +1816,8 @@ export 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
    */
   <const Name extends string, Input, E, R, ContextInput, _, E2, R2>(
     self: Command<Name, Input, ContextInput, E, R>,
@@ -1799,9 +1886,13 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
   })
 
 /**
- * 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"
@@ -1819,14 +1910,18 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
  * })
  * ```
  *
- * @since 4.0.0
  * @category command execution
+ * @since 4.0.0
  */
 export 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"
@@ -1844,8 +1939,8 @@ export const run: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category command execution
+   * @since 4.0.0
    */
   (
     config: {
@@ -1855,9 +1950,13 @@ export const run: {
     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"
@@ -1875,8 +1974,8 @@ export 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>,
@@ -1903,7 +2002,8 @@ export 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"
@@ -1933,8 +2033,8 @@ export const run: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category command execution
+ * @since 4.0.0
  */
 export const runWith = <const Name extends string, Input, E, R, ContextInput>(
   command: Command<Name, Input, ContextInput, E, R>,