effect 4.0.0-beta.66 → 4.0.0-beta.68

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

@@ -1,4 +1,23 @@
 /**
+ * The `Flag` module provides typed command-line options for Effect CLI
+ * applications. A `Flag<A>` describes how to read one named option from the
+ * parsed command line, validate it, and produce a value of type `A`.
+ *
+ * Use flags for inputs that are naturally named options, such as ports,
+ * verbosity switches, configuration files, output directories, enum-like
+ * choices, secrets, and repeated values. Constructors such as {@link string},
+ * {@link boolean}, {@link integer}, {@link file}, and {@link fileSchema}
+ * define the accepted input shape, while combinators add aliases, defaults,
+ * optionality, fallback config or prompts, validation, and typed mapping.
+ *
+ * Flag names are rendered as long options, for example `Flag.integer("port")`
+ * parses `--port 8080`. Boolean flags also support the disabled form shown by
+ * this module's boolean documentation, and repeated flags are modeled with the
+ * repetition combinators instead of by manually inspecting raw arguments. Help
+ * text is generated from flag metadata, so prefer {@link withDescription} and
+ * {@link withMetavar} when a flag's value, format, or file-system expectation
+ * would otherwise be ambiguous.
+ *
  * @since 4.0.0
  */
 import type * as Config from "../../Config.ts";
