effect 4.0.0-beta.101 → 4.0.0-beta.103

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

@@ -34,11 +34,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
@@ -50,11 +51,12 @@ export declare const string: (name: string) => Flag<string>;
  *
  * **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
@@ -66,11 +68,12 @@ export declare const boolean: (name: string) => Flag<boolean>;
  *
  * **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
@@ -82,11 +85,12 @@ export declare const integer: (name: string) => Flag<number>;
  *
  * **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
@@ -98,11 +102,12 @@ export declare const float: (name: string) => Flag<number>;
  *
  * **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
@@ -115,7 +120,7 @@ export declare const date: (name: string) => Flag<Date>;
  *
  * **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
@@ -127,6 +132,7 @@ export declare const date: (name: string) => Flag<Date>;
  *   ["info", "Info" as const],
  *   ["error", "Error" as const]
  * ])
+ * const kinds = [color.kind, logLevel.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -157,7 +163,7 @@ export declare const choice: <const Choices extends ReadonlyArray<string>>(name:
  *
  * **Example** (Creating path flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Basic path flag
@@ -174,6 +180,7 @@ export declare const choice: <const Choices extends ReadonlyArray<string>>(name:
  *   pathType: "directory",
  *   typeName: "OUTPUT_DIRECTORY"
  * })
+ * const kinds = [pathFlag.kind, fileFlag.kind, dirFlag.kind] // => ["flag", "flag", "flag"]
  * ```
  *
  * @category constructors
@@ -189,7 +196,7 @@ export declare const path: (name: string, options?: {
  *
  * **Example** (Creating file flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Basic file flag
@@ -199,6 +206,7 @@ export declare 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
@@ -212,7 +220,7 @@ export declare const file: (name: string, options?: {
  *
  * **Example** (Creating directory flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Basic directory flag
@@ -222,6 +230,7 @@ export declare 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
@@ -241,20 +250,39 @@ export declare 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
@@ -266,11 +294,12 @@ export declare const redacted: (name: string) => Flag<Redacted.Redacted<string>>
  *
  * **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
@@ -287,7 +316,7 @@ export declare const fileText: (name: string) => Flag<string>;
  *
  * **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
@@ -296,6 +325,7 @@ export declare const fileText: (name: string) => Flag<string>;
  *
  * // Will use the JSON parser
  * const jsonConfig = Flag.fileParse("json-config", { format: "json" })
+ * const kinds = [config.kind, jsonConfig.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -308,7 +338,7 @@ export declare const fileParse: (name: string, options?: Primitive.FileParseOpti
  *
  * **Example** (Validating file contents)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Flag } from "effect/unstable/cli"
  *
@@ -318,6 +348,7 @@ export declare const fileParse: (name: string, options?: Primitive.FileParseOpti
  * })
  *
  * const config = Flag.fileSchema("config", ConfigSchema, { format: "json" })
+ * config.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -339,11 +370,12 @@ export declare const fileSchema: <A>(name: string, schema: Schema.ConstraintDeco
  *
  * **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
@@ -356,14 +388,14 @@ export declare const keyValuePair: (name: string) => Flag<Record<string, string>
  *
  * **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
@@ -375,7 +407,7 @@ export declare const none: Flag<never>;
  *
  * **Example** (Adding flag aliases)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Flag can be used as both --verbose and -v
@@ -388,6 +420,7 @@ export declare const none: Flag<never>;
  *   Flag.withAlias("h"),
  *   Flag.withAlias("?")
  * )
+ * const kinds = [verboseFlag.kind, helpFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category aliasing
@@ -399,7 +432,7 @@ export declare 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
@@ -412,6 +445,7 @@ export declare const withAlias: {
      *   Flag.withAlias("h"),
      *   Flag.withAlias("?")
      * )
+     * const kinds = [verboseFlag.kind, helpFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category aliasing
@@ -423,7 +457,7 @@ export declare 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
@@ -436,6 +470,7 @@ export declare const withAlias: {
      *   Flag.withAlias("h"),
      *   Flag.withAlias("?")
      * )
+     * const kinds = [verboseFlag.kind, helpFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category aliasing
@@ -448,7 +483,7 @@ export declare const withAlias: {
  *
  * **Example** (Adding help descriptions)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const portFlag = Flag.integer("port").pipe(
@@ -458,9 +493,10 @@ export declare 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 declare const withDescription: {
@@ -469,7 +505,7 @@ export declare const withDescription: {
      *
      * **Example** (Adding help descriptions)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Flag } from "effect/unstable/cli"
      *
      * const portFlag = Flag.integer("port").pipe(
@@ -479,9 +515,10 @@ export declare 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>;
@@ -490,7 +527,7 @@ export declare const withDescription: {
      *
      * **Example** (Adding help descriptions)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Flag } from "effect/unstable/cli"
      *
      * const portFlag = Flag.integer("port").pipe(
@@ -500,9 +537,10 @@ export declare 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>;
@@ -517,7 +555,7 @@ export declare const withDescription: {
  *
  * **Example** (Setting metavars)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const databaseFlag = Flag.string("database-url").pipe(
@@ -530,6 +568,7 @@ export declare const withDescription: {
  *   Flag.withMetavar("SECONDS")
  * )
  * // In help: --timeout SECONDS
+ * const kinds = [databaseFlag.kind, timeoutFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category metadata
@@ -546,7 +585,7 @@ export declare const withMetavar: {
      *
      * **Example** (Setting metavars)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Flag } from "effect/unstable/cli"
      *
      * const databaseFlag = Flag.string("database-url").pipe(
@@ -559,6 +598,7 @@ export declare const withMetavar: {
      *   Flag.withMetavar("SECONDS")
      * )
      * // In help: --timeout SECONDS
+     * const kinds = [databaseFlag.kind, timeoutFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category metadata
@@ -575,7 +615,7 @@ export declare const withMetavar: {
      *
      * **Example** (Setting metavars)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Flag } from "effect/unstable/cli"
      *
      * const databaseFlag = Flag.string("database-url").pipe(
@@ -588,6 +628,7 @@ export declare const withMetavar: {
      *   Flag.withMetavar("SECONDS")
      * )
      * // In help: --timeout SECONDS
+     * const kinds = [databaseFlag.kind, timeoutFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category metadata
@@ -607,13 +648,14 @@ export declare 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
@@ -625,23 +667,39 @@ export declare const withHidden: <A>(self: Flag<A>) => Flag<A>;
  *
  * **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
@@ -653,7 +711,7 @@ export declare const optional: <A>(param: Flag<A>) => Flag<Option.Option<A>>;
  *
  * **Example** (Providing default values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const portFlag = Flag.integer("port").pipe(
@@ -665,6 +723,7 @@ export declare const optional: <A>(param: Flag<A>) => Flag<Option.Option<A>>;
  *   Flag.withDefault("localhost")
  * )
  * // If --host is not provided, defaults to "localhost"
+ * const kinds = [portFlag.kind, hostFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category optionality
@@ -676,7 +735,7 @@ export declare const withDefault: {
      *
      * **Example** (Providing default values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Flag } from "effect/unstable/cli"
      *
      * const portFlag = Flag.integer("port").pipe(
@@ -688,6 +747,7 @@ export declare const withDefault: {
      *   Flag.withDefault("localhost")
      * )
      * // If --host is not provided, defaults to "localhost"
+     * const kinds = [portFlag.kind, hostFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category optionality
@@ -699,7 +759,7 @@ export declare const withDefault: {
      *
      * **Example** (Providing default values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Flag } from "effect/unstable/cli"
      *
      * const portFlag = Flag.integer("port").pipe(
@@ -711,6 +771,7 @@ export declare const withDefault: {
      *   Flag.withDefault("localhost")
      * )
      * // If --host is not provided, defaults to "localhost"
+     * const kinds = [portFlag.kind, hostFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category optionality
@@ -723,13 +784,14 @@ export declare 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
@@ -741,13 +803,14 @@ export declare 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
@@ -759,13 +822,14 @@ export declare 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
@@ -778,12 +842,13 @@ export declare 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
@@ -795,12 +860,13 @@ export declare 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
@@ -812,12 +878,13 @@ export declare 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
@@ -830,7 +897,7 @@ export declare const withFallbackPrompt: {
  *
  * **Example** (Mapping parsed values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Convert string to uppercase
@@ -842,6 +909,7 @@ export declare const withFallbackPrompt: {
  * const urlFlag = Flag.integer("port").pipe(
  *   Flag.map((port) => `http://localhost:${port}`)
  * )
+ * const kinds = [nameFlag.kind, urlFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category mapping
@@ -853,7 +921,7 @@ export declare const map: {
      *
      * **Example** (Mapping parsed values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Flag } from "effect/unstable/cli"
      *
      * // Convert string to uppercase
@@ -865,6 +933,7 @@ export declare const map: {
      * const urlFlag = Flag.integer("port").pipe(
      *   Flag.map((port) => `http://localhost:${port}`)
      * )
+     * const kinds = [nameFlag.kind, urlFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category mapping
@@ -876,7 +945,7 @@ export declare const map: {
      *
      * **Example** (Mapping parsed values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Flag } from "effect/unstable/cli"
      *
      * // Convert string to uppercase
@@ -888,6 +957,7 @@ export declare const map: {
      * const urlFlag = Flag.integer("port").pipe(
      *   Flag.map((port) => `http://localhost:${port}`)
      * )
+     * const kinds = [nameFlag.kind, urlFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category mapping
@@ -900,18 +970,39 @@ export declare 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
@@ -923,18 +1014,39 @@ export declare 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
@@ -946,18 +1058,39 @@ export declare 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
@@ -970,8 +1103,27 @@ export declare 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(
@@ -988,6 +1140,14 @@ export declare 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
@@ -999,8 +1159,27 @@ export declare 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(
@@ -1017,6 +1196,14 @@ export declare 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
@@ -1028,8 +1215,27 @@ export declare 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(
@@ -1046,6 +1252,14 @@ export declare 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
@@ -1058,7 +1272,7 @@ export declare 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)
@@ -1069,6 +1283,7 @@ export declare const mapTryCatch: {
  *   Flag.atLeast(1)
  * )
  * // Requires at least 1 tag
+ * const kinds = [sourceFlag.kind, tagFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category repetition
@@ -1080,7 +1295,7 @@ export declare 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)
@@ -1091,6 +1306,7 @@ export declare const atLeast: {
      *   Flag.atLeast(1)
      * )
      * // Requires at least 1 tag
+     * const kinds = [sourceFlag.kind, tagFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category repetition
@@ -1102,7 +1318,7 @@ export declare 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)
@@ -1113,6 +1329,7 @@ export declare const atLeast: {
      *   Flag.atLeast(1)
      * )
      * // Requires at least 1 tag
+     * const kinds = [sourceFlag.kind, tagFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category repetition
@@ -1125,7 +1342,7 @@ export declare 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)
@@ -1136,6 +1353,7 @@ export declare const atLeast: {
  *   Flag.atMost(1)
  * )
  * // Allows at most 1 debug flag
+ * const kinds = [warningFlag.kind, debugFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category repetition
@@ -1147,7 +1365,7 @@ export declare 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)
@@ -1158,6 +1376,7 @@ export declare const atMost: {
      *   Flag.atMost(1)
      * )
      * // Allows at most 1 debug flag
+     * const kinds = [warningFlag.kind, debugFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category repetition
@@ -1169,7 +1388,7 @@ export declare 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)
@@ -1180,6 +1399,7 @@ export declare const atMost: {
      *   Flag.atMost(1)
      * )
      * // Allows at most 1 debug flag
+     * const kinds = [warningFlag.kind, debugFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category repetition
@@ -1192,7 +1412,7 @@ export declare 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)
@@ -1203,6 +1423,7 @@ export declare const atMost: {
  *   Flag.between(0, 5)
  * )
  * // Allows 0-5 exclude patterns
+ * const kinds = [hostFlag.kind, excludeFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category repetition
@@ -1214,7 +1435,7 @@ export declare 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)
@@ -1225,6 +1446,7 @@ export declare const between: {
      *   Flag.between(0, 5)
      * )
      * // Allows 0-5 exclude patterns
+     * const kinds = [hostFlag.kind, excludeFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category repetition
@@ -1236,7 +1458,7 @@ export declare 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)
@@ -1247,6 +1469,7 @@ export declare const between: {
      *   Flag.between(0, 5)
      * )
      * // Allows 0-5 exclude patterns
+     * const kinds = [hostFlag.kind, excludeFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category repetition
@@ -1259,7 +1482,7 @@ export declare const between: {
  *
  * **Example** (Filtering and transforming values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Option } from "effect"
  * import { Flag } from "effect/unstable/cli"
  *
@@ -1278,6 +1501,7 @@ export declare const between: {
  *     (email) => `Invalid email address: ${email}`
  *   )
  * )
+ * const kinds = [positiveInt.kind, emailFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category filtering
@@ -1289,7 +1513,7 @@ export declare const filterMap: {
      *
      * **Example** (Filtering and transforming values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Option } from "effect"
      * import { Flag } from "effect/unstable/cli"
      *
@@ -1308,6 +1532,7 @@ export declare const filterMap: {
      *     (email) => `Invalid email address: ${email}`
      *   )
      * )
+     * const kinds = [positiveInt.kind, emailFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category filtering
@@ -1319,7 +1544,7 @@ export declare const filterMap: {
      *
      * **Example** (Filtering and transforming values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Option } from "effect"
      * import { Flag } from "effect/unstable/cli"
      *
@@ -1338,6 +1563,7 @@ export declare const filterMap: {
      *     (email) => `Invalid email address: ${email}`
      *   )
      * )
+     * const kinds = [positiveInt.kind, emailFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category filtering
@@ -1350,7 +1576,7 @@ export declare const filterMap: {
  *
  * **Example** (Filtering parsed values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Ensure port is in valid range
@@ -1368,6 +1594,7 @@ export declare const filterMap: {
  *     () => "Name cannot be empty"
  *   )
  * )
+ * const kinds = [portFlag.kind, nameFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category filtering
@@ -1379,7 +1606,7 @@ export declare const filter: {
      *
      * **Example** (Filtering parsed values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Flag } from "effect/unstable/cli"
      *
      * // Ensure port is in valid range
@@ -1397,6 +1624,7 @@ export declare const filter: {
      *     () => "Name cannot be empty"
      *   )
      * )
+     * const kinds = [portFlag.kind, nameFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category filtering
@@ -1408,7 +1636,7 @@ export declare const filter: {
      *
      * **Example** (Filtering parsed values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Flag } from "effect/unstable/cli"
      *
      * // Ensure port is in valid range
@@ -1426,6 +1654,7 @@ export declare const filter: {
      *     () => "Name cannot be empty"
      *   )
      * )
+     * const kinds = [portFlag.kind, nameFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category filtering
@@ -1438,7 +1667,7 @@ export declare 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
@@ -1452,6 +1681,7 @@ export declare const filter: {
  *   Flag.file("config"),
  *   () => Flag.string("config-url")
  * )
+ * const kinds = [valueFlag.kind, configFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category alternatives
@@ -1463,7 +1693,7 @@ export declare 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
@@ -1477,6 +1707,7 @@ export declare const orElse: {
      *   Flag.file("config"),
      *   () => Flag.string("config-url")
      * )
+     * const kinds = [valueFlag.kind, configFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category alternatives
@@ -1488,7 +1719,7 @@ export declare 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
@@ -1502,6 +1733,7 @@ export declare const orElse: {
      *   Flag.file("config"),
      *   () => Flag.string("config-url")
      * )
+     * const kinds = [valueFlag.kind, configFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category alternatives
@@ -1514,27 +1746,42 @@ export declare 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
@@ -1546,27 +1793,42 @@ export declare 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
@@ -1578,27 +1840,42 @@ export declare 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
@@ -1611,7 +1888,7 @@ export declare const orElseResult: {
  *
  * **Example** (Validating with schemas)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Flag } from "effect/unstable/cli"
  *
@@ -1638,6 +1915,7 @@ export declare const orElseResult: {
  * const configFlag = Flag.string("config").pipe(
  *   Flag.withSchema(ConfigSchema)
  * )
+ * const kinds = [emailFlag.kind, configFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category schemas
@@ -1649,7 +1927,7 @@ export declare const withSchema: {
      *
      * **Example** (Validating with schemas)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Schema } from "effect"
      * import { Flag } from "effect/unstable/cli"
      *
@@ -1676,6 +1954,7 @@ export declare const withSchema: {
      * const configFlag = Flag.string("config").pipe(
      *   Flag.withSchema(ConfigSchema)
      * )
+     * const kinds = [emailFlag.kind, configFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category schemas
@@ -1687,7 +1966,7 @@ export declare const withSchema: {
      *
      * **Example** (Validating with schemas)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Schema } from "effect"
      * import { Flag } from "effect/unstable/cli"
      *
@@ -1714,6 +1993,7 @@ export declare const withSchema: {
      * const configFlag = Flag.string("config").pipe(
      *   Flag.withSchema(ConfigSchema)
      * )
+     * const kinds = [emailFlag.kind, configFlag.kind] // => ["flag", "flag"]
      * ```
      *
      * @category schemas