effect 4.0.0-beta.102 → 4.0.0-beta.104

package/src/unstable/cli/Command.ts

@@ -57,9 +57,27 @@ import * as Prompt from "./Prompt.ts"
  *
  * **Example** (Defining CLI commands)
  *
- * ```ts
- * import { Console } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { Argument, Command, Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
  * // Simple command with no configuration
  * const version: Command.Command<"version", {}, {}, never, never> = Command.make(
@@ -84,9 +102,15 @@ import * as Prompt from "./Prompt.ts"
  * })
  *
  * // Command with handler
+ * const output: Array<string> = []
  * const greet = Command.make("greet", {
  *   name: Flag.string("name")
- * }, (config) => Console.log(`Hello, ${config.name}!`))
+ * }, (config) => Effect.sync(() => output.push(`Hello, ${config.name}!`)).pipe(Effect.asVoid))
+ *
+ * await Effect.runPromise(
+ *   Command.runWith(greet, { version: "1.0.0" })(["--name", "Alice"]).pipe(Effect.provide(CliTestLayer))
+ * )
+ * output // => ["Hello, Alice!"]
  * ```
  *
  * @category models
@@ -141,11 +165,11 @@ export interface Command<in out Name extends string, in Input, out ContextInput
   readonly annotations: Context.Context<never>
 
   /**
-   * Whether this command is hidden from parent help output, shell
-   * completions, and unknown-subcommand suggestions. Hidden commands still
+   * Whether this command is omitted from parent help output, shell
+   * completions, and unknown-subcommand suggestions. Unlisted commands still
    * parse and execute normally when invoked by exact name.
    */
