effect 4.0.0-beta.99 → 4.0.0-rc.108

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

@@ -39,9 +39,27 @@ import * as Param from "./Param.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(
@@ -66,9 +84,15 @@ import * as Param from "./Param.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
@@ -108,11 +132,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;
 }
 /**
  * Companion namespace containing type-level helpers and configuration shapes
@@ -158,19 +182,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")
@@ -179,7 +203,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
@@ -217,7 +243,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"
          *
@@ -237,6 +263,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
@@ -273,7 +305,7 @@ export declare namespace Command {
             readonly commands: NonEmptyReadonlyArray<Command.Any>;
         }>;
         readonly annotations: Context.Context<never>;
-        readonly hidden: boolean;
+        readonly unlisted: boolean;
     }
     /**
      * A grouped set of subcommands used by `Command.withSubcommands`.
@@ -332,9 +364,27 @@ export type Services<C> = C extends Command<infer _Name, infer _Input, infer _Co
  *
  * **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({
@@ -343,19 +393,31 @@ export type Services<C> = C extends Command<infer _Name, infer _Input, infer _Co
  *   })
  * )
  *
+ * 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
@@ -404,9 +466,27 @@ export declare const isCommand: (u: unknown) => u is Command.Any;
  *
  * **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")
@@ -431,19 +511,29 @@ export declare const isCommand: (u: unknown) => u is Command.Any;
  * })
  *
  * // 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
@@ -462,9 +552,27 @@ export declare 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")
@@ -489,19 +597,29 @@ export declare 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
@@ -520,9 +638,27 @@ export declare 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")
@@ -547,19 +683,29 @@ export declare 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
@@ -578,9 +724,27 @@ export declare 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")
@@ -605,19 +769,29 @@ export declare 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
@@ -630,9 +804,27 @@ export declare 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", {
@@ -640,11 +832,19 @@ export declare 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
@@ -656,9 +856,27 @@ export declare 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", {
@@ -666,11 +884,19 @@ export declare 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
@@ -682,9 +908,27 @@ export declare 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", {
@@ -692,11 +936,19 @@ export declare 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
@@ -715,9 +967,27 @@ export declare const withHandler: {
  *
  * **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(
@@ -727,19 +997,29 @@ export declare const withHandler: {
  * )
  *
  * // 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
@@ -757,9 +1037,27 @@ export declare 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(
@@ -769,19 +1067,29 @@ export declare 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
@@ -799,9 +1107,27 @@ export declare 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(
@@ -811,19 +1137,29 @@ export declare 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
@@ -920,18 +1256,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
@@ -948,18 +1308,42 @@ export declare 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
@@ -976,18 +1360,42 @@ export declare 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
@@ -1073,7 +1481,7 @@ export declare const withAlias: {
     <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>, alias: string): Command<Name, Input, ContextInput, E, R>;
 };
 /**
- * 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**
@@ -1081,26 +1489,28 @@ export declare 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 declare const withHidden: <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Input, ContextInput, E, R>;
+export declare const unlisted: <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Input, ContextInput, E, R>;
 /**
  * Adds a custom annotation to a command.
  *
@@ -1254,7 +1664,7 @@ export declare const annotateMerge: {
  *
  * **Example** (Adding usage examples)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Command } from "effect/unstable/cli"
  *
  * const login = Command.make("login").pipe(
@@ -1263,6 +1673,8 @@ export declare 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
@@ -1279,7 +1691,7 @@ export declare const withExamples: {
      *
      * **Example** (Adding usage examples)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Command } from "effect/unstable/cli"
      *
      * const login = Command.make("login").pipe(
@@ -1288,6 +1700,8 @@ export declare 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
@@ -1304,7 +1718,7 @@ export declare const withExamples: {
      *
      * **Example** (Adding usage examples)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Command } from "effect/unstable/cli"
      *
      * const login = Command.make("login").pipe(
@@ -1313,6 +1727,8 @@ export declare 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
@@ -1326,16 +1742,35 @@ export declare const withExamples: {
  *
  * **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) =>
@@ -1352,6 +1787,11 @@ export declare const withExamples: {
  *         })
  *     )
  *   )
+ *
+ * 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
@@ -1364,16 +1804,35 @@ export declare 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) =>
@@ -1390,6 +1849,11 @@ export declare 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
@@ -1404,16 +1868,35 @@ export declare 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) =>
@@ -1430,6 +1913,11 @@ export declare 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
@@ -1566,19 +2054,42 @@ export declare 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 declare const wizard: <Name extends string, Input, E, R, ContextInput>(command: Command<Name, Input, ContextInput, E, R>, options?: {
@@ -1592,28 +2103,57 @@ export declare const wizard: <Name extends string, Input, E, R, ContextInput>(co
  * Use when command-line arguments should come from `Stdio` at the application
  * entry point.
  *
+ * Help documents are always rendered. By default, parse error details and
+ * `CliError.UserError` failures are also rendered with the installed
+ * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
+ * `false` when the host application owns error rendering.
+ *
  * **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 declare const run: {
@@ -1625,32 +2165,62 @@ export declare const run: {
      * Use when command-line arguments should come from `Stdio` at the application
      * entry point.
      *
+     * Help documents are always rendered. By default, parse error details and
+     * `CliError.UserError` failures are also rendered with the installed
+     * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
+     * `false` when the host application owns error rendering.
+     *
      * **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
      */
     (config: {
         readonly version: string;
+        readonly renderErrors?: boolean | undefined;
     }): <Name extends string, Input, E, R, ContextInput>(command: Command<Name, Input, ContextInput, E, R>) => Effect.Effect<void, E | CliError.CliError, R | Environment>;
     /**
      * Runs a command using the arguments supplied by the `Stdio` service.
@@ -1660,32 +2230,62 @@ export declare const run: {
      * Use when command-line arguments should come from `Stdio` at the application
      * entry point.
      *
+     * Help documents are always rendered. By default, parse error details and
+     * `CliError.UserError` failures are also rendered with the installed
+     * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
+     * `false` when the host application owns error rendering.
+     *
      * **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>(command: Command<Name, Input, ContextInput, E, R>, config: {
         readonly version: string;
+        readonly renderErrors?: boolean | undefined;
     }): Effect.Effect<void, E | CliError.CliError, R | Environment>;
 };
 /**
@@ -1696,19 +2296,43 @@ export declare const run: {
  * Use when you need to test CLI applications or programmatically execute
  * commands with specific arguments.
  *
+ * Help documents are always rendered. By default, parse error details and
+ * `CliError.UserError` failures are also rendered with the installed
+ * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
+ * `false` when the host application owns error rendering.
+ *
  * **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}!`))
  *     }
  *   }))
  *
@@ -1716,22 +2340,19 @@ export declare 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 declare const runWith: <const Name extends string, Input, E, R, ContextInput>(command: Command<Name, Input, ContextInput, E, R>, config: {
     readonly version: string;
+    readonly renderErrors?: boolean | undefined;
 }) => (input: ReadonlyArray<string>) => Effect.Effect<void, Exclude<E, Terminal.QuitError> | CliError.CliError, R | Environment>;
 export {};
 //# sourceMappingURL=Command.d.ts.map