effect 4.0.0-beta.66 → 4.0.0-beta.67

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

@@ -1,4 +1,26 @@
 /**
+ * The `Argument` module defines typed positional command-line arguments for
+ * Effect CLI applications. Arguments consume ordered values after a command name
+ * and its flags, then parse them into the types your command handler expects.
+ *
+ * Use this module for required inputs such as file paths, directories, numbers,
+ * dates, choices, secrets, and structured configuration files. Arguments can be
+ * made optional, variadic, validated with Schema, transformed with pure or
+ * effectful functions, and supplied from defaults, config, or prompts when
+ * missing.
+ *
+ * **Gotchas**
+ *
+ * - Positional arguments are order-sensitive; compose them in the same order the
+ *   user should type them.
+ * - `variadic` arguments can consume more than one value, so place them where
+ *   the remaining positional input belongs.
+ * - Use {@link withDescription} and {@link withMetavar} to keep generated help
+ *   text clear, especially when the parser name differs from the value users
+ *   should provide.
+ * - Boolean positional arguments are intentionally not provided. Prefer boolean
+ *   flags, or use {@link choice} for explicit `"true"` / `"false"` values.
+ *
  * @since 4.0.0
  */
 import type * as Config from "../../Config.ts";
@@ -19,43 +41,46 @@ import type * as Primitive from "./Primitive.ts";
  * no flag name to negate (e.g., `--no-verbose`). Use Flag.boolean instead,
  * or use Argument.choice with explicit "true"/"false" strings if needed.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Argument<A> extends Param.Param<typeof Param.argumentKind, A> {
 }
 /**
  * Creates a positional string argument.
  *
- * @example
+ * **Example** (Creating a string argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const filename = Argument.string("filename")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const string: (name: string) => Argument<string>;
 /**
  * Creates a positional integer argument.
  *
- * @example
+ * **Example** (Creating an integer argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const count = Argument.integer("count")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const integer: (name: string) => Argument<number>;
 /**
  * Creates a positional file path argument.
  *
- * @example
+ * **Example** (Creating file path arguments)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -63,8 +88,8 @@ export declare const integer: (name: string) => Argument<number>;
  * const outputFile = Argument.file("output", { mustExist: false }) // Must not exist
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const file: (name: string, options?: {
     readonly mustExist?: boolean | undefined;
@@ -72,15 +97,16 @@ export declare const file: (name: string, options?: {
 /**
  * Creates a positional directory path argument.
  *
- * @example
+ * **Example** (Creating a directory path argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const workspace = Argument.directory("workspace", { mustExist: true }) // Must exist
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const directory: (name: string, options?: {
     readonly mustExist?: boolean | undefined;
@@ -88,57 +114,61 @@ export declare const directory: (name: string, options?: {
 /**
  * Creates a positional float argument.
  *
- * @example
+ * **Example** (Creating a float argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const ratio = Argument.float("ratio")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const float: (name: string) => Argument<number>;
 /**
  * Creates a positional date argument.
  *
- * @example
+ * **Example** (Creating a date argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const startDate = Argument.date("start-date")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const date: (name: string) => Argument<Date>;
 /**
  * Creates a positional choice argument.
  *
- * @example
+ * **Example** (Creating a choice argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const environment = Argument.choice("environment", ["dev", "staging", "prod"])
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const choice: <const Choices extends ReadonlyArray<string>>(name: string, choices: Choices) => Argument<Choices[number]>;
 /**
  * Creates a positional path argument.
  *
- * @example
+ * **Example** (Creating a path argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const configPath = Argument.path("config")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const path: (name: string, options?: {
     pathType?: "file" | "directory" | "either";
@@ -147,49 +177,57 @@ export declare const path: (name: string, options?: {
 /**
  * Creates a positional redacted argument that obscures its value.
  *
- * @example
+ * **Example** (Creating a redacted argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const secret = Argument.redacted("secret")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const redacted: (name: string) => Argument<Redacted.Redacted<string>>;
 /**
  * Creates a positional argument that reads file content as a string.
  *
- * @example
+ * **Example** (Reading file text)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const config = Argument.fileText("config-file")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fileText: (name: string) => Argument<string>;
 /**
- * Creates a positional argument that reads and validates file content using a schema.
+ * Creates a positional argument that reads a file and parses its content.
+ *
+ * The parser is chosen from the explicit `format` option or, when omitted, the
+ * file extension. The parsed value is `unknown`; use `fileSchema` when the
+ * parsed content should also be decoded with a Schema.
+ *
+ * **Example** (Parsing file content)
  *
- * @example
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const config = Argument.fileParse("config", { format: "json" })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fileParse: (name: string, options?: Primitive.FileParseOptions | undefined) => Argument<unknown>;
 /**
  * Creates a positional argument that reads and validates file content using a schema.
  *
- * @example
+ * **Example** (Validating file content with a schema)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Argument } from "effect/unstable/cli"
@@ -202,14 +240,15 @@ export declare const fileParse: (name: string, options?: Primitive.FileParseOpti
  * const config = Argument.fileSchema("config", ConfigSchema)
  * ```
  *
- * @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) => Argument<A>;
 /**
  * Creates an empty sentinel argument that always fails to parse.
  *
- * @example
+ * **Example** (Creating a sentinel argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -217,28 +256,30 @@ export declare const fileSchema: <A>(name: string, schema: Schema.Decoder<A>, op
  * const noArg = Argument.none
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const none: Argument<never>;
 /**
  * Makes a positional argument optional.
  *
- * @example
+ * **Example** (Making an argument optional)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const optionalVersion = Argument.string("version").pipe(Argument.optional)
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const optional: <A>(arg: Argument<A>) => Argument<Option.Option<A>>;
 /**
  * Adds a description to a positional argument.
  *
- * @example
+ * **Example** (Adding an argument description)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -247,14 +288,15 @@ export declare const optional: <A>(arg: Argument<A>) => Argument<Option.Option<A
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withDescription: {
     /**
      * Adds a description to a positional argument.
      *
-     * @example
+     * **Example** (Adding an argument description)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -263,14 +305,15 @@ export declare const withDescription: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(description: string): (self: Argument<A>) => Argument<A>;
     /**
      * Adds a description to a positional argument.
      *
-     * @example
+     * **Example** (Adding an argument description)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -279,58 +322,62 @@ export declare const withDescription: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: Argument<A>, description: string): Argument<A>;
 };
 /**
  * Provides a default value for a positional argument.
  *
- * @example
+ * **Example** (Providing a default value)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const port = Argument.integer("port").pipe(Argument.withDefault(8080))
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withDefault: {
     /**
      * Provides a default value for a positional argument.
      *
-     * @example
+     * **Example** (Providing a default value)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
      * const port = Argument.integer("port").pipe(Argument.withDefault(8080))
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <const B>(defaultValue: B | Effect.Effect<B, CliError.CliError, Param.Environment>): <A>(self: Argument<A>) => Argument<A | B>;
     /**
      * Provides a default value for a positional argument.
      *
-     * @example
+     * **Example** (Providing a default value)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
      * const port = Argument.integer("port").pipe(Argument.withDefault(8080))
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, const B>(self: Argument<A>, defaultValue: B | Effect.Effect<B, CliError.CliError, Param.Environment>): Argument<A | B>;
 };
 /**
  * Adds a fallback config that is loaded when a required argument is missing.
  *
- * @example
+ * **Example** (Loading a fallback config)
+ *
  * ```ts
  * import { Config } from "effect"
  * import { Argument } from "effect/unstable/cli"
@@ -340,14 +387,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 argument is missing.
      *
-     * @example
+     * **Example** (Loading a fallback config)
+     *
      * ```ts
      * import { Config } from "effect"
      * import { Argument } from "effect/unstable/cli"
@@ -357,14 +405,15 @@ export declare const withFallbackConfig: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <B>(config: Config.Config<B>): <A>(self: Argument<A>) => Argument<A | B>;
     /**
      * Adds a fallback config that is loaded when a required argument is missing.
      *
-     * @example
+     * **Example** (Loading a fallback config)
+     *
      * ```ts
      * import { Config } from "effect"
      * import { Argument } from "effect/unstable/cli"
@@ -374,15 +423,16 @@ export declare const withFallbackConfig: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(self: Argument<A>, config: Config.Config<B>): Argument<A | B>;
 };
 /**
  * Adds a fallback prompt that is shown when a required argument is missing.
  *
- * @example
+ * **Example** (Showing a fallback prompt)
+ *
  * ```ts
  * import { Argument, Prompt } from "effect/unstable/cli"
  *
@@ -391,14 +441,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 argument is missing.
      *
-     * @example
+     * **Example** (Showing a fallback prompt)
+     *
      * ```ts
      * import { Argument, Prompt } from "effect/unstable/cli"
      *
@@ -407,14 +458,15 @@ export declare const withFallbackPrompt: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <B>(prompt: Param.FallbackPrompt<B>): <A>(self: Argument<A>) => Argument<A | B>;
     /**
      * Adds a fallback prompt that is shown when a required argument is missing.
      *
-     * @example
+     * **Example** (Showing a fallback prompt)
+     *
      * ```ts
      * import { Argument, Prompt } from "effect/unstable/cli"
      *
@@ -423,15 +475,16 @@ export declare const withFallbackPrompt: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(self: Argument<A>, prompt: Param.FallbackPrompt<B>): Argument<A | B>;
 };
 /**
  * Creates a variadic positional argument that accepts multiple values.
  *
- * @example
+ * **Example** (Accepting multiple values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -449,14 +502,15 @@ export declare const withFallbackPrompt: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const variadic: {
     /**
      * Creates a variadic positional argument that accepts multiple values.
      *
-     * @example
+     * **Example** (Accepting multiple values)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -474,14 +528,15 @@ export declare const variadic: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     (options?: Param.VariadicParamOptions | undefined): <A>(self: Argument<A>) => Argument<ReadonlyArray<A>>;
     /**
      * Creates a variadic positional argument that accepts multiple values.
      *
-     * @example
+     * **Example** (Accepting multiple values)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -499,15 +554,16 @@ export declare const variadic: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: Argument<A>, options?: Param.VariadicParamOptions | undefined): Argument<ReadonlyArray<A>>;
 };
 /**
  * Transforms the parsed value of a positional argument.
  *
- * @example
+ * **Example** (Mapping parsed values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -516,14 +572,15 @@ export declare const variadic: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const map: {
     /**
      * Transforms the parsed value of a positional argument.
      *
-     * @example
+     * **Example** (Mapping parsed values)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -532,14 +589,15 @@ export declare const map: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(f: (a: A) => B): (self: Argument<A>) => Argument<B>;
     /**
      * Transforms the parsed value of a positional argument.
      *
-     * @example
+     * **Example** (Mapping parsed values)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -548,15 +606,16 @@ export declare const map: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(self: Argument<A>, f: (a: A) => B): Argument<B>;
 };
 /**
  * Transforms the parsed value of a positional argument using an effectful function.
  *
- * @example
+ * **Example** (Validating values effectfully)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { Argument, CliError } from "effect/unstable/cli"
@@ -574,14 +633,15 @@ export declare const map: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const mapEffect: {
     /**
      * Transforms the parsed value of a positional argument using an effectful function.
      *
-     * @example
+     * **Example** (Validating values effectfully)
+     *
      * ```ts
      * import { Effect } from "effect"
      * import { Argument, CliError } from "effect/unstable/cli"
@@ -599,14 +659,15 @@ export declare const mapEffect: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(f: (a: A) => Effect.Effect<B, CliError.CliError, Param.Environment>): (self: Argument<A>) => Argument<B>;
     /**
      * Transforms the parsed value of a positional argument using an effectful function.
      *
-     * @example
+     * **Example** (Validating values effectfully)
+     *
      * ```ts
      * import { Effect } from "effect"
      * import { Argument, CliError } from "effect/unstable/cli"
@@ -624,15 +685,16 @@ export declare const mapEffect: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(self: Argument<A>, f: (a: A) => Effect.Effect<B, CliError.CliError, Param.Environment>): Argument<B>;
 };
 /**
  * Transforms the parsed value of a positional argument using a function that may throw.
  *
- * @example
+ * **Example** (Mapping values that may throw)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -645,14 +707,15 @@ export declare const mapEffect: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const mapTryCatch: {
     /**
      * Transforms the parsed value of a positional argument using a function that may throw.
      *
-     * @example
+     * **Example** (Mapping values that may throw)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -665,14 +728,15 @@ export declare const mapTryCatch: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(f: (a: A) => B, onError: (error: unknown) => string): (self: Argument<A>) => Argument<B>;
     /**
      * Transforms the parsed value of a positional argument using a function that may throw.
      *
-     * @example
+     * **Example** (Mapping values that may throw)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -685,144 +749,154 @@ export declare const mapTryCatch: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(self: Argument<A>, f: (a: A) => B, onError: (error: unknown) => string): Argument<B>;
 };
 /**
  * Creates a variadic argument that requires at least n values.
  *
- * @example
+ * **Example** (Requiring a minimum number of values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const files = Argument.string("files").pipe(Argument.atLeast(1))
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const atLeast: {
     /**
      * Creates a variadic argument that requires at least n values.
      *
-     * @example
+     * **Example** (Requiring a minimum number of values)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
      * const files = Argument.string("files").pipe(Argument.atLeast(1))
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(min: number): (self: Argument<A>) => Argument<ReadonlyArray<A>>;
     /**
      * Creates a variadic argument that requires at least n values.
      *
-     * @example
+     * **Example** (Requiring a minimum number of values)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
      * const files = Argument.string("files").pipe(Argument.atLeast(1))
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: Argument<A>, min: number): Argument<ReadonlyArray<A>>;
 };
 /**
  * Creates a variadic argument that accepts at most n values.
  *
- * @example
+ * **Example** (Limiting the maximum number of values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const files = Argument.string("files").pipe(Argument.atMost(5))
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const atMost: {
     /**
      * Creates a variadic argument that accepts at most n values.
      *
-     * @example
+     * **Example** (Limiting the maximum number of values)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
      * const files = Argument.string("files").pipe(Argument.atMost(5))
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(max: number): (self: Argument<A>) => Argument<ReadonlyArray<A>>;
     /**
      * Creates a variadic argument that accepts at most n values.
      *
-     * @example
+     * **Example** (Limiting the maximum number of values)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
      * const files = Argument.string("files").pipe(Argument.atMost(5))
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: Argument<A>, max: number): Argument<ReadonlyArray<A>>;
 };
 /**
  * Creates a variadic argument that accepts between min and max values.
  *
- * @example
+ * **Example** (Requiring a range of values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const files = Argument.string("files").pipe(Argument.between(1, 5))
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const between: {
     /**
      * Creates a variadic argument that accepts between min and max values.
      *
-     * @example
+     * **Example** (Requiring a range of values)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
      * const files = Argument.string("files").pipe(Argument.between(1, 5))
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(min: number, max: number): (self: Argument<A>) => Argument<ReadonlyArray<A>>;
     /**
      * Creates a variadic argument that accepts between min and max values.
      *
-     * @example
+     * **Example** (Requiring a range of values)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
      * const files = Argument.string("files").pipe(Argument.between(1, 5))
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: Argument<A>, min: number, max: number): Argument<ReadonlyArray<A>>;
 };
 /**
  * Validates parsed values against a Schema.
  *
- * @example
+ * **Example** (Validating parsed values with a schema)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Argument } from "effect/unstable/cli"
@@ -832,14 +906,15 @@ export declare const between: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withSchema: {
     /**
      * Validates parsed values against a Schema.
      *
-     * @example
+     * **Example** (Validating parsed values with a schema)
+     *
      * ```ts
      * import { Schema } from "effect"
      * import { Argument } from "effect/unstable/cli"
@@ -849,14 +924,15 @@ export declare const withSchema: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(schema: Schema.Codec<B, A>): (self: Argument<A>) => Argument<B>;
     /**
      * Validates parsed values against a Schema.
      *
-     * @example
+     * **Example** (Validating parsed values with a schema)
+     *
      * ```ts
      * import { Schema } from "effect"
      * import { Argument } from "effect/unstable/cli"
@@ -866,15 +942,16 @@ export declare const withSchema: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(self: Argument<A>, schema: Schema.Codec<B, A>): Argument<B>;
 };
 /**
  * Creates a positional choice argument with custom value mapping.
  *
- * @example
+ * **Example** (Mapping choices to values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -886,8 +963,8 @@ export declare const withSchema: {
  * ])
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const choiceWithValue: <const Choices extends ReadonlyArray<readonly [string, any]>>(name: string, choices: Choices) => Argument<Choices[number][1]>;
 /**
@@ -896,7 +973,8 @@ export declare const choiceWithValue: <const Choices extends ReadonlyArray<reado
  * The metavar is displayed in usage text to indicate what value the user should provide.
  * For example, `<FILE>` shows `FILE` as the metavar.
  *
- * @example
+ * **Example** (Setting a metavar)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -905,8 +983,8 @@ export declare const choiceWithValue: <const Choices extends ReadonlyArray<reado
  * )
  * ```
  *
- * @since 4.0.0
  * @category metadata
+ * @since 4.0.0
  */
 export declare const withMetavar: {
     /**
@@ -915,7 +993,8 @@ export declare const withMetavar: {
      * The metavar is displayed in usage text to indicate what value the user should provide.
      * For example, `<FILE>` shows `FILE` as the metavar.
      *
-     * @example
+     * **Example** (Setting a metavar)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -924,8 +1003,8 @@ export declare const withMetavar: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category metadata
+     * @since 4.0.0
      */
     <A>(metavar: string): (self: Argument<A>) => Argument<A>;
     /**
@@ -934,7 +1013,8 @@ export declare const withMetavar: {
      * The metavar is displayed in usage text to indicate what value the user should provide.
      * For example, `<FILE>` shows `FILE` as the metavar.
      *
-     * @example
+     * **Example** (Setting a metavar)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -943,15 +1023,16 @@ export declare const withMetavar: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category metadata
+     * @since 4.0.0
      */
     <A>(self: Argument<A>, metavar: string): Argument<A>;
 };
 /**
  * Filters parsed values, failing with a custom error message if the predicate returns false.
  *
- * @example
+ * **Example** (Filtering parsed values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -963,14 +1044,15 @@ export declare const withMetavar: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const filter: {
     /**
      * Filters parsed values, failing with a custom error message if the predicate returns false.
      *
-     * @example
+     * **Example** (Filtering parsed values)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -982,14 +1064,15 @@ export declare const filter: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(predicate: (a: A) => boolean, onFalse: (a: A) => string): (self: Argument<A>) => Argument<A>;
     /**
      * Filters parsed values, failing with a custom error message if the predicate returns false.
      *
-     * @example
+     * **Example** (Filtering parsed values)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -1001,8 +1084,8 @@ export declare const filter: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A>(self: Argument<A>, predicate: (a: A) => boolean, onFalse: (a: A) => string): Argument<A>;
 };
@@ -1010,7 +1093,8 @@ export declare const filter: {
  * Filters and transforms parsed values, failing with a custom error message
  * if the filter function returns None.
  *
- * @example
+ * **Example** (Filtering and mapping parsed values)
+ *
  * ```ts
  * import { Option } from "effect"
  * import { Argument } from "effect/unstable/cli"
@@ -1023,15 +1107,16 @@ export declare const filter: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const filterMap: {
     /**
      * Filters and transforms parsed values, failing with a custom error message
      * if the filter function returns None.
      *
-     * @example
+     * **Example** (Filtering and mapping parsed values)
+     *
      * ```ts
      * import { Option } from "effect"
      * import { Argument } from "effect/unstable/cli"
@@ -1044,15 +1129,16 @@ export declare const filterMap: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(f: (a: A) => Option.Option<B>, onNone: (a: A) => string): (self: Argument<A>) => Argument<B>;
     /**
      * Filters and transforms parsed values, failing with a custom error message
      * if the filter function returns None.
      *
-     * @example
+     * **Example** (Filtering and mapping parsed values)
+     *
      * ```ts
      * import { Option } from "effect"
      * import { Argument } from "effect/unstable/cli"
@@ -1065,15 +1151,16 @@ export declare const filterMap: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(self: Argument<A>, f: (a: A) => Option.Option<B>, onNone: (a: A) => string): Argument<B>;
 };
 /**
  * Provides a fallback argument to use if this argument fails to parse.
  *
- * @example
+ * **Example** (Providing a fallback argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -1082,14 +1169,15 @@ export declare const filterMap: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const orElse: {
     /**
      * Provides a fallback argument to use if this argument fails to parse.
      *
-     * @example
+     * **Example** (Providing a fallback argument)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -1098,14 +1186,15 @@ export declare const orElse: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <B>(that: LazyArg<Argument<B>>): <A>(self: Argument<A>) => Argument<A | B>;
     /**
      * Provides a fallback argument to use if this argument fails to parse.
      *
-     * @example
+     * **Example** (Providing a fallback argument)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -1114,15 +1203,16 @@ export declare const orElse: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(self: Argument<A>, that: LazyArg<Argument<B>>): Argument<A | B>;
 };
 /**
  * Provides a fallback argument, wrapping results in Result to distinguish which succeeded.
  *
- * @example
+ * **Example** (Returning which fallback succeeded)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -1132,14 +1222,15 @@ export declare const orElse: {
  * // Returns Result<string, string>
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const orElseResult: {
     /**
      * Provides a fallback argument, wrapping results in Result to distinguish which succeeded.
      *
-     * @example
+     * **Example** (Returning which fallback succeeded)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -1149,14 +1240,15 @@ export declare const orElseResult: {
      * // Returns Result<string, string>
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <B>(that: LazyArg<Argument<B>>): <A>(self: Argument<A>) => Argument<Result.Result<A, B>>;
     /**
      * Provides a fallback argument, wrapping results in Result to distinguish which succeeded.
      *
-     * @example
+     * **Example** (Returning which fallback succeeded)
+     *
      * ```ts
      * import { Argument } from "effect/unstable/cli"
      *
@@ -1166,8 +1258,8 @@ export declare const orElseResult: {
      * // Returns Result<string, string>
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A, B>(self: Argument<A>, that: LazyArg<Argument<B>>): Argument<Result.Result<A, B>>;
 };