-  readonly hidden: boolean
+  readonly unlisted: boolean
 }
 
 /**
@@ -194,19 +218,19 @@ export declare namespace Command {
    *
    * **Example** (Configuring command input)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Argument, Flag } from "effect/unstable/cli"
    * import type { Command as CliCommand } from "effect/unstable/cli"
    *
    * // Simple flat configuration
-   * const simpleConfig: CliCommand.Command.Config = {
+   * const simpleConfig = {
    *   name: Flag.string("name"),
    *   age: Flag.integer("age"),
    *   file: Argument.string("file")
-   * }
+   * } satisfies CliCommand.Command.Config
    *
    * // Nested configuration for organization
-   * const nestedConfig: CliCommand.Command.Config = {
+   * const nestedConfig = {
    *   user: {
    *     name: Flag.string("name"),
    *     email: Flag.string("email")
@@ -215,7 +239,9 @@ export declare namespace Command {
    *     host: Flag.string("host"),
    *     port: Flag.integer("port")
    *   }
-   * }
+   * } satisfies CliCommand.Command.Config
+   *
+   * [simpleConfig.name.kind, nestedConfig.server.port.kind] // => ["flag", "flag"]
    * ```
    *
    * @category models
@@ -261,7 +287,7 @@ export declare namespace Command {
      *
      * **Example** (Inferring command input)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Flag } from "effect/unstable/cli"
      * import type { Command as CliCommand } from "effect/unstable/cli"
      *
@@ -281,6 +307,12 @@ export declare namespace Command {
      * //     readonly port: number
      * //   }
      * // }
+     *
+     * const inferred: Result = {
+     *   name: "Alice",
+     *   server: { host: "localhost", port: 8080 }
+     * }
+     * inferred // => { name: "Alice", server: { host: "localhost", port: 8080 } }
      * ```
      *
      * @category models
@@ -320,7 +352,7 @@ export declare namespace Command {
       readonly commands: NonEmptyReadonlyArray<Command.Any>
     }>
     readonly annotations: Context.Context<never>
-    readonly hidden: boolean
+    readonly unlisted: boolean
   }
 
   /**
@@ -399,9 +431,27 @@ export type Services<C> = C extends Command<
  *
  * **Example** (Accessing parent command context)
  *
- * ```ts
- * import { Console, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
  * const parent = Command.make("app").pipe(
  *   Command.withSharedFlags({
@@ -410,19 +460,31 @@ export type Services<C> = C extends Command<
  *   })
  * )
  *
+ * const output: Array<string> = []
  * const child = Command.make("deploy", {
  *   target: Flag.string("target")
  * }, (config) =>
  *   Effect.gen(function*() {
  *     // Access parent's config by yielding the parent command
  *     const parentConfig = yield* parent
- *     yield* Console.log(`Verbose: ${parentConfig.verbose}`)
- *     yield* Console.log(`Config: ${parentConfig.config}`)
- *     yield* Console.log(`Target: ${config.target}`)
+ *     yield* Effect.sync(() => output.push(`Verbose: ${parentConfig.verbose}`))
+ *     yield* Effect.sync(() => output.push(`Config: ${parentConfig.config}`))
+ *     yield* Effect.sync(() => output.push(`Target: ${config.target}`))
  *   }))
  *
  * const app = parent.pipe(Command.withSubcommands([child]))
- * // Usage: app --verbose --config prod.json deploy --target staging
+ *
+ * await Effect.runPromise(
+ *   Command.runWith(app, { version: "1.0.0" })([
+ *     "--verbose",
+ *     "--config",
+ *     "prod.json",
+ *     "deploy",
+ *     "--target",
+ *     "staging"
+ *   ]).pipe(Effect.provide(CliTestLayer))
+ * )
+ * output // => ["Verbose: true", "Config: prod.json", "Target: staging"]
  * ```
  *
  * @category models
@@ -478,9 +540,27 @@ export const isCommand = (u: unknown): u is Command.Any => Predicate.hasProperty
  *
  * **Example** (Creating commands)
  *
- * ```ts
- * import { Console, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { Argument, Command, Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
  * // Simple command with no configuration
  * const version = Command.make("version")
@@ -505,19 +585,29 @@ export const isCommand = (u: unknown): u is Command.Any => Predicate.hasProperty
  * })
  *
  * // Command with handler
+ * const output: Array<string> = []
  * const deployWithHandler = Command.make("deploy", {
  *   environment: Flag.string("env"),
  *   force: Flag.boolean("force")
  * }, (config) =>
  *   Effect.gen(function*() {
- *     yield* Console.log(`Starting deployment to ${config.environment}`)
+ *     yield* Effect.sync(() => output.push(`Starting deployment to ${config.environment}`))
  *
  *     if (!config.force && config.environment === "production") {
  *       return yield* Effect.fail("Production deployments require --force flag")
  *     }
  *
- *     yield* Console.log("Deployment completed successfully")
+ *     yield* Effect.sync(() => output.push("Deployment completed successfully"))
  *   }))
+ *
+ * await Effect.runPromise(
+ *   Command.runWith(deployWithHandler, { version: "1.0.0" })([
+ *     "--env",
+ *     "staging",
+ *     "--force"
+ *   ]).pipe(Effect.provide(CliTestLayer))
+ * )
+ * output // => ["Starting deployment to staging", "Deployment completed successfully"]
  * ```
  *
  * @category constructors
@@ -540,9 +630,27 @@ export const make: {
    *
    * **Example** (Creating commands)
    *
-   * ```ts
-   * import { Console, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { Argument, Command, Flag } from "effect/unstable/cli"
+   * import { ChildProcessSpawner } from "effect/unstable/process"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
    *
    * // Simple command with no configuration
    * const version = Command.make("version")
@@ -567,19 +675,29 @@ export const make: {
    * })
    *
    * // Command with handler
+   * const output: Array<string> = []
    * const deployWithHandler = Command.make("deploy", {
    *   environment: Flag.string("env"),
    *   force: Flag.boolean("force")
    * }, (config) =>
    *   Effect.gen(function*() {
-   *     yield* Console.log(`Starting deployment to ${config.environment}`)
+   *     yield* Effect.sync(() => output.push(`Starting deployment to ${config.environment}`))
    *
    *     if (!config.force && config.environment === "production") {
    *       return yield* Effect.fail("Production deployments require --force flag")
    *     }
    *
-   *     yield* Console.log("Deployment completed successfully")
+   *     yield* Effect.sync(() => output.push("Deployment completed successfully"))
    *   }))
+   *
+   * await Effect.runPromise(
+   *   Command.runWith(deployWithHandler, { version: "1.0.0" })([
+   *     "--env",
+   *     "staging",
+   *     "--force"
+   *   ]).pipe(Effect.provide(CliTestLayer))
+   * )
+   * output // => ["Starting deployment to staging", "Deployment completed successfully"]
    * ```
    *
    * @category constructors
@@ -603,9 +721,27 @@ export const make: {
    *
    * **Example** (Creating commands)
    *
-   * ```ts
-   * import { Console, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { Argument, Command, Flag } from "effect/unstable/cli"
+   * import { ChildProcessSpawner } from "effect/unstable/process"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
    *
    * // Simple command with no configuration
    * const version = Command.make("version")
@@ -630,19 +766,29 @@ export const make: {
    * })
    *
    * // Command with handler
+   * const output: Array<string> = []
    * const deployWithHandler = Command.make("deploy", {
    *   environment: Flag.string("env"),
    *   force: Flag.boolean("force")
    * }, (config) =>
    *   Effect.gen(function*() {
-   *     yield* Console.log(`Starting deployment to ${config.environment}`)
+   *     yield* Effect.sync(() => output.push(`Starting deployment to ${config.environment}`))
    *
    *     if (!config.force && config.environment === "production") {
    *       return yield* Effect.fail("Production deployments require --force flag")
    *     }
    *
-   *     yield* Console.log("Deployment completed successfully")
+   *     yield* Effect.sync(() => output.push("Deployment completed successfully"))
    *   }))
+   *
+   * await Effect.runPromise(
+   *   Command.runWith(deployWithHandler, { version: "1.0.0" })([
+   *     "--env",
+   *     "staging",
+   *     "--force"
+   *   ]).pipe(Effect.provide(CliTestLayer))
+   * )
+   * output // => ["Starting deployment to staging", "Deployment completed successfully"]
    * ```
    *
    * @category constructors
@@ -666,9 +812,27 @@ export const make: {
    *
    * **Example** (Creating commands)
    *
-   * ```ts
-   * import { Console, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { Argument, Command, Flag } from "effect/unstable/cli"
+   * import { ChildProcessSpawner } from "effect/unstable/process"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
    *
    * // Simple command with no configuration
    * const version = Command.make("version")
@@ -693,19 +857,29 @@ export const make: {
    * })
    *
    * // Command with handler
+   * const output: Array<string> = []
    * const deployWithHandler = Command.make("deploy", {
    *   environment: Flag.string("env"),
    *   force: Flag.boolean("force")
    * }, (config) =>
    *   Effect.gen(function*() {
-   *     yield* Console.log(`Starting deployment to ${config.environment}`)
+   *     yield* Effect.sync(() => output.push(`Starting deployment to ${config.environment}`))
    *
    *     if (!config.force && config.environment === "production") {
    *       return yield* Effect.fail("Production deployments require --force flag")
    *     }
    *
-   *     yield* Console.log("Deployment completed successfully")
+   *     yield* Effect.sync(() => output.push("Deployment completed successfully"))
    *   }))
+   *
+   * await Effect.runPromise(
+   *   Command.runWith(deployWithHandler, { version: "1.0.0" })([
+   *     "--env",
+   *     "staging",
+   *     "--force"
+   *   ]).pipe(Effect.provide(CliTestLayer))
+   * )
+   * output // => ["Starting deployment to staging", "Deployment completed successfully"]
    * ```
    *
    * @category constructors
@@ -738,9 +912,27 @@ export const make: {
  *
  * **Example** (Adding command handlers)
  *
- * ```ts
- * import { Console } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
  * // Command without initial handler
  * const greet = Command.make("greet", {
@@ -748,11 +940,19 @@ export const make: {
  * })
  *
  * // Add handler later
+ * const output: Array<string> = []
  * const greetWithHandler = greet.pipe(
  *   Command.withHandler((config: { readonly name: string }) =>
- *     Console.log(`Hello, ${config.name}!`)
+ *     Effect.sync(() => output.push(`Hello, ${config.name}!`)).pipe(Effect.asVoid)
  *   )
  * )
+ *
+ * await Effect.runPromise(
+ *   Command.runWith(greetWithHandler, { version: "1.0.0" })(["--name", "Alice"]).pipe(
+ *     Effect.provide(CliTestLayer)
+ *   )
+ * )
+ * output // => ["Hello, Alice!"]
  * ```
  *
  * @category combinators
@@ -768,9 +968,27 @@ export const withHandler: {
    *
    * **Example** (Adding command handlers)
    *
-   * ```ts
-   * import { Console } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { Command, Flag } from "effect/unstable/cli"
+   * import { ChildProcessSpawner } from "effect/unstable/process"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
    *
    * // Command without initial handler
    * const greet = Command.make("greet", {
@@ -778,11 +996,19 @@ export const withHandler: {
    * })
    *
    * // Add handler later
+   * const output: Array<string> = []
    * const greetWithHandler = greet.pipe(
    *   Command.withHandler((config: { readonly name: string }) =>
-   *     Console.log(`Hello, ${config.name}!`)
+   *     Effect.sync(() => output.push(`Hello, ${config.name}!`)).pipe(Effect.asVoid)
    *   )
    * )
+   *
+   * await Effect.runPromise(
+   *   Command.runWith(greetWithHandler, { version: "1.0.0" })(["--name", "Alice"]).pipe(
+   *     Effect.provide(CliTestLayer)
+   *   )
+   * )
+   * output // => ["Hello, Alice!"]
    * ```
    *
    * @category combinators
@@ -800,9 +1026,27 @@ export const withHandler: {
    *
    * **Example** (Adding command handlers)
    *
-   * ```ts
-   * import { Console } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { Command, Flag } from "effect/unstable/cli"
+   * import { ChildProcessSpawner } from "effect/unstable/process"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
    *
    * // Command without initial handler
    * const greet = Command.make("greet", {
@@ -810,11 +1054,19 @@ export const withHandler: {
    * })
    *
    * // Add handler later
+   * const output: Array<string> = []
    * const greetWithHandler = greet.pipe(
    *   Command.withHandler((config: { readonly name: string }) =>
-   *     Console.log(`Hello, ${config.name}!`)
+   *     Effect.sync(() => output.push(`Hello, ${config.name}!`)).pipe(Effect.asVoid)
    *   )
    * )
+   *
+   * await Effect.runPromise(
+   *   Command.runWith(greetWithHandler, { version: "1.0.0" })(["--name", "Alice"]).pipe(
+   *     Effect.provide(CliTestLayer)
+   *   )
+   * )
+   * output // => ["Hello, Alice!"]
    * ```
    *
    * @category combinators
@@ -892,9 +1144,27 @@ const normalizeSubcommandEntries = (
  *
  * **Example** (Adding subcommands)
  *
- * ```ts
- * import { Console, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
  * // Parent command with shared flags
  * const git = Command.make("git").pipe(
@@ -904,19 +1174,29 @@ const normalizeSubcommandEntries = (
  * )
  *
  * // Subcommand that accesses parent config
+ * const output: Array<string> = []
  * const clone = Command.make("clone", {
  *   repository: Flag.string("repo")
  * }, (config) =>
  *   Effect.gen(function*() {
  *     const parent = yield* git // Access parent's parsed config
  *     if (parent.verbose) {
- *       yield* Console.log("Verbose mode enabled")
+ *       yield* Effect.sync(() => output.push("Verbose mode enabled"))
  *     }
- *     yield* Console.log(`Cloning ${config.repository}`)
+ *     yield* Effect.sync(() => output.push(`Cloning ${config.repository}`))
  *   }))
  *
  * const app = git.pipe(Command.withSubcommands([clone]))
- * // Usage: git --verbose clone --repo github.com/foo/bar
+ *
+ * await Effect.runPromise(
+ *   Command.runWith(app, { version: "1.0.0" })([
+ *     "--verbose",
+ *     "clone",
+ *     "--repo",
+ *     "github.com/foo/bar"
+ *   ]).pipe(Effect.provide(CliTestLayer))
+ * )
+ * output // => ["Verbose mode enabled", "Cloning github.com/foo/bar"]
  * ```
  *
  * @category combinators
@@ -934,9 +1214,27 @@ export const withSubcommands: {
    *
    * **Example** (Adding subcommands)
    *
-   * ```ts
-   * import { Console, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { Command, Flag } from "effect/unstable/cli"
+   * import { ChildProcessSpawner } from "effect/unstable/process"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
    *
    * // Parent command with shared flags
    * const git = Command.make("git").pipe(
@@ -946,19 +1244,29 @@ export const withSubcommands: {
    * )
    *
    * // Subcommand that accesses parent config
+   * const output: Array<string> = []
    * const clone = Command.make("clone", {
    *   repository: Flag.string("repo")
    * }, (config) =>
    *   Effect.gen(function*() {
    *     const parent = yield* git // Access parent's parsed config
    *     if (parent.verbose) {
-   *       yield* Console.log("Verbose mode enabled")
+   *       yield* Effect.sync(() => output.push("Verbose mode enabled"))
    *     }
-   *     yield* Console.log(`Cloning ${config.repository}`)
+   *     yield* Effect.sync(() => output.push(`Cloning ${config.repository}`))
    *   }))
    *
    * const app = git.pipe(Command.withSubcommands([clone]))
-   * // Usage: git --verbose clone --repo github.com/foo/bar
+   *
+   * await Effect.runPromise(
+   *   Command.runWith(app, { version: "1.0.0" })([
+   *     "--verbose",
+   *     "clone",
+   *     "--repo",
+   *     "github.com/foo/bar"
+   *   ]).pipe(Effect.provide(CliTestLayer))
+   * )
+   * output // => ["Verbose mode enabled", "Cloning github.com/foo/bar"]
    * ```
    *
    * @category combinators
@@ -984,9 +1292,27 @@ export const withSubcommands: {
    *
    * **Example** (Adding subcommands)
    *
-   * ```ts
-   * import { Console, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { Command, Flag } from "effect/unstable/cli"
+   * import { ChildProcessSpawner } from "effect/unstable/process"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
    *
    * // Parent command with shared flags
    * const git = Command.make("git").pipe(
@@ -996,19 +1322,29 @@ export const withSubcommands: {
    * )
    *
    * // Subcommand that accesses parent config
+   * const output: Array<string> = []
    * const clone = Command.make("clone", {
    *   repository: Flag.string("repo")
    * }, (config) =>
    *   Effect.gen(function*() {
    *     const parent = yield* git // Access parent's parsed config
    *     if (parent.verbose) {
-   *       yield* Console.log("Verbose mode enabled")
+   *       yield* Effect.sync(() => output.push("Verbose mode enabled"))
    *     }
-   *     yield* Console.log(`Cloning ${config.repository}`)
+   *     yield* Effect.sync(() => output.push(`Cloning ${config.repository}`))
    *   }))
    *
    * const app = git.pipe(Command.withSubcommands([clone]))
-   * // Usage: git --verbose clone --repo github.com/foo/bar
+   *
+   * await Effect.runPromise(
+   *   Command.runWith(app, { version: "1.0.0" })([
+   *     "--verbose",
+   *     "clone",
+   *     "--repo",
+   *     "github.com/foo/bar"
+   *   ]).pipe(Effect.provide(CliTestLayer))
+   * )
+   * output // => ["Verbose mode enabled", "Cloning github.com/foo/bar"]
    * ```
    *
    * @category combinators
@@ -1094,6 +1430,7 @@ export const withSubcommands: {
     description: impl.description,
     shortDescription: impl.shortDescription,
     alias: impl.alias,
+    unlisted: impl.unlisted,
     annotations: impl.annotations,
     globalFlags: impl.globalFlags,
     examples: impl.examples,
@@ -1212,6 +1549,7 @@ export const withSharedFlags: {
       description: impl.description,
       shortDescription: impl.shortDescription,
       alias: impl.alias,
+      unlisted: impl.unlisted,
       annotations: impl.annotations,
       globalFlags: impl.globalFlags,
       examples: impl.examples,
@@ -1307,18 +1645,42 @@ type ExtractSubcommandContext<T extends ReadonlyArray<Command.SubcommandEntry>>
  *
  * **Example** (Setting descriptions)
  *
- * ```ts
- * import { Console, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
+ * const output: Array<string> = []
  * const deploy = Command.make("deploy", {
  *   environment: Flag.string("env")
  * }, (config) =>
  *   Effect.gen(function*() {
- *     yield* Console.log(`Deploying to ${config.environment}`)
+ *     yield* Effect.sync(() => output.push(`Deploying to ${config.environment}`))
  *   })).pipe(
  *     Command.withDescription("Deploy the application to a specified environment")
  *   )
+ *
+ * await Effect.runPromise(
+ *   Command.runWith(deploy, { version: "1.0.0" })(["--env", "staging"]).pipe(Effect.provide(CliTestLayer))
+ * )
+ * output // => ["Deploying to staging"]
  * ```
  *
  * @category combinators
@@ -1335,18 +1697,42 @@ export const withDescription: {
    *
    * **Example** (Setting descriptions)
    *
-   * ```ts
-   * import { Console, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { Command, Flag } from "effect/unstable/cli"
+   * import { ChildProcessSpawner } from "effect/unstable/process"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
    *
+   * const output: Array<string> = []
    * const deploy = Command.make("deploy", {
    *   environment: Flag.string("env")
    * }, (config) =>
    *   Effect.gen(function*() {
-   *     yield* Console.log(`Deploying to ${config.environment}`)
+   *     yield* Effect.sync(() => output.push(`Deploying to ${config.environment}`))
    *   })).pipe(
    *     Command.withDescription("Deploy the application to a specified environment")
    *   )
+   *
+   * await Effect.runPromise(
+   *   Command.runWith(deploy, { version: "1.0.0" })(["--env", "staging"]).pipe(Effect.provide(CliTestLayer))
+   * )
+   * output // => ["Deploying to staging"]
    * ```
    *
    * @category combinators
@@ -1365,18 +1751,42 @@ export const withDescription: {
    *
    * **Example** (Setting descriptions)
    *
-   * ```ts
-   * import { Console, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { Command, Flag } from "effect/unstable/cli"
+   * import { ChildProcessSpawner } from "effect/unstable/process"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
    *
+   * const output: Array<string> = []
    * const deploy = Command.make("deploy", {
    *   environment: Flag.string("env")
    * }, (config) =>
    *   Effect.gen(function*() {
-   *     yield* Console.log(`Deploying to ${config.environment}`)
+   *     yield* Effect.sync(() => output.push(`Deploying to ${config.environment}`))
    *   })).pipe(
    *     Command.withDescription("Deploy the application to a specified environment")
    *   )
+   *
+   * await Effect.runPromise(
+   *   Command.runWith(deploy, { version: "1.0.0" })(["--env", "staging"]).pipe(Effect.provide(CliTestLayer))
+   * )
+   * output // => ["Deploying to staging"]
    * ```
    *
    * @category combinators
@@ -1478,7 +1888,7 @@ export const withAlias: {
 ) => makeCommand({ ...toImpl(self), alias }))
 
 /**
- * Hides a subcommand from parent help output, shell completions, and
+ * Omits a subcommand from parent help output, shell completions, and
  * "did you mean?" suggestions while keeping it fully invocable by exact name.
  *
  * **When to use**
@@ -1486,29 +1896,31 @@ export const withAlias: {
  * Use when experimental or internal subcommands should be accepted but not advertised on
  * the public CLI surface.
  *
- * **Example** (Hiding a subcommand)
+ * **Example** (Unlisting a subcommand)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Command } from "effect/unstable/cli"
  *
  * // `experimental` still runs when invoked as `mycli experimental`,
  * // but it does not appear under SUBCOMMANDS in `mycli --help`.
  * const experimental = Command.make("experimental").pipe(
- *   Command.withHidden
+ *   Command.unlisted
  * )
  *
  * const root = Command.make("mycli").pipe(
  *   Command.withSubcommands([experimental])
  * )
+ *
+ * root.subcommands[0].commands[0].unlisted // => true
  * ```
  *
  * @category combinators
  * @since 4.0.0
  */
