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

package/src/unstable/cli/Command.ts

@@ -22,6 +22,7 @@ import type * as Path from "../../Path.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as References from "../../References.ts"
 import * as Result from "../../Result.ts"
+import * as Runtime from "../../Runtime.ts"
 import * as Stdio from "../../Stdio.ts"
 import * as Terminal from "../../Terminal.ts"
 import type { Contravariant, Covariant, NoInfer, Simplify } from "../../Types.ts"
@@ -57,9 +58,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 +103,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 +166,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 +219,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 +240,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 +288,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 +308,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 +353,7 @@ export declare namespace Command {
       readonly commands: NonEmptyReadonlyArray<Command.Any>
     }>
     readonly annotations: Context.Context<never>
-    readonly hidden: boolean
+    readonly unlisted: boolean
   }
 
   /**
@@ -399,9 +432,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 +461,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 +541,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 +586,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 +631,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 +676,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 +722,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 +767,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 +813,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 +858,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 +913,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 +941,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 +969,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 +997,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 +1027,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 +1055,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 +1145,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 +1175,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 +1215,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 +1245,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 +1293,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 +1323,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
@@ -1068,7 +1405,7 @@ export const withSubcommands: {
 
     const context = yield* impl.parseContext(raw)
     const result = yield* sub.parse(raw.subcommand.value.parsedInput)
-    return Object.assign({}, context, { [SubcommandStateSymbol]: { name: sub.name, result } }) as NextInput
+    return { ...context, [SubcommandStateSymbol]: { name: sub.name, result } } as NextInput
   })
 
   const handle = Effect.fnUntraced(function*(input: NextInput, path: ReadonlyArray<string>) {
@@ -1094,6 +1431,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,
@@ -1184,20 +1522,20 @@ export const withSharedFlags: {
     type NextInput = Simplify<Input & SharedInput>
     type NextContextInput = Simplify<ContextInput & SharedInput>
 
-    const parseShared = makeParser(sharedConfig) as (
+    const parseShared = makeParser(sharedConfig, { allowLeftovers: true }) as (
       input: ParsedTokens
     ) => Effect.Effect<SharedInput, CliError.CliError, Environment>
 
     const parse = Effect.fnUntraced(function*(raw: ParsedTokens) {
       const base = yield* impl.parse(raw)
       const shared = yield* parseShared(raw)
-      return Object.assign({}, base, shared) as NextInput
+      return { ...(base as object), ...(shared as object) } as NextInput
     })
 
     const parseContext = Effect.fnUntraced(function*(raw: ParsedTokens) {
       const base = yield* impl.parseContext(raw)
       const shared = yield* parseShared(raw)
-      return Object.assign({}, base, shared) as NextContextInput
+      return { ...(base as object), ...(shared as object) } as NextContextInput
     })
 
     const handle = (
@@ -1212,6 +1550,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 +1646,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 +1698,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 +1752,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 +1889,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 +1897,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 +2102,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 +2111,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 +2129,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 +2138,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 +2158,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 +2167,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 +2202,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 +2247,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 +2264,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 +2309,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 +2333,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 +2378,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 +2584,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>(
@@ -2156,18 +2670,26 @@ const getOutOfScopeGlobalFlagErrors = (
 
 const showHelp = <Name extends string, Input, E, R, ContextInput>(
   command: Command<Name, Input, ContextInput, E, R>,
-  error: CliError.ShowHelp
+  error: CliError.ShowHelp,
+  renderErrors: boolean
 ): Effect.Effect<void, CliError.CliError, Environment> =>
   Effect.gen(function*() {
     const { builtIns } = yield* CliConfig.CliConfig
     const formatter = yield* CliOutput.Formatter
     const helpDoc = yield* getHelpForCommandPath(command, error.commandPath, builtIns)
     yield* Console.log(formatter.formatHelpDoc(helpDoc))
-    if (error.errors.length > 0) {
+    if (renderErrors && error.errors.length > 0) {
       yield* Console.error(formatter.formatErrors(error.errors as any))
     }
   })
 
+const showUserError = (error: CliError.UserError): Effect.Effect<void> =>
+  Effect.gen(function*() {
+    const formatter = yield* CliOutput.Formatter
+    yield* Console.error(formatter.formatError(error))
+    error[Runtime.errorReported] = false
+  })
+
 /**
  * Runs a command using the arguments supplied by the `Stdio` service.
  *
@@ -2176,28 +2698,57 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
  * 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 const run: {
@@ -2209,33 +2760,63 @@ export 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>
@@ -2248,40 +2829,71 @@ export 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>
 } = dual(2, <Name extends string, Input, E, R, ContextInput>(
   command: Command<Name, Input, ContextInput, E, R>,
   config: {
     readonly version: string
+    readonly renderErrors?: boolean | undefined
   }
 ) =>
   Stdio.Stdio.use(({ args }) =>
@@ -2299,19 +2911,43 @@ export 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}!`))
  *     }
  *   }))
  *
@@ -2319,24 +2955,21 @@ 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>(
   command: Command<Name, Input, ContextInput, E, R>,
   config: {
     readonly version: string
+    readonly renderErrors?: boolean | undefined
   }
 ): (
   input: ReadonlyArray<string>
@@ -2403,7 +3036,7 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
             }))
             if (shouldRun) {
               yield* Console.log()
-              yield* runWith(command, config)(wizardArgs.slice(1))
+              yield* runWith(command, { ...config, renderErrors: false })(wizardArgs.slice(1))
             }
           }).pipe(
             Effect.catchTag("QuitError", () => Console.log(Wizard.renderQuit()))
@@ -2451,7 +3084,14 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
         CliError.isCliError(error) && error._tag === "ShowHelp"
           ? Result.succeed(error)
           : Result.fail(error),
-      (error) => Effect.andThen(showHelp(command, error), Effect.fail(error))
+      (error) => Effect.andThen(showHelp(command, error, config.renderErrors !== false), Effect.fail(error))
+    ),
+    Effect.catchFilter(
+      (error) =>
+        config.renderErrors !== false && CliError.isCliError(error) && error._tag === "UserError"
+          ? Result.succeed(error)
+          : Result.fail(error),
+      (error) => Effect.andThen(showUserError(error), Effect.fail(error))
     ),
     Effect.catchFilter(
       (e) =>