effect 4.0.0-beta.66 → 4.0.0-beta.68

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"
@@ -40,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"
@@ -73,8 +102,8 @@ 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<in out Name extends string, in Input, out ContextInput = {}, out E = never, out R = never>
   extends
@@ -126,12 +155,20 @@ export interface Command<in out Name extends string, in Input, out ContextInput
 }
 
 /**
+ * Companion namespace containing type-level helpers and configuration shapes
+ * used by `Command`.
+ *
  * @since 4.0.0
  */
 export declare namespace Command {
   /**
-   * @since 4.0.0
+   * 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>
@@ -142,8 +179,8 @@ export declare namespace Command {
   /**
    * Represents a concrete usage example for a command.
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export interface Example {
     readonly command: string
@@ -158,10 +195,11 @@ 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"
+   * import type { Command as CliCommand } from "effect/unstable/cli"
    *
    * // Simple flat configuration
    * const simpleConfig: CliCommand.Command.Config = {
@@ -183,8 +221,8 @@ export declare namespace Command {
    * }
    * ```
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export interface Config {
     readonly [key: string]:
@@ -198,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]:
@@ -212,7 +250,6 @@ export declare namespace Command {
    * Utilities for working with command configurations.
    *
    * @since 4.0.0
-   * @category models
    */
   export namespace Config {
     /**
@@ -221,10 +258,11 @@ 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"
+     * import type { Command as CliCommand } from "effect/unstable/cli"
      *
      * const config = {
      *   name: Flag.string("name"),
@@ -244,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]> }
@@ -254,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
@@ -266,8 +304,8 @@ export declare namespace Command {
   /**
    * Represents any Command regardless of its type parameters.
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export interface Any extends Effect.Effect<any, never, any> {
     readonly [TypeId]: any
@@ -286,8 +324,8 @@ export declare namespace Command {
   /**
    * 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
@@ -297,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,
@@ -334,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"
@@ -361,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
@@ -372,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>>
@@ -386,8 +429,10 @@ export interface ParsedTokens {
 }
 
 /**
+ * Returns `true` if the provided value is a `Command`.
+ *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export const isCommand = (u: unknown): u is Command.Any => Predicate.hasProperty(u, TypeId)
 
@@ -396,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.
+ *
+ * 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"
@@ -445,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: {
   /* ========================================================================== */
@@ -454,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"
@@ -503,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>
 
@@ -513,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"
@@ -562,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>
 
@@ -572,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.
    *
-   * 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"
@@ -621,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,
@@ -649,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"
@@ -667,8 +721,8 @@ export const make: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withHandler: {
   /* ========================================================================== */
@@ -678,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"
@@ -696,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>
@@ -709,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"
@@ -727,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>,
@@ -798,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"
@@ -826,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: {
   /**
@@ -837,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"
@@ -865,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>
@@ -884,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"
@@ -912,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,
@@ -1013,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: {
   /**
@@ -1024,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>
@@ -1043,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,
@@ -1124,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: {
   /**
@@ -1133,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>
@@ -1144,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,
@@ -1192,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"
@@ -1207,8 +1267,8 @@ type ExtractSubcommandContext<T extends ReadonlyArray<Command.SubcommandEntry>>
  *   )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withDescription: {
   /**
@@ -1217,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"
@@ -1232,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>
@@ -1244,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"
@@ -1259,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>(
@@ -1275,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: {
   /**
@@ -1286,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>
@@ -1299,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>(
@@ -1314,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: {
   /**
@@ -1324,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>
@@ -1336,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>(
@@ -1348,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>
@@ -1364,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>,
@@ -1384,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>
@@ -1400,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>,
@@ -1421,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"
  *
@@ -1433,8 +1496,8 @@ export const annotateMerge: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withExamples: {
   /**
@@ -1443,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"
    *
@@ -1455,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>
@@ -1467,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"
    *
@@ -1479,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>,
@@ -1508,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"
@@ -1537,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"
@@ -1574,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>),
@@ -1589,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"
@@ -1618,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>,
@@ -1642,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>
@@ -1660,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>,
@@ -1684,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>,
@@ -1705,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>,
@@ -1728,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>)
@@ -1748,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>,
@@ -1818,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"
@@ -1838,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"
@@ -1863,8 +1939,8 @@ export const run: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category command execution
+   * @since 4.0.0
    */
   (
     config: {
@@ -1874,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"
@@ -1894,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>,
@@ -1922,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"
@@ -1952,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>,