@@ -14,15 +33,16 @@ import type * as Primitive from "./Primitive.ts";
 /**
  * Represents a command-line flag.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Flag<A> extends Param.Param<typeof Param.flagKind, A> {
 }
 /**
  * Creates a string flag that accepts text input.
  *
- * @example
+ * **Example** (Creating string flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -30,14 +50,15 @@ export interface Flag<A> extends Param.Param<typeof Param.flagKind, A> {
  * // Usage: --name "John Doe"
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const string: (name: string) => Flag<string>;
 /**
  * Creates a boolean flag that can be enabled or disabled.
  *
- * @example
+ * **Example** (Creating boolean flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -45,14 +66,15 @@ export declare const string: (name: string) => Flag<string>;
  * // Usage: --verbose (true) or --no-verbose (false)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const boolean: (name: string) => Flag<boolean>;
 /**
  * Creates an integer flag that accepts whole number input.
  *
- * @example
+ * **Example** (Creating integer flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -60,14 +82,15 @@ export declare const boolean: (name: string) => Flag<boolean>;
  * // Usage: --port 8080
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const integer: (name: string) => Flag<number>;
 /**
  * Creates a float flag that accepts decimal number input.
  *
- * @example
+ * **Example** (Creating float flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -75,14 +98,15 @@ export declare const integer: (name: string) => Flag<number>;
  * // Usage: --rate 3.14
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const float: (name: string) => Flag<number>;
 /**
  * Creates a date flag that accepts date input in ISO format.
  *
- * @example
+ * **Example** (Creating date flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -90,15 +114,16 @@ export declare const float: (name: string) => Flag<number>;
  * // Usage: --start-date 2023-12-25
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const date: (name: string) => Flag<Date>;
 /**
  * Constructs option parameters that represent a choice between several inputs.
  * Each tuple maps a string flag value to an associated typed value.
  *
- * @example
+ * **Example** (Creating flag choices with values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -113,21 +138,22 @@ export declare const date: (name: string) => Flag<Date>;
  * ])
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const choiceWithValue: <const Choice extends ReadonlyArray<readonly [string, any]>>(name: string, choices: Choice) => Flag<Choice[number][1]>;
 /**
  * Simpler variant of `choiceWithValue` which maps each string to itself.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const choice: <const Choices extends ReadonlyArray<string>>(name: string, choices: Choices) => Flag<Choices[number]>;
 /**
  * Creates a path flag that accepts file system path input with validation options.
  *
- * @example
+ * **Example** (Creating path flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -147,8 +173,8 @@ export declare const choice: <const Choices extends ReadonlyArray<string>>(name:
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const path: (name: string, options?: {
     readonly pathType?: "file" | "directory" | "either" | undefined;
@@ -158,7 +184,8 @@ export declare const path: (name: string, options?: {
 /**
  * Creates a file path flag that accepts file paths with optional existence validation.
  *
- * @example
+ * **Example** (Creating file flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -171,8 +198,8 @@ export declare const path: (name: string, options?: {
  * // Usage: --config ./config.yaml (file must exist)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const file: (name: string, options?: {
     readonly mustExist?: boolean | undefined;
@@ -180,7 +207,8 @@ export declare const file: (name: string, options?: {
 /**
  * Creates a directory path flag that accepts directory paths with optional existence validation.
  *
- * @example
+ * **Example** (Creating directory flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -193,16 +221,21 @@ export declare const file: (name: string, options?: {
  * // Usage: --source ./src (directory must exist)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const directory: (name: string, options?: {
     readonly mustExist?: boolean | undefined;
 }) => Flag<string>;
 /**
- * Creates a redacted flag that securely handles sensitive string input.
+ * Creates a string flag whose parsed value is wrapped in `Redacted.Redacted`
+ * so stringification and logging redact the value.
+ *
+ * Values supplied on the command line may still be visible to the operating
+ * system or shell history.
+ *
+ * **Example** (Creating redacted flags)
  *
- * @example
  * ```ts
  * import { Effect, Redacted } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -219,14 +252,15 @@ export declare const directory: (name: string, options?: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const redacted: (name: string) => Flag<Redacted.Redacted<string>>;
 /**
  * Creates a flag that reads and returns file content as a string.
  *
- * @example
+ * **Example** (Reading file text)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -234,8 +268,8 @@ export declare const redacted: (name: string) => Flag<Redacted.Redacted<string>>
  * // --config-file ./app.json will read the file content
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fileText: (name: string) => Flag<string>;
 /**
@@ -244,7 +278,8 @@ export declare const fileText: (name: string) => Flag<string>;
  * The parser that is utilized will depend on the specified `format`, or the
  * extension of the file passed on the command-line if no `format` is specified.
  *
- * @example
+ * **Example** (Parsing file contents)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -256,15 +291,16 @@ export declare const fileText: (name: string) => Flag<string>;
  * const jsonConfig = Flag.fileParse("json-config", { format: "json" })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fileParse: (name: string, options?: Primitive.FileParseOptions | undefined) => Flag<unknown>;
 /**
  * Creates a flag that reads and validates file content using the specified
  * schema.
  *
- * @example
+ * **Example** (Validating file contents)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -277,8 +313,8 @@ export declare const fileParse: (name: string, options?: Primitive.FileParseOpti
  * const config = Flag.fileSchema("config", ConfigSchema, { format: "json" })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fileSchema: <A>(name: string, schema: Schema.Decoder<A>, options?: Primitive.FileSchemaOptions | undefined) => Flag<A>;
 /**
@@ -288,7 +324,8 @@ export declare const fileSchema: <A>(name: string, schema: Schema.Decoder<A>, op
  * Note: Requires at least one key=value pair. Multiple pairs are merged
  * into a single record.
  *
- * @example
+ * **Example** (Parsing key-value pairs)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -296,30 +333,35 @@ export declare const fileSchema: <A>(name: string, schema: Schema.Decoder<A>, op
  * // --env FOO=bar --env BAZ=qux will parse to { FOO: "bar", BAZ: "qux" }
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const keyValuePair: (name: string) => Flag<Record<string, string>>;
 /**
  * Creates an empty sentinel flag that always fails to parse.
  * This is useful for creating placeholder flags or for combinators.
  *
- * @example
+ * **Example** (Creating sentinel flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
- * // Used as a placeholder in flag combinators
- * const conditionalFlag = true ? Flag.string("value") : Flag.none
+ * const makeValueFlag = (includeValue: boolean) =>
+ *   includeValue ? Flag.string("value") : Flag.none
+ *
+ * console.log(makeValueFlag(true) === Flag.none) // false
+ * console.log(makeValueFlag(false) === Flag.none) // true
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const none: Flag<never>;
 /**
  * Adds an alias to a flag, allowing it to be referenced by multiple names.
  *
- * @example
+ * **Example** (Adding flag aliases)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -335,14 +377,15 @@ export declare const none: Flag<never>;
  * )
  * ```
  *
- * @since 4.0.0
  * @category aliasing
+ * @since 4.0.0
  */
 export declare const withAlias: {
     /**
      * Adds an alias to a flag, allowing it to be referenced by multiple names.
      *
-     * @example
+     * **Example** (Adding flag aliases)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -358,14 +401,15 @@ export declare const withAlias: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category aliasing
+     * @since 4.0.0
      */
     <A>(alias: string): (self: Flag<A>) => Flag<A>;
     /**
      * Adds an alias to a flag, allowing it to be referenced by multiple names.
      *
-     * @example
+     * **Example** (Adding flag aliases)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -381,15 +425,16 @@ export declare const withAlias: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category aliasing
+     * @since 4.0.0
      */
     <A>(self: Flag<A>, alias: string): Flag<A>;
 };
 /**
  * Adds a description to a flag for help documentation.
  *
- * @example
+ * **Example** (Adding help descriptions)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -402,14 +447,15 @@ export declare const withAlias: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category help documentation
+ * @since 4.0.0
  */
 export declare const withDescription: {
     /**
      * Adds a description to a flag for help documentation.
      *
-     * @example
+     * **Example** (Adding help descriptions)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -422,14 +468,15 @@ export declare const withDescription: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category help documentation
+     * @since 4.0.0
      */
     <A>(description: string): (self: Flag<A>) => Flag<A>;
     /**
      * Adds a description to a flag for help documentation.
      *
-     * @example
+     * **Example** (Adding help descriptions)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -442,8 +489,8 @@ export declare const withDescription: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category help documentation
+     * @since 4.0.0
      */
     <A>(self: Flag<A>, description: string): Flag<A>;
 };