-export const withHidden = <const Name extends string, Input, E, R, ContextInput>(
+export const unlisted = <const Name extends string, Input, E, R, ContextInput>(
   self: Command<Name, Input, ContextInput, E, R>
 ): Command<Name, Input, ContextInput, E, R> =>
-  makeCommand({ ...toImpl(self), hidden: true }) as Command<Name, Input, ContextInput, E, R>
+  makeCommand({ ...toImpl(self), unlisted: true }) as Command<Name, Input, ContextInput, E, R>
 
 /**
  * Adds a custom annotation to a command.
@@ -1689,7 +2101,7 @@ export const annotateMerge: {
  *
  * **Example** (Adding usage examples)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Command } from "effect/unstable/cli"
  *
  * const login = Command.make("login").pipe(
@@ -1698,6 +2110,8 @@ export const annotateMerge: {
  *     { command: "myapp login --token sbp_abc123", description: "Log in with a token" }
  *   ])
  * )
+ *
+ * login.examples.map((example) => example.command) // => ["myapp login", "myapp login --token sbp_abc123"]
  * ```
  *
  * @category combinators
@@ -1714,7 +2128,7 @@ export const withExamples: {
    *
    * **Example** (Adding usage examples)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Command } from "effect/unstable/cli"
    *
    * const login = Command.make("login").pipe(
@@ -1723,6 +2137,8 @@ export const withExamples: {
    *     { command: "myapp login --token sbp_abc123", description: "Log in with a token" }
    *   ])
    * )
+   *
+   * login.examples.map((example) => example.command) // => ["myapp login", "myapp login --token sbp_abc123"]
    * ```
    *
    * @category combinators
@@ -1741,7 +2157,7 @@ export const withExamples: {
    *
    * **Example** (Adding usage examples)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Command } from "effect/unstable/cli"
    *
    * const login = Command.make("login").pipe(
@@ -1750,6 +2166,8 @@ export const withExamples: {
    *     { command: "myapp login --token sbp_abc123", description: "Log in with a token" }
    *   ])
    * )
+   *
+   * login.examples.map((example) => example.command) // => ["myapp login", "myapp login --token sbp_abc123"]
    * ```
    *
    * @category combinators
@@ -1783,16 +2201,35 @@ const mapHandler = <Name extends string, Input, E, R, ContextInput, E2, R2>(
  *
  * **Example** (Providing command services)
  *
- * ```ts
- * import { Effect, FileSystem, PlatformError } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, PlatformError, Stdio, Terminal } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
+ * const output: Array<string> = []
  * const deploy = Command.make("deploy", {
  *   env: Flag.string("env")
  * }, (config) =>
  *   Effect.gen(function*() {
  *     const fs = yield* FileSystem.FileSystem
- *     // Use fs...
+ *     yield* Effect.sync(() => output.push(`Using file system for ${config.env}`))
  *   })).pipe(
  *     // Provide FileSystem based on the --env flag
  *     Command.provide((config) =>
@@ -1809,6 +2246,11 @@ const mapHandler = <Name extends string, Input, E, R, ContextInput, E2, R2>(
  *         })
  *     )
  *   )
+ *
+ * await Effect.runPromise(
+ *   Command.runWith(deploy, { version: "1.0.0" })(["--env", "local"]).pipe(Effect.provide(CliTestLayer))
+ * )
+ * output // => ["Using file system for local"]
  * ```
  *
  * @category providing services
@@ -1821,16 +2263,35 @@ export const provide: {
    *
    * **Example** (Providing command services)
    *
-   * ```ts
-   * import { Effect, FileSystem, PlatformError } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, PlatformError, Stdio, Terminal } from "effect"
    * import { Command, Flag } from "effect/unstable/cli"
+   * import { ChildProcessSpawner } from "effect/unstable/process"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
    *
+   * const output: Array<string> = []
    * const deploy = Command.make("deploy", {
    *   env: Flag.string("env")
    * }, (config) =>
    *   Effect.gen(function*() {
    *     const fs = yield* FileSystem.FileSystem
-   *     // Use fs...
+   *     yield* Effect.sync(() => output.push(`Using file system for ${config.env}`))
    *   })).pipe(
    *     // Provide FileSystem based on the --env flag
    *     Command.provide((config) =>
@@ -1847,6 +2308,11 @@ export const provide: {
    *         })
    *     )
    *   )
+   *
+   * await Effect.runPromise(
+   *   Command.runWith(deploy, { version: "1.0.0" })(["--env", "local"]).pipe(Effect.provide(CliTestLayer))
+   * )
+   * output // => ["Using file system for local"]
    * ```
    *
    * @category providing services
@@ -1866,16 +2332,35 @@ export const provide: {
    *
    * **Example** (Providing command services)
    *
-   * ```ts
-   * import { Effect, FileSystem, PlatformError } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, PlatformError, Stdio, Terminal } from "effect"
    * import { Command, Flag } from "effect/unstable/cli"
+   * import { ChildProcessSpawner } from "effect/unstable/process"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
    *
+   * const output: Array<string> = []
    * const deploy = Command.make("deploy", {
    *   env: Flag.string("env")
    * }, (config) =>
    *   Effect.gen(function*() {
    *     const fs = yield* FileSystem.FileSystem
-   *     // Use fs...
+   *     yield* Effect.sync(() => output.push(`Using file system for ${config.env}`))
    *   })).pipe(
    *     // Provide FileSystem based on the --env flag
    *     Command.provide((config) =>
@@ -1892,6 +2377,11 @@ export const provide: {
    *         })
    *     )
    *   )
+   *
+   * await Effect.runPromise(
+   *   Command.runWith(deploy, { version: "1.0.0" })(["--env", "local"]).pipe(Effect.provide(CliTestLayer))
+   * )
+   * output // => ["Using file system for local"]
    * ```
    *
    * @category providing services
@@ -2093,19 +2583,42 @@ export const provideEffectDiscard: {
  *
  * **Example** (Constructing command arguments)
  *
- * ```ts
- * import { Console, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Console, Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { Command } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
  * const command = Command.make("app")
- *
- * const program = Effect.gen(function*() {
- *   const args = yield* Command.wizard(command)
- *   yield* Console.log(args.join(" "))
+ * const silentConsole: Console.Console = Object.assign(Object.create(console), {
+ *   log: () => {}
  * })
+ *
+ * const program = Command.wizard(command).pipe(
+ *   Effect.provideService(Console.Console, silentConsole),
+ *   Effect.provide(CliTestLayer)
+ * )
+ *
+ * await Effect.runPromise(program) // => ["app"]
  * ```
  *
- * @category command execution
+ * @category running
  * @since 4.0.0
  */
 export const wizard = <Name extends string, Input, E, R, ContextInput>(
@@ -2178,26 +2691,50 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
  *
  * **Example** (Running commands with standard input)
  *
- * ```ts
- * import { Console, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({
+ *     args: Effect.succeed(["--name", "Alice"])
+ *   }),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
+ * const output: Array<string> = []
  * const greetCommand = Command.make("greet", {
  *   name: Flag.string("name")
  * }, (config) =>
  *   Effect.gen(function*() {
- *     yield* Console.log(`Hello, ${config.name}!`)
+ *     yield* Effect.sync(() => output.push(`Hello, ${config.name}!`))
  *   }))
  *
  * // Automatically gets args from the Stdio service
  * const program = Command.run(greetCommand, {
  *   version: "1.0.0"
  * })
+ *
+ * await Effect.runPromise(program.pipe(Effect.provide(CliTestLayer)))
+ * output // => ["Hello, Alice!"]
  * ```
  *
  * @see {@link runWith} for running a command with an explicit argument array
  *
- * @category command execution
+ * @category running
  * @since 4.0.0
  */
 export const run: {
@@ -2211,26 +2748,50 @@ export const run: {
    *
    * **Example** (Running commands with standard input)
    *
-   * ```ts
-   * import { Console, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { Command, Flag } from "effect/unstable/cli"
+   * import { ChildProcessSpawner } from "effect/unstable/process"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({
+   *     args: Effect.succeed(["--name", "Alice"])
+   *   }),
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
    *
+   * const output: Array<string> = []
    * const greetCommand = Command.make("greet", {
    *   name: Flag.string("name")
    * }, (config) =>
    *   Effect.gen(function*() {
-   *     yield* Console.log(`Hello, ${config.name}!`)
+   *     yield* Effect.sync(() => output.push(`Hello, ${config.name}!`))
    *   }))
    *
    * // Automatically gets args from the Stdio service
    * const program = Command.run(greetCommand, {
    *   version: "1.0.0"
    * })
+   *
+   * await Effect.runPromise(program.pipe(Effect.provide(CliTestLayer)))
+   * output // => ["Hello, Alice!"]
    * ```
    *
    * @see {@link runWith} for running a command with an explicit argument array
    *
-   * @category command execution
+   * @category running
    * @since 4.0.0
    */
   (
@@ -2250,26 +2811,50 @@ export const run: {
    *
    * **Example** (Running commands with standard input)
    *
-   * ```ts
-   * import { Console, Effect } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { Command, Flag } from "effect/unstable/cli"
+   * import { ChildProcessSpawner } from "effect/unstable/process"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({
+   *     args: Effect.succeed(["--name", "Alice"])
+   *   }),
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
    *
+   * const output: Array<string> = []
    * const greetCommand = Command.make("greet", {
    *   name: Flag.string("name")
    * }, (config) =>
    *   Effect.gen(function*() {
-   *     yield* Console.log(`Hello, ${config.name}!`)
+   *     yield* Effect.sync(() => output.push(`Hello, ${config.name}!`))
    *   }))
    *
    * // Automatically gets args from the Stdio service
    * const program = Command.run(greetCommand, {
    *   version: "1.0.0"
    * })
+   *
+   * await Effect.runPromise(program.pipe(Effect.provide(CliTestLayer)))
+   * output // => ["Hello, Alice!"]
    * ```
    *
    * @see {@link runWith} for running a command with an explicit argument array
    *
-   * @category command execution
+   * @category running
    * @since 4.0.0
    */
   <Name extends string, Input, E, R, ContextInput>(
@@ -2301,17 +2886,36 @@ export const run: {
  *
  * **Example** (Running commands with explicit arguments)
  *
- * ```ts
- * import { Console, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
+ * const output: Array<string> = []
  * const greet = Command.make("greet", {
  *   name: Flag.string("name"),
  *   count: Flag.integer("count").pipe(Flag.withDefault(1))
  * }, (config) =>
  *   Effect.gen(function*() {
  *     for (let i = 0; i < config.count; i++) {
- *       yield* Console.log(`Hello, ${config.name}!`)
+ *       yield* Effect.sync(() => output.push(`Hello, ${config.name}!`))
  *     }
  *   }))
  *
@@ -2319,18 +2923,14 @@ export const run: {
  * const testProgram = Effect.gen(function*() {
  *   const runCommand = Command.runWith(greet, { version: "1.0.0" })
  *
- *   // Test normal execution
  *   yield* runCommand(["--name", "Alice", "--count", "2"])
- *
- *   // Test help display
- *   yield* runCommand(["--help"])
- *
- *   // Test version display
- *   yield* runCommand(["--version"])
  * })
+ *
+ * await Effect.runPromise(testProgram.pipe(Effect.provide(CliTestLayer)))
+ * output // => ["Hello, Alice!", "Hello, Alice!"]
  * ```
  *
- * @category command execution
+ * @category running
  * @since 4.0.0
  */
 export const runWith = <const Name extends string, Input, E, R, ContextInput>(