effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/unstable/cli/Flag.ts

@@ -43,11 +43,12 @@ export interface Flag<A> extends Param.Param<typeof Param.flagKind, A> {}
  *
  * **Example** (Creating string flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const nameFlag = Flag.string("name")
  * // Usage: --name "John Doe"
+ * nameFlag.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -60,11 +61,12 @@ export const string = (name: string): Flag<string> => Param.string(Param.flagKin
  *
  * **Example** (Creating boolean flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const verboseFlag = Flag.boolean("verbose")
  * // Usage: --verbose (true) or --no-verbose (false)
+ * verboseFlag.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -77,11 +79,12 @@ export const boolean = (name: string): Flag<boolean> => Param.boolean(Param.flag
  *
  * **Example** (Creating integer flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const portFlag = Flag.integer("port")
  * // Usage: --port 8080
+ * portFlag.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -94,11 +97,12 @@ export const integer = (name: string): Flag<number> => Param.integer(Param.flagK
  *
  * **Example** (Creating float flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const rateFlag = Flag.float("rate")
  * // Usage: --rate 3.14
+ * rateFlag.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -111,11 +115,12 @@ export const float = (name: string): Flag<number> => Param.float(Param.flagKind,
  *
  * **Example** (Creating date flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const startDateFlag = Flag.date("start-date")
  * // Usage: --start-date 2023-12-25
+ * startDateFlag.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -129,7 +134,7 @@ export const date = (name: string): Flag<Date> => Param.date(Param.flagKind, nam
  *
  * **Example** (Creating flag choices with values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // simple enum like choice mapping directly to string union
@@ -141,6 +146,7 @@ export const date = (name: string): Flag<Date> => Param.date(Param.flagKind, nam
  *   ["info", "Info" as const],
  *   ["error", "Error" as const]
  * ])
+ * const kinds = [color.kind, logLevel.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -179,7 +185,7 @@ export const choice = <const Choices extends ReadonlyArray<string>>(
  *
  * **Example** (Creating path flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Basic path flag
@@ -196,6 +202,7 @@ export const choice = <const Choices extends ReadonlyArray<string>>(
  *   pathType: "directory",
  *   typeName: "OUTPUT_DIRECTORY"
  * })
+ * const kinds = [pathFlag.kind, fileFlag.kind, dirFlag.kind] // => ["flag", "flag", "flag"]
  * ```
  *
  * @category constructors
@@ -212,7 +219,7 @@ export const path = (name: string, options?: {
  *
  * **Example** (Creating file flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Basic file flag
@@ -222,6 +229,7 @@ export const path = (name: string, options?: {
  * // File that must exist
  * const configFlag = Flag.file("config", { mustExist: true })
  * // Usage: --config ./config.yaml (file must exist)
+ * const kinds = [inputFlag.kind, configFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -236,7 +244,7 @@ export const file = (name: string, options?: {
  *
  * **Example** (Creating directory flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Basic directory flag
@@ -246,6 +254,7 @@ export const file = (name: string, options?: {
  * // Directory that must exist
  * const sourceFlag = Flag.directory("source", { mustExist: true })
  * // Usage: --source ./src (directory must exist)
+ * const kinds = [outputFlag.kind, sourceFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -266,20 +275,39 @@ export const directory = (name: string, options?: {
  *
  * **Example** (Creating redacted flags)
  *
- * ```ts
- * import { Effect, Redacted } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Redacted, Stdio, Terminal } from "effect"
  * import { 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 passwordFlag = Flag.redacted("password")
  *
  * const program = Effect.gen(function*() {
- *   const [leftover, password] = yield* passwordFlag.parse({
+ *   const [, password] = yield* passwordFlag.parse({
  *     arguments: [],
  *     flags: { "password": ["abc123"] }
  *   })
- *   const value = Redacted.value(password) // Access the underlying value
- *   console.log("Password length:", value.length)
+ *   return Redacted.value(password).length
  * })
+ *
+ * await Effect.runPromise(program.pipe(Effect.provide(CliTestLayer))) // => 6
  * ```
  *
  * @category constructors
@@ -292,11 +320,12 @@ export const redacted = (name: string): Flag<Redacted.Redacted<string>> => Param
  *
  * **Example** (Reading file text)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const config = Flag.fileText("config-file")
  * // --config-file ./app.json will read the file content
+ * config.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -314,7 +343,7 @@ export const fileText = (name: string): Flag<string> => Param.fileText(Param.fla
  *
  * **Example** (Parsing file contents)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Will use the extension of the file passed on the command line to determine
@@ -323,6 +352,7 @@ export const fileText = (name: string): Flag<string> => Param.fileText(Param.fla
  *
  * // Will use the JSON parser
  * const jsonConfig = Flag.fileParse("json-config", { format: "json" })
+ * const kinds = [config.kind, jsonConfig.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -339,7 +369,7 @@ export const fileParse = (
  *
  * **Example** (Validating file contents)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Flag } from "effect/unstable/cli"
  *
@@ -349,6 +379,7 @@ export const fileParse = (
  * })
  *
  * const config = Flag.fileSchema("config", ConfigSchema, { format: "json" })
+ * config.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -375,11 +406,12 @@ export const fileSchema = <A>(
  *
  * **Example** (Parsing key-value pairs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const env = Flag.keyValuePair("env")
  * // --env FOO=bar --env BAZ=qux will parse to { FOO: "bar", BAZ: "qux" }
+ * env.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -393,14 +425,14 @@ export const keyValuePair = (name: string): Flag<Record<string, string>> => Para
  *
  * **Example** (Creating sentinel flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const makeValueFlag = (includeValue: boolean) =>
  *   includeValue ? Flag.string("value") : Flag.none
  *
- * console.log(makeValueFlag(true) === Flag.none) // false
- * console.log(makeValueFlag(false) === Flag.none) // true
+ * makeValueFlag(true) === Flag.none // => false
+ * makeValueFlag(false) === Flag.none // => true
  * ```
  *
  * @category constructors
@@ -417,7 +449,7 @@ export const none: Flag<never> = Param.none(Param.flagKind)
  *
  * **Example** (Adding flag aliases)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Flag can be used as both --verbose and -v
@@ -430,6 +462,7 @@ export const none: Flag<never> = Param.none(Param.flagKind)
  *   Flag.withAlias("h"),
  *   Flag.withAlias("?")
  * )
+ * const kinds = [verboseFlag.kind, helpFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category aliasing
@@ -445,7 +478,7 @@ export const withAlias: {
    *
    * **Example** (Adding flag aliases)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * // Flag can be used as both --verbose and -v
@@ -458,6 +491,7 @@ export const withAlias: {
    *   Flag.withAlias("h"),
    *   Flag.withAlias("?")
    * )
+   * const kinds = [verboseFlag.kind, helpFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category aliasing
@@ -473,7 +507,7 @@ export const withAlias: {
    *
    * **Example** (Adding flag aliases)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * // Flag can be used as both --verbose and -v
@@ -486,6 +520,7 @@ export const withAlias: {
    *   Flag.withAlias("h"),
    *   Flag.withAlias("?")
    * )
+   * const kinds = [verboseFlag.kind, helpFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category aliasing
@@ -499,7 +534,7 @@ export const withAlias: {
  *
  * **Example** (Adding help descriptions)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const portFlag = Flag.integer("port").pipe(
@@ -509,9 +544,10 @@ export const withAlias: {
  * const configFlag = Flag.file("config").pipe(
  *   Flag.withDescription("Path to the configuration file")
  * )
+ * const kinds = [portFlag.kind, configFlag.kind] // => ["flag", "flag"]
  * ```
  *
- * @category help documentation
+ * @category metadata
  * @since 4.0.0
  */
 export const withDescription: {
@@ -520,7 +556,7 @@ export const withDescription: {
    *
    * **Example** (Adding help descriptions)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * const portFlag = Flag.integer("port").pipe(
@@ -530,9 +566,10 @@ export const withDescription: {
    * const configFlag = Flag.file("config").pipe(
    *   Flag.withDescription("Path to the configuration file")
    * )
+   * const kinds = [portFlag.kind, configFlag.kind] // => ["flag", "flag"]
    * ```
    *
-   * @category help documentation
+   * @category metadata
    * @since 4.0.0
    */
   <A>(description: string): (self: Flag<A>) => Flag<A>
@@ -541,7 +578,7 @@ export const withDescription: {
    *
    * **Example** (Adding help descriptions)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * const portFlag = Flag.integer("port").pipe(
@@ -551,9 +588,10 @@ export const withDescription: {
    * const configFlag = Flag.file("config").pipe(
    *   Flag.withDescription("Path to the configuration file")
    * )
+   * const kinds = [portFlag.kind, configFlag.kind] // => ["flag", "flag"]
    * ```
    *
-   * @category help documentation
+   * @category metadata
    * @since 4.0.0
    */
   <A>(self: Flag<A>, description: string): Flag<A>
@@ -573,7 +611,7 @@ export const withDescription: {
  *
  * **Example** (Setting metavars)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const databaseFlag = Flag.string("database-url").pipe(
@@ -586,6 +624,7 @@ export const withDescription: {
  *   Flag.withMetavar("SECONDS")
  * )
  * // In help: --timeout SECONDS
+ * const kinds = [databaseFlag.kind, timeoutFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category metadata
@@ -606,7 +645,7 @@ export const withMetavar: {
    *
    * **Example** (Setting metavars)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * const databaseFlag = Flag.string("database-url").pipe(
@@ -619,6 +658,7 @@ export const withMetavar: {
    *   Flag.withMetavar("SECONDS")
    * )
    * // In help: --timeout SECONDS
+   * const kinds = [databaseFlag.kind, timeoutFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category metadata
@@ -639,7 +679,7 @@ export const withMetavar: {
    *
    * **Example** (Setting metavars)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * const databaseFlag = Flag.string("database-url").pipe(
@@ -652,6 +692,7 @@ export const withMetavar: {
    *   Flag.withMetavar("SECONDS")
    * )
    * // In help: --timeout SECONDS
+   * const kinds = [databaseFlag.kind, timeoutFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category metadata
@@ -672,13 +713,14 @@ export const withMetavar: {
  *
  * **Example** (Hiding a flag from help)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Flag still parses --experimental-foo, but it does not appear in --help.
  * const experimental = Flag.boolean("experimental-foo").pipe(
  *   Flag.withHidden
  * )
+ * experimental.kind // => "flag"
  * ```
  *
  * @category metadata
@@ -691,23 +733,39 @@ export const withHidden = <A>(self: Flag<A>): Flag<A> => Param.withHidden(self)
  *
  * **Example** (Making flags optional)
  *
- * ```ts
- * import { Effect, Option } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Option, Path, Stdio, Terminal } from "effect"
  * import { 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 optionalPort = Flag.optional(Flag.integer("port"))
  *
  * const program = Effect.gen(function*() {
- *   const [leftover, port] = yield* optionalPort.parse({
+ *   const [, port] = yield* optionalPort.parse({
  *     arguments: [],
  *     flags: { "port": ["4000"] }
  *   })
- *   if (Option.isSome(port)) {
- *     console.log("Port specified:", port.value)
- *   } else {
- *     console.log("No port specified, using default")
- *   }
+ *   return port
  * })
+ *
+ * await Effect.runPromise(program.pipe(Effect.provide(CliTestLayer))) // => Option.some(4000)
  * ```
  *
  * @category optionality
@@ -720,7 +778,7 @@ export const optional = <A>(param: Flag<A>): Flag<Option.Option<A>> => Param.opt
  *
  * **Example** (Providing default values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const portFlag = Flag.integer("port").pipe(
@@ -732,6 +790,7 @@ export const optional = <A>(param: Flag<A>): Flag<Option.Option<A>> => Param.opt
  *   Flag.withDefault("localhost")
  * )
  * // If --host is not provided, defaults to "localhost"
+ * const kinds = [portFlag.kind, hostFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category optionality
@@ -743,7 +802,7 @@ export const withDefault: {
    *
    * **Example** (Providing default values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * const portFlag = Flag.integer("port").pipe(
@@ -755,6 +814,7 @@ export const withDefault: {
    *   Flag.withDefault("localhost")
    * )
    * // If --host is not provided, defaults to "localhost"
+   * const kinds = [portFlag.kind, hostFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category optionality
@@ -766,7 +826,7 @@ export const withDefault: {
    *
    * **Example** (Providing default values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * const portFlag = Flag.integer("port").pipe(
@@ -778,6 +838,7 @@ export const withDefault: {
    *   Flag.withDefault("localhost")
    * )
    * // If --host is not provided, defaults to "localhost"
+   * const kinds = [portFlag.kind, hostFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category optionality
@@ -794,13 +855,14 @@ export const withDefault: {
  *
  * **Example** (Falling back to config)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config } from "effect"
  * import { Flag } from "effect/unstable/cli"
  *
  * const verbose = Flag.boolean("verbose").pipe(
  *   Flag.withFallbackConfig(Config.boolean("VERBOSE"))
  * )
+ * verbose.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -812,13 +874,14 @@ export const withFallbackConfig: {
    *
    * **Example** (Falling back to config)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Config } from "effect"
    * import { Flag } from "effect/unstable/cli"
    *
    * const verbose = Flag.boolean("verbose").pipe(
    *   Flag.withFallbackConfig(Config.boolean("VERBOSE"))
    * )
+   * verbose.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -830,13 +893,14 @@ export const withFallbackConfig: {
    *
    * **Example** (Falling back to config)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Config } from "effect"
    * import { Flag } from "effect/unstable/cli"
    *
    * const verbose = Flag.boolean("verbose").pipe(
    *   Flag.withFallbackConfig(Config.boolean("VERBOSE"))
    * )
+   * verbose.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -850,12 +914,13 @@ export const withFallbackConfig: {
  *
  * **Example** (Falling back to prompts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag, Prompt } from "effect/unstable/cli"
  *
  * const name = Flag.string("name").pipe(
  *   Flag.withFallbackPrompt(Prompt.text({ message: "Name" }))
  * )
+ * name.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -867,12 +932,13 @@ export const withFallbackPrompt: {
    *
    * **Example** (Falling back to prompts)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag, Prompt } from "effect/unstable/cli"
    *
    * const name = Flag.string("name").pipe(
    *   Flag.withFallbackPrompt(Prompt.text({ message: "Name" }))
    * )
+   * name.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -884,12 +950,13 @@ export const withFallbackPrompt: {
    *
    * **Example** (Falling back to prompts)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag, Prompt } from "effect/unstable/cli"
    *
    * const name = Flag.string("name").pipe(
    *   Flag.withFallbackPrompt(Prompt.text({ message: "Name" }))
    * )
+   * name.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -903,7 +970,7 @@ export const withFallbackPrompt: {
  *
  * **Example** (Mapping parsed values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Convert string to uppercase
@@ -915,6 +982,7 @@ export const withFallbackPrompt: {
  * const urlFlag = Flag.integer("port").pipe(
  *   Flag.map((port) => `http://localhost:${port}`)
  * )
+ * const kinds = [nameFlag.kind, urlFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category mapping
@@ -926,7 +994,7 @@ export const map: {
    *
    * **Example** (Mapping parsed values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * // Convert string to uppercase
@@ -938,6 +1006,7 @@ export const map: {
    * const urlFlag = Flag.integer("port").pipe(
    *   Flag.map((port) => `http://localhost:${port}`)
    * )
+   * const kinds = [nameFlag.kind, urlFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category mapping
@@ -949,7 +1018,7 @@ export const map: {
    *
    * **Example** (Mapping parsed values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * // Convert string to uppercase
@@ -961,6 +1030,7 @@ export const map: {
    * const urlFlag = Flag.integer("port").pipe(
    *   Flag.map((port) => `http://localhost:${port}`)
    * )
+   * const kinds = [nameFlag.kind, urlFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category mapping
@@ -974,18 +1044,39 @@ export const map: {
  *
  * **Example** (Mapping parsed values effectfully)
  *
- * ```ts
- * import { Effect, FileSystem } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { 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 upperName = Flag.string("name").pipe(
+ *   Flag.mapEffect((name) => Effect.succeed(name.toUpperCase()))
+ * )
  *
- * // Read file size from path flag
- * const fileSizeFlag = Flag.file("input").pipe(
- *   Flag.mapEffect(Effect.fnUntraced(function*(path) {
- *     const fs = yield* FileSystem.FileSystem
- *     const stats = yield* Effect.orDie(fs.stat(path))
- *     return stats.size
- *   }))
+ * const [, value] = await Effect.runPromise(
+ *   upperName.parse({
+ *     arguments: [],
+ *     flags: { name: ["alice"] }
+ *   }).pipe(Effect.provide(CliTestLayer))
  * )
+ * value // => "ALICE"
  * ```
  *
  * @category mapping
@@ -997,18 +1088,39 @@ export const mapEffect: {
    *
    * **Example** (Mapping parsed values effectfully)
    *
-   * ```ts
-   * import { Effect, FileSystem } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { 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 upperName = Flag.string("name").pipe(
+   *   Flag.mapEffect((name) => Effect.succeed(name.toUpperCase()))
+   * )
    *
-   * // Read file size from path flag
-   * const fileSizeFlag = Flag.file("input").pipe(
-   *   Flag.mapEffect(Effect.fnUntraced(function*(path) {
-   *     const fs = yield* FileSystem.FileSystem
-   *     const stats = yield* Effect.orDie(fs.stat(path))
-   *     return stats.size
-   *   }))
+   * const [, value] = await Effect.runPromise(
+   *   upperName.parse({
+   *     arguments: [],
+   *     flags: { name: ["alice"] }
+   *   }).pipe(Effect.provide(CliTestLayer))
    * )
+   * value // => "ALICE"
    * ```
    *
    * @category mapping
@@ -1020,18 +1132,39 @@ export const mapEffect: {
    *
    * **Example** (Mapping parsed values effectfully)
    *
-   * ```ts
-   * import { Effect, FileSystem } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { 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"))
+   *   )
+   * )
    *
-   * // Read file size from path flag
-   * const fileSizeFlag = Flag.file("input").pipe(
-   *   Flag.mapEffect(Effect.fnUntraced(function*(path) {
-   *     const fs = yield* FileSystem.FileSystem
-   *     const stats = yield* Effect.orDie(fs.stat(path))
-   *     return stats.size
-   *   }))
+   * const upperName = Flag.string("name").pipe(
+   *   Flag.mapEffect((name) => Effect.succeed(name.toUpperCase()))
+   * )
+   *
+   * const [, value] = await Effect.runPromise(
+   *   upperName.parse({
+   *     arguments: [],
+   *     flags: { name: ["alice"] }
+   *   }).pipe(Effect.provide(CliTestLayer))
    * )
+   * value // => "ALICE"
    * ```
    *
    * @category mapping
@@ -1051,8 +1184,27 @@ export const mapEffect: {
  *
  * **Example** (Mapping thrown errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { 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"))
+ *   )
+ * )
  *
  * // Parse JSON string with error handling
  * const jsonFlag = Flag.string("config").pipe(
@@ -1069,6 +1221,14 @@ export const mapEffect: {
  *     (error) => `Invalid URL: ${error}`
  *   )
  * )
+ *
+ * const [, value] = await Effect.runPromise(
+ *   jsonFlag.parse({
+ *     arguments: [],
+ *     flags: { config: ['{"enabled":true}'] }
+ *   }).pipe(Effect.provide(CliTestLayer))
+ * )
+ * value // => { enabled: true }
  * ```
  *
  * @category mapping
@@ -1080,8 +1240,27 @@ export const mapTryCatch: {
    *
    * **Example** (Mapping thrown errors)
    *
-   * ```ts
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { 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"))
+   *   )
+   * )
    *
    * // Parse JSON string with error handling
    * const jsonFlag = Flag.string("config").pipe(
@@ -1098,6 +1277,14 @@ export const mapTryCatch: {
    *     (error) => `Invalid URL: ${error}`
    *   )
    * )
+   *
+   * const [, value] = await Effect.runPromise(
+   *   jsonFlag.parse({
+   *     arguments: [],
+   *     flags: { config: ['{"enabled":true}'] }
+   *   }).pipe(Effect.provide(CliTestLayer))
+   * )
+   * value // => { enabled: true }
    * ```
    *
    * @category mapping
@@ -1109,8 +1296,27 @@ export const mapTryCatch: {
    *
    * **Example** (Mapping thrown errors)
    *
-   * ```ts
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
    * import { 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"))
+   *   )
+   * )
    *
    * // Parse JSON string with error handling
    * const jsonFlag = Flag.string("config").pipe(
@@ -1127,6 +1333,14 @@ export const mapTryCatch: {
    *     (error) => `Invalid URL: ${error}`
    *   )
    * )
+   *
+   * const [, value] = await Effect.runPromise(
+   *   jsonFlag.parse({
+   *     arguments: [],
+   *     flags: { config: ['{"enabled":true}'] }
+   *   }).pipe(Effect.provide(CliTestLayer))
+   * )
+   * value // => { enabled: true }
    * ```
    *
    * @category mapping
@@ -1144,7 +1358,7 @@ export const mapTryCatch: {
  *
  * **Example** (Requiring repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const sourceFlag = Flag.atLeast(Flag.file("source"), 2)
@@ -1155,6 +1369,7 @@ export const mapTryCatch: {
  *   Flag.atLeast(1)
  * )
  * // Requires at least 1 tag
+ * const kinds = [sourceFlag.kind, tagFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category repetition
@@ -1166,7 +1381,7 @@ export const atLeast: {
    *
    * **Example** (Requiring repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * const sourceFlag = Flag.atLeast(Flag.file("source"), 2)
@@ -1177,6 +1392,7 @@ export const atLeast: {
    *   Flag.atLeast(1)
    * )
    * // Requires at least 1 tag
+   * const kinds = [sourceFlag.kind, tagFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category repetition
@@ -1188,7 +1404,7 @@ export const atLeast: {
    *
    * **Example** (Requiring repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * const sourceFlag = Flag.atLeast(Flag.file("source"), 2)
@@ -1199,6 +1415,7 @@ export const atLeast: {
    *   Flag.atLeast(1)
    * )
    * // Requires at least 1 tag
+   * const kinds = [sourceFlag.kind, tagFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category repetition
@@ -1212,7 +1429,7 @@ export const atLeast: {
  *
  * **Example** (Limiting repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const warningFlag = Flag.atMost(Flag.string("warning"), 3)
@@ -1223,6 +1440,7 @@ export const atLeast: {
  *   Flag.atMost(1)
  * )
  * // Allows at most 1 debug flag
+ * const kinds = [warningFlag.kind, debugFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category repetition
@@ -1234,7 +1452,7 @@ export const atMost: {
    *
    * **Example** (Limiting repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * const warningFlag = Flag.atMost(Flag.string("warning"), 3)
@@ -1245,6 +1463,7 @@ export const atMost: {
    *   Flag.atMost(1)
    * )
    * // Allows at most 1 debug flag
+   * const kinds = [warningFlag.kind, debugFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category repetition
@@ -1256,7 +1475,7 @@ export const atMost: {
    *
    * **Example** (Limiting repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * const warningFlag = Flag.atMost(Flag.string("warning"), 3)
@@ -1267,6 +1486,7 @@ export const atMost: {
    *   Flag.atMost(1)
    * )
    * // Allows at most 1 debug flag
+   * const kinds = [warningFlag.kind, debugFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category repetition
@@ -1280,7 +1500,7 @@ export const atMost: {
  *
  * **Example** (Bounding repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const hostFlag = Flag.between(Flag.string("host"), 1, 3)
@@ -1291,6 +1511,7 @@ export const atMost: {
  *   Flag.between(0, 5)
  * )
  * // Allows 0-5 exclude patterns
+ * const kinds = [hostFlag.kind, excludeFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category repetition
@@ -1302,7 +1523,7 @@ export const between: {
    *
    * **Example** (Bounding repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * const hostFlag = Flag.between(Flag.string("host"), 1, 3)
@@ -1313,6 +1534,7 @@ export const between: {
    *   Flag.between(0, 5)
    * )
    * // Allows 0-5 exclude patterns
+   * const kinds = [hostFlag.kind, excludeFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category repetition
@@ -1324,7 +1546,7 @@ export const between: {
    *
    * **Example** (Bounding repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * const hostFlag = Flag.between(Flag.string("host"), 1, 3)
@@ -1335,6 +1557,7 @@ export const between: {
    *   Flag.between(0, 5)
    * )
    * // Allows 0-5 exclude patterns
+   * const kinds = [hostFlag.kind, excludeFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category repetition
@@ -1348,7 +1571,7 @@ export const between: {
  *
  * **Example** (Filtering and transforming values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Option } from "effect"
  * import { Flag } from "effect/unstable/cli"
  *
@@ -1367,6 +1590,7 @@ export const between: {
  *     (email) => `Invalid email address: ${email}`
  *   )
  * )
+ * const kinds = [positiveInt.kind, emailFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category filtering
@@ -1378,7 +1602,7 @@ export const filterMap: {
    *
    * **Example** (Filtering and transforming values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Option } from "effect"
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1397,6 +1621,7 @@ export const filterMap: {
    *     (email) => `Invalid email address: ${email}`
    *   )
    * )
+   * const kinds = [positiveInt.kind, emailFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category filtering
@@ -1408,7 +1633,7 @@ export const filterMap: {
    *
    * **Example** (Filtering and transforming values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Option } from "effect"
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1427,6 +1652,7 @@ export const filterMap: {
    *     (email) => `Invalid email address: ${email}`
    *   )
    * )
+   * const kinds = [positiveInt.kind, emailFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category filtering
@@ -1444,7 +1670,7 @@ export const filterMap: {
  *
  * **Example** (Filtering parsed values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Ensure port is in valid range
@@ -1462,6 +1688,7 @@ export const filterMap: {
  *     () => "Name cannot be empty"
  *   )
  * )
+ * const kinds = [portFlag.kind, nameFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category filtering
@@ -1473,7 +1700,7 @@ export const filter: {
    *
    * **Example** (Filtering parsed values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * // Ensure port is in valid range
@@ -1491,6 +1718,7 @@ export const filter: {
    *     () => "Name cannot be empty"
    *   )
    * )
+   * const kinds = [portFlag.kind, nameFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category filtering
@@ -1502,7 +1730,7 @@ export const filter: {
    *
    * **Example** (Filtering parsed values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * // Ensure port is in valid range
@@ -1520,6 +1748,7 @@ export const filter: {
    *     () => "Name cannot be empty"
    *   )
    * )
+   * const kinds = [portFlag.kind, nameFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category filtering
@@ -1537,7 +1766,7 @@ export const filter: {
  *
  * **Example** (Falling back to another flag)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Try parsing as integer, fallback to string
@@ -1551,6 +1780,7 @@ export const filter: {
  *   Flag.file("config"),
  *   () => Flag.string("config-url")
  * )
+ * const kinds = [valueFlag.kind, configFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category alternatives
@@ -1562,7 +1792,7 @@ export const orElse: {
    *
    * **Example** (Falling back to another flag)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * // Try parsing as integer, fallback to string
@@ -1576,6 +1806,7 @@ export const orElse: {
    *   Flag.file("config"),
    *   () => Flag.string("config-url")
    * )
+   * const kinds = [valueFlag.kind, configFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category alternatives
@@ -1587,7 +1818,7 @@ export const orElse: {
    *
    * **Example** (Falling back to another flag)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Flag } from "effect/unstable/cli"
    *
    * // Try parsing as integer, fallback to string
@@ -1601,6 +1832,7 @@ export const orElse: {
    *   Flag.file("config"),
    *   () => Flag.string("config-url")
    * )
+   * const kinds = [valueFlag.kind, configFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category alternatives
@@ -1614,27 +1846,42 @@ export const orElse: {
  *
  * **Example** (Returning fallback results)
  *
- * ```ts
- * import { Effect, Result } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Result, Stdio, Terminal } from "effect"
  * import { 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"))
+ *   )
+ * )
  *
- * // Try file path, fallback to URL
  * const sourceFlag = Flag.orElseResult(
- *   Flag.file("source"),
+ *   Flag.string("source"),
  *   () => Flag.string("source-url")
  * )
  *
  * const program = Effect.gen(function*() {
- *   const [leftover, source] = yield* sourceFlag.parse({
+ *   const [, source] = yield* sourceFlag.parse({
  *     arguments: [],
- *     flags: { "source-url": ["https://google.com"] }
+ *     flags: { "source-url": ["https://example.com"] }
  *   })
- *   if (Result.isSuccess(source)) {
- *     console.log("Using file:", source.success)
- *   } else {
- *     console.log("Using URL:", source.failure)
- *   }
+ *   return source
  * })
+ *
+ * await Effect.runPromise(program.pipe(Effect.provide(CliTestLayer))) // => Result.fail("https://example.com")
  * ```
  *
  * @category alternatives
@@ -1646,27 +1893,42 @@ export const orElseResult: {
    *
    * **Example** (Returning fallback results)
    *
-   * ```ts
-   * import { Effect, Result } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Result, Stdio, Terminal } from "effect"
    * import { 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"))
+   *   )
+   * )
    *
-   * // Try file path, fallback to URL
    * const sourceFlag = Flag.orElseResult(
-   *   Flag.file("source"),
+   *   Flag.string("source"),
    *   () => Flag.string("source-url")
    * )
    *
    * const program = Effect.gen(function*() {
-   *   const [leftover, source] = yield* sourceFlag.parse({
+   *   const [, source] = yield* sourceFlag.parse({
    *     arguments: [],
-   *     flags: { "source-url": ["https://google.com"] }
+   *     flags: { "source-url": ["https://example.com"] }
    *   })
-   *   if (Result.isSuccess(source)) {
-   *     console.log("Using file:", source.success)
-   *   } else {
-   *     console.log("Using URL:", source.failure)
-   *   }
+   *   return source
    * })
+   *
+   * await Effect.runPromise(program.pipe(Effect.provide(CliTestLayer))) // => Result.fail("https://example.com")
    * ```
    *
    * @category alternatives
@@ -1678,27 +1940,42 @@ export const orElseResult: {
    *
    * **Example** (Returning fallback results)
    *
-   * ```ts
-   * import { Effect, Result } from "effect"
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Result, Stdio, Terminal } from "effect"
    * import { 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"))
+   *   )
+   * )
    *
-   * // Try file path, fallback to URL
    * const sourceFlag = Flag.orElseResult(
-   *   Flag.file("source"),
+   *   Flag.string("source"),
    *   () => Flag.string("source-url")
    * )
    *
    * const program = Effect.gen(function*() {
-   *   const [leftover, source] = yield* sourceFlag.parse({
+   *   const [, source] = yield* sourceFlag.parse({
    *     arguments: [],
-   *     flags: { "source-url": ["https://google.com"] }
+   *     flags: { "source-url": ["https://example.com"] }
    *   })
-   *   if (Result.isSuccess(source)) {
-   *     console.log("Using file:", source.success)
-   *   } else {
-   *     console.log("Using URL:", source.failure)
-   *   }
+   *   return source
    * })
+   *
+   * await Effect.runPromise(program.pipe(Effect.provide(CliTestLayer))) // => Result.fail("https://example.com")
    * ```
    *
    * @category alternatives
@@ -1712,7 +1989,7 @@ export const orElseResult: {
  *
  * **Example** (Validating with schemas)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Flag } from "effect/unstable/cli"
  *
@@ -1739,6 +2016,7 @@ export const orElseResult: {
  * const configFlag = Flag.string("config").pipe(
  *   Flag.withSchema(ConfigSchema)
  * )
+ * const kinds = [emailFlag.kind, configFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category schemas
@@ -1750,7 +2028,7 @@ export const withSchema: {
    *
    * **Example** (Validating with schemas)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Schema } from "effect"
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1777,6 +2055,7 @@ export const withSchema: {
    * const configFlag = Flag.string("config").pipe(
    *   Flag.withSchema(ConfigSchema)
    * )
+   * const kinds = [emailFlag.kind, configFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category schemas
@@ -1788,7 +2067,7 @@ export const withSchema: {
    *
    * **Example** (Validating with schemas)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Schema } from "effect"
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1815,6 +2094,7 @@ export const withSchema: {
    * const configFlag = Flag.string("config").pipe(
    *   Flag.withSchema(ConfigSchema)
    * )
+   * const kinds = [emailFlag.kind, configFlag.kind] // => ["flag", "flag"]
    * ```
    *
    * @category schemas