@@ -453,7 +500,8 @@ export declare const withDescription: {
  * The metavar is displayed in usage text to indicate what value the user should provide.
  * For example, `--output FILE` shows `FILE` as the metavar.
  *
- * @example
+ * **Example** (Setting metavars)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -469,8 +517,8 @@ export declare const withDescription: {
  * // In help: --timeout SECONDS
  * ```
  *
- * @since 4.0.0
  * @category metadata
+ * @since 4.0.0
  */
 export declare const withMetavar: {
     /**
@@ -479,7 +527,8 @@ export declare const withMetavar: {
      * The metavar is displayed in usage text to indicate what value the user should provide.
      * For example, `--output FILE` shows `FILE` as the metavar.
      *
-     * @example
+     * **Example** (Setting metavars)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -495,8 +544,8 @@ export declare const withMetavar: {
      * // In help: --timeout SECONDS
      * ```
      *
-     * @since 4.0.0
      * @category metadata
+     * @since 4.0.0
      */
     <A>(metavar: string): (self: Flag<A>) => Flag<A>;
     /**
@@ -505,7 +554,8 @@ export declare const withMetavar: {
      * The metavar is displayed in usage text to indicate what value the user should provide.
      * For example, `--output FILE` shows `FILE` as the metavar.
      *
-     * @example
+     * **Example** (Setting metavars)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -521,15 +571,16 @@ export declare const withMetavar: {
      * // In help: --timeout SECONDS
      * ```
      *
-     * @since 4.0.0
      * @category metadata
+     * @since 4.0.0
      */
     <A>(self: Flag<A>, metavar: string): Flag<A>;
 };
 /**
  * Makes a flag optional, returning an Option type that can be None if not provided.
  *
- * @example
+ * **Example** (Making flags optional)
+ *
  * ```ts
  * import { Effect, Option } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -549,14 +600,15 @@ export declare const withMetavar: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category optionality
+ * @since 4.0.0
  */
 export declare const optional: <A>(param: Flag<A>) => Flag<Option.Option<A>>;
 /**
  * Provides a default value for a flag when it's not specified.
  *
- * @example
+ * **Example** (Providing default values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -571,14 +623,15 @@ export declare const optional: <A>(param: Flag<A>) => Flag<Option.Option<A>>;
  * // If --host is not provided, defaults to "localhost"
  * ```
  *
- * @since 4.0.0
  * @category optionality
+ * @since 4.0.0
  */
 export declare const withDefault: {
     /**
      * Provides a default value for a flag when it's not specified.
      *
-     * @example
+     * **Example** (Providing default values)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -593,14 +646,15 @@ export declare const withDefault: {
      * // If --host is not provided, defaults to "localhost"
      * ```
      *
-     * @since 4.0.0
      * @category optionality
+     * @since 4.0.0
      */
     <const B>(defaultValue: B | Effect.Effect<B, CliError.CliError, Param.Environment>): <A>(self: Flag<A>) => Flag<A | B>;
     /**
      * Provides a default value for a flag when it's not specified.
      *
-     * @example
+     * **Example** (Providing default values)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -615,15 +669,16 @@ export declare const withDefault: {
      * // If --host is not provided, defaults to "localhost"
      * ```
      *
-     * @since 4.0.0
      * @category optionality
+     * @since 4.0.0
      */
     <A, const B>(self: Flag<A>, defaultValue: B | Effect.Effect<B, CliError.CliError, Param.Environment>): Flag<A | B>;
 };
 /**
  * Adds a fallback config that is loaded when a required flag is missing.
  *
- * @example
+ * **Example** (Falling back to config)
+ *
  * ```ts
  * import { Config } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -633,14 +688,15 @@ export declare const withDefault: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withFallbackConfig: {
     /**
      * Adds a fallback config that is loaded when a required flag is missing.
      *
-     * @example
+     * **Example** (Falling back to config)
+     *
      * ```ts
      * import { Config } from "effect"
      * import { Flag } from "effect/unstable/cli"
@@ -650,14 +706,15 @@ export declare const withFallbackConfig: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <B>(config: Config.Config<B>): <A>(self: Flag<A>) => Flag<A | B>;
     /**
      * Adds a fallback config that is loaded when a required flag is missing.
      *
-     * @example
+     * **Example** (Falling back to config)
+     *
      * ```ts
      * import { Config } from "effect"
      * import { Flag } from "effect/unstable/cli"
@@ -667,15 +724,16 @@ export declare const withFallbackConfig: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(self: Flag<A>, config: Config.Config<B>): Flag<A | B>;
 };
 /**
  * Adds a fallback prompt that is shown when a required flag is missing.
  *
- * @example
+ * **Example** (Falling back to prompts)
+ *
  * ```ts
  * import { Flag, Prompt } from "effect/unstable/cli"
  *
@@ -684,14 +742,15 @@ export declare const withFallbackConfig: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withFallbackPrompt: {
     /**
      * Adds a fallback prompt that is shown when a required flag is missing.
      *
-     * @example
+     * **Example** (Falling back to prompts)
+     *
      * ```ts
      * import { Flag, Prompt } from "effect/unstable/cli"
      *
@@ -700,14 +759,15 @@ export declare const withFallbackPrompt: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <B>(prompt: Param.FallbackPrompt<B>): <A>(self: Flag<A>) => Flag<A | B>;
     /**
      * Adds a fallback prompt that is shown when a required flag is missing.
      *
-     * @example
+     * **Example** (Falling back to prompts)
+     *
      * ```ts
      * import { Flag, Prompt } from "effect/unstable/cli"
      *
@@ -716,15 +776,16 @@ export declare const withFallbackPrompt: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(self: Flag<A>, prompt: Param.FallbackPrompt<B>): Flag<A | B>;
 };
 /**
  * Transforms the parsed value of a flag using a mapping function.
  *
- * @example
+ * **Example** (Mapping parsed values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -739,14 +800,15 @@ export declare const withFallbackPrompt: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category mapping
+ * @since 4.0.0
  */
 export declare const map: {
     /**
      * Transforms the parsed value of a flag using a mapping function.
      *
-     * @example
+     * **Example** (Mapping parsed values)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -761,14 +823,15 @@ export declare const map: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <A, B>(f: (a: A) => B): (self: Flag<A>) => Flag<B>;
     /**
      * Transforms the parsed value of a flag using a mapping function.
      *
-     * @example
+     * **Example** (Mapping parsed values)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -783,15 +846,16 @@ export declare const map: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <A, B>(self: Flag<A>, f: (a: A) => B): Flag<B>;
 };
 /**
  * Transforms the parsed value using an Effect that can perform IO operations.
  *
- * @example
+ * **Example** (Mapping parsed values effectfully)
+ *
  * ```ts
  * import { Effect, FileSystem } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -806,14 +870,15 @@ export declare const map: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category mapping
+ * @since 4.0.0
  */
 export declare const mapEffect: {
     /**
      * Transforms the parsed value using an Effect that can perform IO operations.
      *
-     * @example
+     * **Example** (Mapping parsed values effectfully)
+     *
      * ```ts
      * import { Effect, FileSystem } from "effect"
      * import { Flag } from "effect/unstable/cli"
@@ -828,14 +893,15 @@ export declare const mapEffect: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <A, B>(f: (a: A) => Effect.Effect<B, CliError.CliError, Param.Environment>): (self: Flag<A>) => Flag<B>;
     /**
      * Transforms the parsed value using an Effect that can perform IO operations.
      *
-     * @example
+     * **Example** (Mapping parsed values effectfully)
+     *
      * ```ts
      * import { Effect, FileSystem } from "effect"
      * import { Flag } from "effect/unstable/cli"
@@ -850,15 +916,16 @@ export declare const mapEffect: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <A, B>(self: Flag<A>, f: (a: A) => Effect.Effect<B, CliError.CliError, Param.Environment>): Flag<B>;
 };
 /**
  * Transforms the parsed value using a function that might throw, with error handling.
  *
- * @example
+ * **Example** (Mapping thrown errors)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -879,14 +946,15 @@ export declare const mapEffect: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category mapping
+ * @since 4.0.0
  */
 export declare const mapTryCatch: {
     /**
      * Transforms the parsed value using a function that might throw, with error handling.
      *
-     * @example
+     * **Example** (Mapping thrown errors)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -907,14 +975,15 @@ export declare const mapTryCatch: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <A, B>(f: (a: A) => B, onError: (error: unknown) => string): (self: Flag<A>) => Flag<B>;
     /**
      * Transforms the parsed value using a function that might throw, with error handling.
      *
-     * @example
+     * **Example** (Mapping thrown errors)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -935,15 +1004,16 @@ export declare const mapTryCatch: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <A, B>(self: Flag<A>, f: (a: A) => B, onError: (error: unknown) => string): Flag<B>;
 };
 /**
  * Requires a flag to be specified at least a minimum number of times.
  *
- * @example
+ * **Example** (Requiring repeated values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -957,14 +1027,15 @@ export declare const mapTryCatch: {
  * // Requires at least 1 tag
  * ```
  *
- * @since 4.0.0
  * @category repetition
+ * @since 4.0.0
  */
 export declare const atLeast: {
     /**
      * Requires a flag to be specified at least a minimum number of times.
      *
-     * @example
+     * **Example** (Requiring repeated values)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -978,14 +1049,15 @@ export declare const atLeast: {
      * // Requires at least 1 tag
      * ```
      *
-     * @since 4.0.0
      * @category repetition
+     * @since 4.0.0
      */
     <A>(min: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>;
     /**
      * Requires a flag to be specified at least a minimum number of times.
      *
-     * @example
+     * **Example** (Requiring repeated values)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -999,15 +1071,16 @@ export declare const atLeast: {
      * // Requires at least 1 tag
      * ```
      *
-     * @since 4.0.0
      * @category repetition
+     * @since 4.0.0
      */
     <A>(self: Flag<A>, min: number): Flag<ReadonlyArray<A>>;
 };
 /**
  * Limits a flag to be specified at most a maximum number of times.
  *
- * @example
+ * **Example** (Limiting repeated values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -1021,14 +1094,15 @@ export declare const atLeast: {
  * // Allows at most 1 debug flag
  * ```
  *
- * @since 4.0.0
  * @category repetition
+ * @since 4.0.0
  */
 export declare const atMost: {
     /**
      * Limits a flag to be specified at most a maximum number of times.
      *
-     * @example
+     * **Example** (Limiting repeated values)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -1042,14 +1116,15 @@ export declare const atMost: {
      * // Allows at most 1 debug flag
      * ```
      *
-     * @since 4.0.0
      * @category repetition
+     * @since 4.0.0
      */
     <A>(max: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>;
     /**
      * Limits a flag to be specified at most a maximum number of times.
      *
-     * @example
+     * **Example** (Limiting repeated values)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -1063,15 +1138,16 @@ export declare const atMost: {
      * // Allows at most 1 debug flag
      * ```
      *
-     * @since 4.0.0
      * @category repetition
+     * @since 4.0.0
      */
     <A>(self: Flag<A>, max: number): Flag<ReadonlyArray<A>>;
 };
 /**
  * Constrains a flag to be specified between a minimum and maximum number of times.
  *
- * @example
+ * **Example** (Bounding repeated values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -1085,14 +1161,15 @@ export declare const atMost: {
  * // Allows 0-5 exclude patterns
  * ```
  *
- * @since 4.0.0
  * @category repetition
+ * @since 4.0.0
  */
 export declare const between: {
     /**
      * Constrains a flag to be specified between a minimum and maximum number of times.
      *
-     * @example
+     * **Example** (Bounding repeated values)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -1106,14 +1183,15 @@ export declare const between: {
      * // Allows 0-5 exclude patterns
      * ```
      *
-     * @since 4.0.0
      * @category repetition
+     * @since 4.0.0
      */
     <A>(min: number, max: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>;
     /**
      * Constrains a flag to be specified between a minimum and maximum number of times.
      *
-     * @example
+     * **Example** (Bounding repeated values)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -1127,15 +1205,16 @@ export declare const between: {
      * // Allows 0-5 exclude patterns
      * ```
      *
-     * @since 4.0.0
      * @category repetition
+     * @since 4.0.0
      */
     <A>(self: Flag<A>, min: number, max: number): Flag<ReadonlyArray<A>>;
 };
 /**
  * Transforms and filters a flag value, failing with a custom error if the transformation returns None.
  *
- * @example
+ * **Example** (Filtering and transforming values)
+ *
  * ```ts
  * import { Option } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -1157,14 +1236,15 @@ export declare const between: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category filtering
+ * @since 4.0.0
  */
 export declare const filterMap: {
     /**
      * Transforms and filters a flag value, failing with a custom error if the transformation returns None.
      *
-     * @example
+     * **Example** (Filtering and transforming values)
+     *
      * ```ts
      * import { Option } from "effect"
      * import { Flag } from "effect/unstable/cli"
@@ -1186,14 +1266,15 @@ export declare const filterMap: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category filtering
+     * @since 4.0.0
      */
     <A, B>(f: (a: A) => Option.Option<B>, onNone: (a: A) => string): (self: Flag<A>) => Flag<B>;
     /**
      * Transforms and filters a flag value, failing with a custom error if the transformation returns None.
      *
-     * @example
+     * **Example** (Filtering and transforming values)
+     *
      * ```ts
      * import { Option } from "effect"
      * import { Flag } from "effect/unstable/cli"
@@ -1215,15 +1296,16 @@ export declare const filterMap: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category filtering
+     * @since 4.0.0
      */
     <A, B>(self: Flag<A>, f: (a: A) => Option.Option<B>, onNone: (a: A) => string): Flag<B>;
 };
 /**
  * Filters a flag value based on a predicate, failing with a custom error if the predicate returns false.
  *
- * @example
+ * **Example** (Filtering parsed values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -1244,14 +1326,15 @@ export declare const filterMap: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category filtering
+ * @since 4.0.0
  */
 export declare const filter: {
     /**
      * Filters a flag value based on a predicate, failing with a custom error if the predicate returns false.
      *
-     * @example
+     * **Example** (Filtering parsed values)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -1272,14 +1355,15 @@ export declare const filter: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category filtering
+     * @since 4.0.0
      */
     <A>(predicate: (a: A) => boolean, onFalse: (a: A) => string): (self: Flag<A>) => Flag<A>;
     /**
      * Filters a flag value based on a predicate, failing with a custom error if the predicate returns false.
      *
-     * @example
+     * **Example** (Filtering parsed values)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -1300,15 +1384,16 @@ export declare const filter: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category filtering
+     * @since 4.0.0
      */
     <A>(self: Flag<A>, predicate: (a: A) => boolean, onFalse: (a: A) => string): Flag<A>;
 };
 /**
  * Provides an alternative flag if the first one fails to parse.
  *
- * @example
+ * **Example** (Falling back to another flag)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -1325,14 +1410,15 @@ export declare const filter: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category alternatives
+ * @since 4.0.0
  */
 export declare const orElse: {
     /**
      * Provides an alternative flag if the first one fails to parse.
      *
-     * @example
+     * **Example** (Falling back to another flag)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -1349,14 +1435,15 @@ export declare const orElse: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category alternatives
+     * @since 4.0.0
      */
     <B>(that: LazyArg<Flag<B>>): <A>(self: Flag<A>) => Flag<A | B>;
     /**
      * Provides an alternative flag if the first one fails to parse.
      *
-     * @example
+     * **Example** (Falling back to another flag)
+     *
      * ```ts
      * import { Flag } from "effect/unstable/cli"
      *
@@ -1373,15 +1460,16 @@ export declare const orElse: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category alternatives
+     * @since 4.0.0
      */
     <A, B>(self: Flag<A>, that: LazyArg<Flag<B>>): Flag<A | B>;
 };
 /**
  * Tries to parse with the first flag, then the second, returning a Result that indicates which succeeded.
  *
- * @example
+ * **Example** (Returning fallback results)
+ *
  * ```ts
  * import { Effect, Result } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -1405,14 +1493,15 @@ export declare const orElse: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category alternatives
+ * @since 4.0.0
  */
 export declare const orElseResult: {
     /**
      * Tries to parse with the first flag, then the second, returning a Result that indicates which succeeded.
      *
-     * @example
+     * **Example** (Returning fallback results)
+     *
      * ```ts
      * import { Effect, Result } from "effect"
      * import { Flag } from "effect/unstable/cli"
@@ -1436,14 +1525,15 @@ export declare const orElseResult: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category alternatives
+     * @since 4.0.0
      */
     <B>(that: LazyArg<Flag<B>>): <A>(self: Flag<A>) => Flag<Result.Result<A, B>>;
     /**
      * Tries to parse with the first flag, then the second, returning a Result that indicates which succeeded.
      *
-     * @example
+     * **Example** (Returning fallback results)
+     *
      * ```ts
      * import { Effect, Result } from "effect"
      * import { Flag } from "effect/unstable/cli"
@@ -1467,20 +1557,21 @@ export declare const orElseResult: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category alternatives
+     * @since 4.0.0
      */
     <A, B>(self: Flag<A>, that: LazyArg<Flag<B>>): Flag<Result.Result<A, B>>;
 };
 /**
  * Validates and transforms a flag value using a Schema codec.
  *
- * @example
+ * **Example** (Validating with schemas)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Flag } from "effect/unstable/cli"
  *
- * const isEmail = Schema.isIncludes("@", {
+ * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, {
  *   message: "Must be a valid email address"
  * })
  *
@@ -1505,19 +1596,20 @@ export declare const orElseResult: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const withSchema: {
     /**
      * Validates and transforms a flag value using a Schema codec.
      *
-     * @example
+     * **Example** (Validating with schemas)
+     *
      * ```ts
      * import { Schema } from "effect"
      * import { Flag } from "effect/unstable/cli"
      *
-     * const isEmail = Schema.isIncludes("@", {
+     * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, {
      *   message: "Must be a valid email address"
      * })
      *
@@ -1542,19 +1634,20 @@ export declare const withSchema: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category schemas
+     * @since 4.0.0
      */
     <A, B>(schema: Schema.Codec<B, A>): (self: Flag<A>) => Flag<B>;
     /**
      * Validates and transforms a flag value using a Schema codec.
      *
-     * @example
+     * **Example** (Validating with schemas)
+     *
      * ```ts
      * import { Schema } from "effect"
      * import { Flag } from "effect/unstable/cli"
      *
-     * const isEmail = Schema.isIncludes("@", {
+     * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, {
      *   message: "Must be a valid email address"
      * })
      *
@@ -1579,8 +1672,8 @@ export declare const withSchema: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category schemas
+     * @since 4.0.0
      */
     <A, B>(self: Flag<A>, schema: Schema.Codec<B, A>): Flag<B>;
 };