effect 4.0.0-beta.85 → 4.0.0-beta.86

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

@@ -12,14 +12,15 @@
  */
 import * as Config from "../../Config.ts";
 import * as Effect from "../../Effect.ts";
-import type * as FileSystem from "../../FileSystem.ts";
 import * as Option from "../../Option.ts";
-import type * as Path from "../../Path.ts";
 import { type Pipeable } from "../../Pipeable.ts";
-import type * as Terminal from "../../Terminal.ts";
+import * as Predicate from "../../Predicate.ts";
+import type * as Redacted from "../../Redacted.ts";
+import * as Result from "../../Result.ts";
+import * as Schema from "../../Schema.ts";
 import type { Covariant } from "../../Types.ts";
-import type { ChildProcessSpawner } from "../process/ChildProcessSpawner.ts";
 import * as CliError from "./CliError.ts";
+import type { Environment } from "./Command.ts";
 import * as Primitive from "./Primitive.ts";
 import * as Prompt from "./Prompt.ts";
 declare const TypeId = "~effect/cli/Param";
@@ -47,14 +48,6 @@ export interface Param<Kind extends ParamKind, out A> extends Param.Variance<A>
  * @since 4.0.0
  */
 export type ParamKind = "argument" | "flag";
-/**
- * Services that parameter parsing can require, such as filesystem, path,
- * terminal, and child-process support.
- *
- * @category models
- * @since 4.0.0
- */
-export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal | ChildProcessSpawner;
 /**
  * Defines the kind discriminator for positional argument parameters.
  *
@@ -239,6 +232,44 @@ export interface Variadic<Kind extends ParamKind, A> extends Param<Kind, Readonl
     readonly min: Option.Option<number>;
     readonly max: Option.Option<number>;
 }
+/**
+ * Type guard to check if a value is a Param.
+ *
+ * **Example** (Checking for params)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const maybeParam = Param.string(Param.flagKind, "name")
+ *
+ * if (Param.isParam(maybeParam)) {
+ *   console.log("This is a Param")
+ * }
+ * ```
+ *
+ * @category refinements
+ * @since 4.0.0
+ */
+export declare const isParam: (u: unknown) => u is Param<any, ParamKind>;
+/**
+ * Type guard to check if a param is a Single param (not composed).
+ *
+ * **Example** (Checking for single params)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const nameParam = Param.string(Param.flagKind, "name")
+ * const optionalParam = Param.optional(nameParam)
+ *
+ * console.log(Param.isSingle(nameParam)) // true
+ * console.log(Param.isSingle(optionalParam)) // false
+ * ```
+ *
+ * @category refinements
+ * @since 4.0.0
+ */
+export declare const isSingle: <const Kind extends ParamKind, A>(param: Param<Kind, A>) => param is Single<Kind, A>;
 /**
  * Constructs a leaf `Single` parameter from its kind, name, primitive parser,
  * and optional help metadata.
@@ -261,199 +292,1806 @@ export declare const makeSingle: <const Kind extends ParamKind, A>(params: {
     readonly hidden?: boolean | undefined;
 }) => Single<Kind, A>;
 /**
- * Makes a flag or positional argument optional.
+ * Creates a string parameter.
  *
- * **Details**
+ * **Example** (Creating string parameters)
  *
- * When the parameter is absent, parsing succeeds with `Option.none()` instead
- * of failing with a missing option or missing argument error. When present, the
- * parsed value is wrapped in `Option.some()`.
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
  *
- * **Example** (Making parameters optional)
+ * // Create a string flag
+ * const nameFlag = Param.string(Param.flagKind, "name")
+ *
+ * // Create a string argument
+ * const fileArg = Param.string(Param.argumentKind, "file")
+ *
+ * // Usage in CLI: --name "John Doe" or as positional argument
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const string: <const Kind extends ParamKind>(kind: Kind, name: string) => Param<Kind, string>;
+/**
+ * Creates a boolean parameter.
+ *
+ * **Example** (Creating boolean parameters)
  *
  * ```ts
  * import { Param } from "effect/unstable/cli"
  *
- * // Create an optional port option
- * // - When not provided: returns Option.none()
- * // - When provided: returns Option.some(parsedValue)
- * const port = Param.optional(Param.integer(Param.flagKind, "port"))
+ * // Create a boolean flag
+ * const verboseFlag = Param.boolean(Param.flagKind, "verbose")
+ *
+ * // Create a boolean argument
+ * const enableArg = Param.boolean(Param.argumentKind, "enable")
+ *
+ * // Usage in CLI: --verbose (defaults to true when present, false when absent)
+ * // or as positional: true/false
  * ```
  *
- * @category combinators
+ * @category constructors
  * @since 4.0.0
  */
-export declare const optional: <Kind extends ParamKind, A>(param: Param<Kind, A>) => Param<Kind, Option.Option<A>>;
+export declare const boolean: <const Kind extends ParamKind>(kind: Kind, name: string) => Param<Kind, boolean>;
 /**
- * Adds a fallback config that is loaded when a required parameter is missing.
+ * Creates an integer parameter.
  *
- * **When to use**
+ * **Example** (Creating integer parameters)
  *
- * Use when you need config to provide a fallback source for required flags or
- * arguments that are absent from CLI input.
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
  *
- * **Details**
+ * // Create an integer flag
+ * const portFlag = Param.integer(Param.flagKind, "port")
  *
- * Provided CLI values win. Config is loaded only after a missing option or
- * missing argument error.
+ * // Create an integer argument
+ * const countArg = Param.integer(Param.argumentKind, "count")
  *
- * **Gotchas**
+ * // Usage in CLI: --port 8080 or as positional argument: 42
+ * ```
  *
- * Missing config preserves the original missing-parameter error. Config parse
- * failure becomes `CliError.InvalidValue`.
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const integer: <const Kind extends ParamKind>(kind: Kind, name: string) => Param<Kind, number>;
+/**
+ * Creates a floating-point number parameter.
  *
- * @see {@link withDefault} for a pure default value
- * @see {@link withFallbackPrompt} for prompting interactively when input is missing
+ * **Example** (Creating float parameters)
  *
- * @category combinators
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // Create a float flag
+ * const rateFlag = Param.float(Param.flagKind, "rate")
+ *
+ * // Create a float argument
+ * const thresholdArg = Param.float(Param.argumentKind, "threshold")
+ *
+ * // Usage in CLI: --rate 0.95 or as positional argument: 3.14159
+ * ```
+ *
+ * @category constructors
  * @since 4.0.0
  */
-export declare const withFallbackConfig: {
-    /**
-     * Adds a fallback config that is loaded when a required parameter is missing.
-     *
-     * **When to use**
-     *
-     * Use when you need config to provide a fallback source for required flags or
-     * arguments that are absent from CLI input.
-     *
-     * **Details**
-     *
-     * Provided CLI values win. Config is loaded only after a missing option or
-     * missing argument error.
-     *
-     * **Gotchas**
-     *
-     * Missing config preserves the original missing-parameter error. Config parse
-     * failure becomes `CliError.InvalidValue`.
-     *
-     * @see {@link withDefault} for a pure default value
-     * @see {@link withFallbackPrompt} for prompting interactively when input is missing
-     *
-     * @category combinators
-     * @since 4.0.0
-     */
-    <B>(config: Config.Config<B>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, A | B>;
-    /**
-     * Adds a fallback config that is loaded when a required parameter is missing.
-     *
-     * **When to use**
-     *
-     * Use when you need config to provide a fallback source for required flags or
-     * arguments that are absent from CLI input.
-     *
-     * **Details**
-     *
-     * Provided CLI values win. Config is loaded only after a missing option or
-     * missing argument error.
-     *
-     * **Gotchas**
-     *
-     * Missing config preserves the original missing-parameter error. Config parse
-     * failure becomes `CliError.InvalidValue`.
-     *
-     * @see {@link withDefault} for a pure default value
-     * @see {@link withFallbackPrompt} for prompting interactively when input is missing
-     *
-     * @category combinators
-     * @since 4.0.0
-     */
-    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, config: Config.Config<B>): Param<Kind, A | B>;
-};
+export declare const float: <const Kind extends ParamKind>(kind: Kind, name: string) => Param<Kind, number>;
 /**
- * Adds a fallback prompt that is shown when a required parameter is missing.
+ * Creates a date parameter that parses ISO date strings.
  *
- * **When to use**
+ * **Example** (Creating date parameters)
  *
- * Use when a CLI should ask interactively for a missing required flag or
- * argument.
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
  *
- * **Details**
+ * // Create a date flag
+ * const startFlag = Param.date(Param.flagKind, "start-date")
  *
- * `FallbackPrompt` accepts either a `Prompt` or an effect that builds one.
- * Effectful prompt creation is lazy and runs only when the fallback is needed.
+ * // Create a date argument
+ * const dueDateArg = Param.date(Param.argumentKind, "due-date")
  *
- * **Gotchas**
+ * // Usage in CLI: --start-date "2023-12-25" or as positional: "2023-01-01"
+ * // Parses to JavaScript Date object
+ * ```
  *
- * This only handles missing options and missing arguments. Invalid values do not
- * prompt, and prompt cancellation re-fails with the original missing error.
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const date: <const Kind extends ParamKind>(kind: Kind, name: string) => Param<Kind, Date>;
+/**
+ * Constructs command-line params that represent a choice between several
+ * inputs. The input will be mapped to it's associated value during parsing.
  *
- * @see {@link FallbackPrompt} for accepted fallback prompt forms
- * @see {@link withFallbackConfig} for loading a fallback from config
- * @see {@link withDefault} for a pure default value
+ * **Example** (Creating valued choices)
  *
- * @category combinators
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * type Animal = Dog | Cat
+ *
+ * interface Dog {
+ *   readonly _tag: "Dog"
+ * }
+ *
+ * interface Cat {
+ *   readonly _tag: "Cat"
+ * }
+ *
+ * const animal = Param.choiceWithValue(Param.flagKind, "animal", [
+ *   ["dog", { _tag: "Dog" }],
+ *   ["cat", { _tag: "Cat" }]
+ * ])
+ * ```
+ *
+ * @category constructors
  * @since 4.0.0
  */
-export declare const withFallbackPrompt: {
-    /**
-     * Adds a fallback prompt that is shown when a required parameter is missing.
-     *
-     * **When to use**
-     *
-     * Use when a CLI should ask interactively for a missing required flag or
-     * argument.
-     *
-     * **Details**
-     *
-     * `FallbackPrompt` accepts either a `Prompt` or an effect that builds one.
-     * Effectful prompt creation is lazy and runs only when the fallback is needed.
-     *
-     * **Gotchas**
-     *
-     * This only handles missing options and missing arguments. Invalid values do not
-     * prompt, and prompt cancellation re-fails with the original missing error.
-     *
-     * @see {@link FallbackPrompt} for accepted fallback prompt forms
-     * @see {@link withFallbackConfig} for loading a fallback from config
-     * @see {@link withDefault} for a pure default value
-     *
-     * @category combinators
-     * @since 4.0.0
-     */
-    <B>(prompt: FallbackPrompt<B>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, A | B>;
-    /**
-     * Adds a fallback prompt that is shown when a required parameter is missing.
-     *
-     * **When to use**
-     *
-     * Use when a CLI should ask interactively for a missing required flag or
-     * argument.
-     *
-     * **Details**
-     *
-     * `FallbackPrompt` accepts either a `Prompt` or an effect that builds one.
-     * Effectful prompt creation is lazy and runs only when the fallback is needed.
-     *
-     * **Gotchas**
-     *
-     * This only handles missing options and missing arguments. Invalid values do not
-     * prompt, and prompt cancellation re-fails with the original missing error.
-     *
-     * @see {@link FallbackPrompt} for accepted fallback prompt forms
-     * @see {@link withFallbackConfig} for loading a fallback from config
-     * @see {@link withDefault} for a pure default value
-     *
-     * @category combinators
-     * @since 4.0.0
-     */
-    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, prompt: FallbackPrompt<B>): Param<Kind, A | B>;
-};
+export declare const choiceWithValue: <const Kind extends ParamKind, const Choices extends ReadonlyArray<readonly [string, any]>>(kind: Kind, name: string, choices: Choices) => Param<Kind, Choices[number][1]>;
 /**
- * Represent options which can be used to configure variadic parameters.
+ * Constructs command-line params that represent a choice between several
+ * string inputs.
  *
- * @category options
+ * **Example** (Creating string choices)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const logLevel = Param.choice(Param.flagKind, "log-level", [
+ *   "debug",
+ *   "info",
+ *   "warn",
+ *   "error"
+ * ])
+ * ```
+ *
+ * @category constructors
  * @since 4.0.0
  */
-export type VariadicParamOptions = {
-    /**
-     * The minimum number of times the parameter can be specified.
-     */
-    readonly min?: number | undefined;
-    /**
-     * The maximum number of times the parameter can be specified.
-     */
-    readonly max?: number | undefined;
+export declare const choice: <const Kind extends ParamKind, const Choices extends ReadonlyArray<string>>(kind: Kind, name: string, choices: Choices) => Param<Kind, Choices[number]>;
+/**
+ * Creates a path parameter that accepts file or directory paths.
+ *
+ * **Example** (Creating path parameters)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // Basic path parameter
+ * const outputPath = Param.path(Param.flagKind, "output")
+ *
+ * // Path that must exist
+ * const inputPath = Param.path(Param.flagKind, "input", { mustExist: true })
+ *
+ * // File-only path
+ * const configFile = Param.path(Param.flagKind, "config", {
+ *   pathType: "file",
+ *   mustExist: true,
+ *   typeName: "config-file"
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const path: <Kind extends ParamKind>(kind: Kind, name: string, options?: {
+    readonly pathType?: Primitive.PathType | undefined;
+    readonly mustExist?: boolean | undefined;
+    readonly typeName?: string | undefined;
+}) => Param<Kind, string>;
+/**
+ * Creates a directory path parameter.
+ *
+ * **Details**
+ *
+ * This is a convenience function that creates a path parameter with the
+ * `pathType` set to `"directory"` and a default type name of `"directory"`.
+ *
+ * **Example** (Creating directory parameters)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // Basic directory parameter
+ * const outputDir = Param.directory(Param.flagKind, "output-dir")
+ *
+ * // Directory that must exist
+ * const sourceDir = Param.directory(Param.flagKind, "source", { mustExist: true })
+ *
+ * // Usage: --output-dir /path/to/dir --source /existing/dir
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const directory: <Kind extends ParamKind>(kind: Kind, name: string, options?: {
+    readonly mustExist?: boolean | undefined;
+}) => Param<Kind, string>;
+/**
+ * Creates a file path parameter.
+ *
+ * **Details**
+ *
+ * This is a convenience function that creates a path parameter with a
+ * `pathType` set to `"file"` and a default type name of `"file"`.
+ *
+ * **Example** (Creating file parameters)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // Basic file parameter
+ * const outputFile = Param.file(Param.flagKind, "output")
+ *
+ * // File that must exist
+ * const inputFile = Param.file(Param.flagKind, "input", { mustExist: true })
+ *
+ * // Usage: --output result.txt --input existing-file.txt
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const file: <Kind extends ParamKind>(kind: Kind, name: string, options?: {
+    readonly mustExist?: boolean | undefined;
+}) => Param<Kind, string>;
+/**
+ * Creates a redacted parameter for sensitive data like passwords.
+ * The value is masked in help output and logging.
+ *
+ * **Example** (Creating redacted parameters)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // Create a password parameter
+ * const password = Param.redacted(Param.flagKind, "password")
+ *
+ * // Create an API key argument
+ * const apiKey = Param.redacted(Param.argumentKind, "api-key")
+ *
+ * // Usage: --password (value will be hidden in help/logs)
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const redacted: <Kind extends ParamKind>(kind: Kind, name: string) => Param<Kind, Redacted.Redacted<string>>;
+/**
+ * Creates a parameter that reads and returns file content as a string.
+ *
+ * **Example** (Reading file text)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // Read a config file as string
+ * const configContent = Param.fileText(Param.flagKind, "config")
+ *
+ * // Read a template file as argument
+ * const templateContent = Param.fileText(Param.argumentKind, "template")
+ *
+ * // Usage: --config config.txt (reads file content into string)
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const fileText: <Kind extends ParamKind>(kind: Kind, name: string) => Param<Kind, string>;
+/**
+ * Creates a param that reads and parses the content of the specified file.
+ *
+ * **Details**
+ *
+ * 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** (Parsing file contents)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // Will use the extension of the file passed on the command line to determine
+ * // the parser to use
+ * const config = Param.fileParse(Param.flagKind, "config")
+ *
+ * // Will use the JSON parser
+ * const jsonConfig = Param.fileParse(Param.flagKind, "json-config", {
+ *   format: "json"
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const fileParse: <Kind extends ParamKind>(kind: Kind, name: string, options?: Primitive.FileParseOptions | undefined) => Param<Kind, unknown>;
+/**
+ * Creates a parameter that reads and validates file content using a schema.
+ *
+ * **Example** (Validating file contents)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Param } from "effect/unstable/cli"
+ * // Parse JSON config file
+ * const configSchema = Schema.Struct({
+ *   port: Schema.Number,
+ *   host: Schema.String
+ * })
+ *
+ * const config = Param.fileSchema(Param.flagKind, "config", configSchema, {
+ *   format: "json"
+ * })
+ *
+ * // Parse YAML file
+ * const yamlConfig = Param.fileSchema(Param.flagKind, "config", configSchema, {
+ *   format: "yaml"
+ * })
+ *
+ * // Usage: --config config.json (reads and validates file content)
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const fileSchema: <Kind extends ParamKind, A>(kind: Kind, name: string, schema: Schema.ConstraintDecoder<A, Environment>, options?: Primitive.FileSchemaOptions | undefined) => Param<Kind, A>;
+/**
+ * Creates a param that parses key=value pairs.
+ *
+ * **When to use**
+ *
+ * Use when you need command-line options or arguments that collect `key=value`
+ * configuration entries.
+ *
+ * **Details**
+ *
+ * Requires at least one key=value pair. The parsed pairs are merged into a
+ * single record object.
+ *
+ * **Example** (Parsing key-value pairs)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const env = Param.keyValuePair(Param.flagKind, "env")
+ * // --env FOO=bar --env BAZ=qux will parse to { FOO: "bar", BAZ: "qux" }
+ *
+ * const props = Param.keyValuePair(Param.flagKind, "property")
+ * // --property name=value --property debug=true
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const keyValuePair: <Kind extends ParamKind>(kind: Kind, name: string) => Param<Kind, Record<string, string>>;
+/**
+ * Creates an empty sentinel parameter that always fails to parse.
+ *
+ * **When to use**
+ *
+ * Use when you need an empty CLI parameter sentinel for optional parameter
+ * construction or internal combinators.
+ *
+ * **Example** (Creating sentinel parameters)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const disabledDebugParam = Param.none(Param.flagKind)
+ *
+ * const makeDebugParam = (enableDebug: boolean) =>
+ *   enableDebug ? Param.string(Param.flagKind, "debug") : disabledDebugParam
+ *
+ * console.log(makeDebugParam(true) === disabledDebugParam) // false
+ * console.log(makeDebugParam(false) === disabledDebugParam) // true
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const none: <Kind extends ParamKind>(kind: Kind) => Param<Kind, never>;
+/**
+ * Adds an alias to an option.
+ *
+ * **When to use**
+ *
+ * Use when you need a CLI parameter to accept an alternate name, such as "-f"
+ * for "--force".
+ *
+ * **Details**
+ *
+ * This works on any param structure by recursively finding the underlying
+ * `Single` node and applying the alias there.
+ *
+ * **Example** (Adding parameter aliases)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const force = Param.boolean(Param.flagKind, "force").pipe(
+ *   Param.withAlias("-f"),
+ *   Param.withAlias("-F")
+ * )
+ *
+ * // Also works on composed params:
+ * const count = Param.integer(Param.flagKind, "count").pipe(
+ *   Param.optional,
+ *   Param.withAlias("-c") // finds the underlying Single and adds alias
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const withAlias: {
+    /**
+     * Adds an alias to an option.
+     *
+     * **When to use**
+     *
+     * Use when you need a CLI parameter to accept an alternate name, such as "-f"
+     * for "--force".
+     *
+     * **Details**
+     *
+     * This works on any param structure by recursively finding the underlying
+     * `Single` node and applying the alias there.
+     *
+     * **Example** (Adding parameter aliases)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const force = Param.boolean(Param.flagKind, "force").pipe(
+     *   Param.withAlias("-f"),
+     *   Param.withAlias("-F")
+     * )
+     *
+     * // Also works on composed params:
+     * const count = Param.integer(Param.flagKind, "count").pipe(
+     *   Param.optional,
+     *   Param.withAlias("-c") // finds the underlying Single and adds alias
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A>(alias: string): (self: Param<Kind, A>) => Param<Kind, A>;
+    /**
+     * Adds an alias to an option.
+     *
+     * **When to use**
+     *
+     * Use when you need a CLI parameter to accept an alternate name, such as "-f"
+     * for "--force".
+     *
+     * **Details**
+     *
+     * This works on any param structure by recursively finding the underlying
+     * `Single` node and applying the alias there.
+     *
+     * **Example** (Adding parameter aliases)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const force = Param.boolean(Param.flagKind, "force").pipe(
+     *   Param.withAlias("-f"),
+     *   Param.withAlias("-F")
+     * )
+     *
+     * // Also works on composed params:
+     * const count = Param.integer(Param.flagKind, "count").pipe(
+     *   Param.optional,
+     *   Param.withAlias("-c") // finds the underlying Single and adds alias
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A>(self: Param<Kind, A>, alias: string): Param<Kind, A>;
+};
+/**
+ * Adds a description to an option for help text.
+ *
+ * **Details**
+ *
+ * Descriptions provide users with information about what the option does
+ * when they view help documentation.
+ *
+ * **Example** (Adding help descriptions)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const verbose = Param.boolean(Param.flagKind, "verbose").pipe(
+ *   Param.withAlias("-v"),
+ *   Param.withDescription("Enable verbose output")
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const withDescription: {
+    /**
+     * Adds a description to an option for help text.
+     *
+     * **Details**
+     *
+     * Descriptions provide users with information about what the option does
+     * when they view help documentation.
+     *
+     * **Example** (Adding help descriptions)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const verbose = Param.boolean(Param.flagKind, "verbose").pipe(
+     *   Param.withAlias("-v"),
+     *   Param.withDescription("Enable verbose output")
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A>(description: string): (self: Param<Kind, A>) => Param<Kind, A>;
+    /**
+     * Adds a description to an option for help text.
+     *
+     * **Details**
+     *
+     * Descriptions provide users with information about what the option does
+     * when they view help documentation.
+     *
+     * **Example** (Adding help descriptions)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const verbose = Param.boolean(Param.flagKind, "verbose").pipe(
+     *   Param.withAlias("-v"),
+     *   Param.withDescription("Enable verbose output")
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A>(self: Param<Kind, A>, description: string): Param<Kind, A>;
+};
+/**
+ * Hides a parameter from generated help output and completions while keeping
+ * it parseable on the command line.
+ *
+ * **When to use**
+ *
+ * Use when experimental, internal, or deprecated flags should be accepted but
+ * not advertised.
+ *
+ * **Example** (Hiding a flag from help)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const experimental = Param.boolean(Param.flagKind, "experimental-foo").pipe(
+ *   Param.withHidden
+ * )
+ * ```
+ *
+ * @category metadata
+ * @since 4.0.0
+ */
+export declare const withHidden: <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, A>;
+/**
+ * Transforms the parsed value of an option using a mapping function.
+ *
+ * **Example** (Mapping parsed values)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const port = Param.integer(Param.flagKind, "port").pipe(
+ *   Param.map((n) => ({ port: n, url: `http://localhost:${n}` }))
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const map: {
+    /**
+     * Transforms the parsed value of an option using a mapping function.
+     *
+     * **Example** (Mapping parsed values)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const port = Param.integer(Param.flagKind, "port").pipe(
+     *   Param.map((n) => ({ port: n, url: `http://localhost:${n}` }))
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <A, B>(f: (a: A) => B): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>;
+    /**
+     * Transforms the parsed value of an option using a mapping function.
+     *
+     * **Example** (Mapping parsed values)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const port = Param.integer(Param.flagKind, "port").pipe(
+     *   Param.map((n) => ({ port: n, url: `http://localhost:${n}` }))
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, f: (a: A) => B): Param<Kind, B>;
+};
+/**
+ * Transforms the parsed value of an option using an effectful mapping function.
+ *
+ * **Example** (Mapping parsed values effectfully)
+ *
+ * ```ts
+ * import { Effect } from "effect"
+ * import { CliError, Param } from "effect/unstable/cli"
+ *
+ * const validatedEmail = Param.string(Param.flagKind, "email").pipe(
+ *   Param.mapEffect((email) =>
+ *     email.includes("@")
+ *       ? Effect.succeed(email)
+ *       : Effect.fail(
+ *         new CliError.InvalidValue({
+ *           option: "email",
+ *           value: email,
+ *           expected: "valid email format",
+ *           kind: "flag"
+ *         })
+ *       )
+ *   )
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const mapEffect: {
+    /**
+     * Transforms the parsed value of an option using an effectful mapping function.
+     *
+     * **Example** (Mapping parsed values effectfully)
+     *
+     * ```ts
+     * import { Effect } from "effect"
+     * import { CliError, Param } from "effect/unstable/cli"
+     *
+     * const validatedEmail = Param.string(Param.flagKind, "email").pipe(
+     *   Param.mapEffect((email) =>
+     *     email.includes("@")
+     *       ? Effect.succeed(email)
+     *       : Effect.fail(
+     *         new CliError.InvalidValue({
+     *           option: "email",
+     *           value: email,
+     *           expected: "valid email format",
+     *           kind: "flag"
+     *         })
+     *       )
+     *   )
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <A, B>(f: (a: A) => Effect.Effect<B, CliError.CliError, Environment>): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>;
+    /**
+     * Transforms the parsed value of an option using an effectful mapping function.
+     *
+     * **Example** (Mapping parsed values effectfully)
+     *
+     * ```ts
+     * import { Effect } from "effect"
+     * import { CliError, Param } from "effect/unstable/cli"
+     *
+     * const validatedEmail = Param.string(Param.flagKind, "email").pipe(
+     *   Param.mapEffect((email) =>
+     *     email.includes("@")
+     *       ? Effect.succeed(email)
+     *       : Effect.fail(
+     *         new CliError.InvalidValue({
+     *           option: "email",
+     *           value: email,
+     *           expected: "valid email format",
+     *           kind: "flag"
+     *         })
+     *       )
+     *   )
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, f: (a: A) => Effect.Effect<B, CliError.CliError, Environment>): Param<Kind, B>;
+};
+/**
+ * Transforms the parsed value of an option using a function that may throw,
+ * converting any thrown errors into failure messages.
+ *
+ * **Example** (Mapping thrown errors)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const parsedJson = Param.string(Param.flagKind, "config").pipe(
+ *   Param.mapTryCatch(
+ *     (str) => JSON.parse(str),
+ *     (error) =>
+ *       `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
+ *   )
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const mapTryCatch: {
+    /**
+     * Transforms the parsed value of an option using a function that may throw,
+     * converting any thrown errors into failure messages.
+     *
+     * **Example** (Mapping thrown errors)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const parsedJson = Param.string(Param.flagKind, "config").pipe(
+     *   Param.mapTryCatch(
+     *     (str) => JSON.parse(str),
+     *     (error) =>
+     *       `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
+     *   )
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <A, B>(f: (a: A) => B, onError: (error: unknown) => string): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>;
+    /**
+     * Transforms the parsed value of an option using a function that may throw,
+     * converting any thrown errors into failure messages.
+     *
+     * **Example** (Mapping thrown errors)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const parsedJson = Param.string(Param.flagKind, "config").pipe(
+     *   Param.mapTryCatch(
+     *     (str) => JSON.parse(str),
+     *     (error) =>
+     *       `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
+     *   )
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, f: (a: A) => B, onError: (error: unknown) => string): Param<Kind, B>;
+};
+/**
+ * Makes a flag or positional argument optional.
+ *
+ * **Details**
+ *
+ * When the parameter is absent, parsing succeeds with `Option.none()` instead
+ * of failing with a missing option or missing argument error. When present, the
+ * parsed value is wrapped in `Option.some()`.
+ *
+ * **Example** (Making parameters optional)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // Create an optional port option
+ * // - When not provided: returns Option.none()
+ * // - When provided: returns Option.some(parsedValue)
+ * const port = Param.optional(Param.integer(Param.flagKind, "port"))
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const optional: <Kind extends ParamKind, A>(param: Param<Kind, A>) => Param<Kind, Option.Option<A>>;
+/**
+ * Makes a flag or positional argument optional by supplying a fallback value.
+ *
+ * **Details**
+ *
+ * The fallback may be a pure value or an effect. It is used only when the
+ * parameter is absent; provided values are parsed normally.
+ *
+ * **Example** (Providing default values)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // Using the pipe operator to make an option optional
+ * const port = Param.integer(Param.flagKind, "port").pipe(
+ *   Param.withDefault(8080)
+ * )
+ *
+ * // Can also be used with other combinators
+ * const verbose = Param.boolean(Param.flagKind, "verbose").pipe(
+ *   Param.withAlias("-v"),
+ *   Param.withDescription("Enable verbose output"),
+ *   Param.withDefault(false)
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const withDefault: {
+    /**
+     * Makes a flag or positional argument optional by supplying a fallback value.
+     *
+     * **Details**
+     *
+     * The fallback may be a pure value or an effect. It is used only when the
+     * parameter is absent; provided values are parsed normally.
+     *
+     * **Example** (Providing default values)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * // Using the pipe operator to make an option optional
+     * const port = Param.integer(Param.flagKind, "port").pipe(
+     *   Param.withDefault(8080)
+     * )
+     *
+     * // Can also be used with other combinators
+     * const verbose = Param.boolean(Param.flagKind, "verbose").pipe(
+     *   Param.withAlias("-v"),
+     *   Param.withDescription("Enable verbose output"),
+     *   Param.withDefault(false)
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <const B>(defaultValue: B | Effect.Effect<B, CliError.CliError, Environment>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, A | B>;
+    /**
+     * Makes a flag or positional argument optional by supplying a fallback value.
+     *
+     * **Details**
+     *
+     * The fallback may be a pure value or an effect. It is used only when the
+     * parameter is absent; provided values are parsed normally.
+     *
+     * **Example** (Providing default values)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * // Using the pipe operator to make an option optional
+     * const port = Param.integer(Param.flagKind, "port").pipe(
+     *   Param.withDefault(8080)
+     * )
+     *
+     * // Can also be used with other combinators
+     * const verbose = Param.boolean(Param.flagKind, "verbose").pipe(
+     *   Param.withAlias("-v"),
+     *   Param.withDescription("Enable verbose output"),
+     *   Param.withDefault(false)
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A, const B>(self: Param<Kind, A>, defaultValue: B | Effect.Effect<B, CliError.CliError, Environment>): Param<Kind, A | B>;
+};
+/**
+ * Adds a fallback config that is loaded when a required parameter is missing.
+ *
+ * **When to use**
+ *
+ * Use when you need config to provide a fallback source for required flags or
+ * arguments that are absent from CLI input.
+ *
+ * **Details**
+ *
+ * Provided CLI values win. Config is loaded only after a missing option or
+ * missing argument error.
+ *
+ * **Gotchas**
+ *
+ * Missing config preserves the original missing-parameter error. Config parse
+ * failure becomes `CliError.InvalidValue`.
+ *
+ * @see {@link withDefault} for a pure default value
+ * @see {@link withFallbackPrompt} for prompting interactively when input is missing
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const withFallbackConfig: {
+    /**
+     * Adds a fallback config that is loaded when a required parameter is missing.
+     *
+     * **When to use**
+     *
+     * Use when you need config to provide a fallback source for required flags or
+     * arguments that are absent from CLI input.
+     *
+     * **Details**
+     *
+     * Provided CLI values win. Config is loaded only after a missing option or
+     * missing argument error.
+     *
+     * **Gotchas**
+     *
+     * Missing config preserves the original missing-parameter error. Config parse
+     * failure becomes `CliError.InvalidValue`.
+     *
+     * @see {@link withDefault} for a pure default value
+     * @see {@link withFallbackPrompt} for prompting interactively when input is missing
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <B>(config: Config.Config<B>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, A | B>;
+    /**
+     * Adds a fallback config that is loaded when a required parameter is missing.
+     *
+     * **When to use**
+     *
+     * Use when you need config to provide a fallback source for required flags or
+     * arguments that are absent from CLI input.
+     *
+     * **Details**
+     *
+     * Provided CLI values win. Config is loaded only after a missing option or
+     * missing argument error.
+     *
+     * **Gotchas**
+     *
+     * Missing config preserves the original missing-parameter error. Config parse
+     * failure becomes `CliError.InvalidValue`.
+     *
+     * @see {@link withDefault} for a pure default value
+     * @see {@link withFallbackPrompt} for prompting interactively when input is missing
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, config: Config.Config<B>): Param<Kind, A | B>;
+};
+/**
+ * Adds a fallback prompt that is shown when a required parameter is missing.
+ *
+ * **When to use**
+ *
+ * Use when a CLI should ask interactively for a missing required flag or
+ * argument.
+ *
+ * **Details**
+ *
+ * `FallbackPrompt` accepts either a `Prompt` or an effect that builds one.
+ * Effectful prompt creation is lazy and runs only when the fallback is needed.
+ *
+ * **Gotchas**
+ *
+ * This only handles missing options and missing arguments. Invalid values do not
+ * prompt, and prompt cancellation re-fails with the original missing error.
+ *
+ * @see {@link FallbackPrompt} for accepted fallback prompt forms
+ * @see {@link withFallbackConfig} for loading a fallback from config
+ * @see {@link withDefault} for a pure default value
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const withFallbackPrompt: {
+    /**
+     * Adds a fallback prompt that is shown when a required parameter is missing.
+     *
+     * **When to use**
+     *
+     * Use when a CLI should ask interactively for a missing required flag or
+     * argument.
+     *
+     * **Details**
+     *
+     * `FallbackPrompt` accepts either a `Prompt` or an effect that builds one.
+     * Effectful prompt creation is lazy and runs only when the fallback is needed.
+     *
+     * **Gotchas**
+     *
+     * This only handles missing options and missing arguments. Invalid values do not
+     * prompt, and prompt cancellation re-fails with the original missing error.
+     *
+     * @see {@link FallbackPrompt} for accepted fallback prompt forms
+     * @see {@link withFallbackConfig} for loading a fallback from config
+     * @see {@link withDefault} for a pure default value
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <B>(prompt: FallbackPrompt<B>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, A | B>;
+    /**
+     * Adds a fallback prompt that is shown when a required parameter is missing.
+     *
+     * **When to use**
+     *
+     * Use when a CLI should ask interactively for a missing required flag or
+     * argument.
+     *
+     * **Details**
+     *
+     * `FallbackPrompt` accepts either a `Prompt` or an effect that builds one.
+     * Effectful prompt creation is lazy and runs only when the fallback is needed.
+     *
+     * **Gotchas**
+     *
+     * This only handles missing options and missing arguments. Invalid values do not
+     * prompt, and prompt cancellation re-fails with the original missing error.
+     *
+     * @see {@link FallbackPrompt} for accepted fallback prompt forms
+     * @see {@link withFallbackConfig} for loading a fallback from config
+     * @see {@link withDefault} for a pure default value
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, prompt: FallbackPrompt<B>): Param<Kind, A | B>;
+};
+/**
+ * Represent options which can be used to configure variadic parameters.
+ *
+ * @category options
+ * @since 4.0.0
+ */
+export type VariadicParamOptions = {
+    /**
+     * The minimum number of times the parameter can be specified.
+     */
+    readonly min?: number | undefined;
+    /**
+     * The maximum number of times the parameter can be specified.
+     */
+    readonly max?: number | undefined;
+};
+/**
+ * Creates a variadic parameter that can be specified multiple times.
+ *
+ * **Details**
+ *
+ * This is the base combinator for creating parameters that accept multiple values.
+ * The `min` and `max` parameters are optional. When they are not provided, the
+ * parameter can be specified any number of times, from 0 to infinity.
+ *
+ * **Example** (Accepting multiple values)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // Basic variadic parameter (0 to infinity)
+ * const tags = Param.variadic(Param.string(Param.flagKind, "tag"))
+ *
+ * // Variadic with minimum count
+ * const inputs = Param.variadic(
+ *   Param.string(Param.flagKind, "input"),
+ *   { min: 1 } // at least 1 required
+ * )
+ *
+ * // Variadic with both min and max
+ * const limited = Param.variadic(Param.string(Param.flagKind, "item"), {
+ *   min: 2, // at least 2 times
+ *   max: 2 // at most 2 times
+ * })
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const variadic: <Kind extends ParamKind, A>(self: Param<Kind, A>, options?: VariadicParamOptions | undefined) => Param<Kind, ReadonlyArray<A>>;
+/**
+ * Wraps an option to allow it to be specified multiple times within a range.
+ *
+ * **Details**
+ *
+ * This combinator transforms an option to accept between `min` and `max`
+ * occurrences on the command line, returning an array of all provided values.
+ *
+ * **Example** (Bounding repeated values)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // Allow 1-3 file inputs
+ * const files = Param.string(Param.flagKind, "file").pipe(
+ *   Param.between(1, 3),
+ *   Param.withAlias("-f")
+ * )
+ *
+ * // Parse: --file a.txt --file b.txt
+ * // Result: ["a.txt", "b.txt"]
+ *
+ * // Allow 0 or more tags
+ * const tags = Param.string(Param.flagKind, "tag").pipe(
+ *   Param.between(0, Number.MAX_SAFE_INTEGER)
+ * )
+ *
+ * // Parse: --tag dev --tag staging --tag v1.0
+ * // Result: ["dev", "staging", "v1.0"]
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const between: {
+    /**
+     * Wraps an option to allow it to be specified multiple times within a range.
+     *
+     * **Details**
+     *
+     * This combinator transforms an option to accept between `min` and `max`
+     * occurrences on the command line, returning an array of all provided values.
+     *
+     * **Example** (Bounding repeated values)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * // Allow 1-3 file inputs
+     * const files = Param.string(Param.flagKind, "file").pipe(
+     *   Param.between(1, 3),
+     *   Param.withAlias("-f")
+     * )
+     *
+     * // Parse: --file a.txt --file b.txt
+     * // Result: ["a.txt", "b.txt"]
+     *
+     * // Allow 0 or more tags
+     * const tags = Param.string(Param.flagKind, "tag").pipe(
+     *   Param.between(0, Number.MAX_SAFE_INTEGER)
+     * )
+     *
+     * // Parse: --tag dev --tag staging --tag v1.0
+     * // Result: ["dev", "staging", "v1.0"]
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <A>(min: number, max: number): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, ReadonlyArray<A>>;
+    /**
+     * Wraps an option to allow it to be specified multiple times within a range.
+     *
+     * **Details**
+     *
+     * This combinator transforms an option to accept between `min` and `max`
+     * occurrences on the command line, returning an array of all provided values.
+     *
+     * **Example** (Bounding repeated values)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * // Allow 1-3 file inputs
+     * const files = Param.string(Param.flagKind, "file").pipe(
+     *   Param.between(1, 3),
+     *   Param.withAlias("-f")
+     * )
+     *
+     * // Parse: --file a.txt --file b.txt
+     * // Result: ["a.txt", "b.txt"]
+     *
+     * // Allow 0 or more tags
+     * const tags = Param.string(Param.flagKind, "tag").pipe(
+     *   Param.between(0, Number.MAX_SAFE_INTEGER)
+     * )
+     *
+     * // Parse: --tag dev --tag staging --tag v1.0
+     * // Result: ["dev", "staging", "v1.0"]
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A>(self: Param<Kind, A>, min: number, max: number): Param<Kind, ReadonlyArray<A>>;
+};
+/**
+ * Wraps an option to allow it to be specified at most `max` times.
+ *
+ * **Details**
+ *
+ * This combinator transforms an option to accept between 0 and `max`
+ * occurrences on the command line, returning an array of all provided values.
+ *
+ * **Example** (Limiting repeated values)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // Allow at most 3 warning suppressions
+ * const suppressions = Param.string(Param.flagKind, "suppress").pipe(
+ *   Param.atMost(3)
+ * )
+ *
+ * // Parse: --suppress warning1 --suppress warning2
+ * // Result: ["warning1", "warning2"]
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const atMost: {
+    /**
+     * Wraps an option to allow it to be specified at most `max` times.
+     *
+     * **Details**
+     *
+     * This combinator transforms an option to accept between 0 and `max`
+     * occurrences on the command line, returning an array of all provided values.
+     *
+     * **Example** (Limiting repeated values)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * // Allow at most 3 warning suppressions
+     * const suppressions = Param.string(Param.flagKind, "suppress").pipe(
+     *   Param.atMost(3)
+     * )
+     *
+     * // Parse: --suppress warning1 --suppress warning2
+     * // Result: ["warning1", "warning2"]
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <A>(max: number): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, ReadonlyArray<A>>;
+    /**
+     * Wraps an option to allow it to be specified at most `max` times.
+     *
+     * **Details**
+     *
+     * This combinator transforms an option to accept between 0 and `max`
+     * occurrences on the command line, returning an array of all provided values.
+     *
+     * **Example** (Limiting repeated values)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * // Allow at most 3 warning suppressions
+     * const suppressions = Param.string(Param.flagKind, "suppress").pipe(
+     *   Param.atMost(3)
+     * )
+     *
+     * // Parse: --suppress warning1 --suppress warning2
+     * // Result: ["warning1", "warning2"]
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A>(self: Param<Kind, A>, max: number): Param<Kind, ReadonlyArray<A>>;
+};
+/**
+ * Wraps an option to require it to be specified at least `min` times.
+ *
+ * **Details**
+ *
+ * This combinator transforms an option to accept at least `min`
+ * occurrences on the command line, returning an array of all provided values.
+ *
+ * **Example** (Requiring repeated values)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // Require at least 2 input files
+ * const inputs = Param.string(Param.flagKind, "input").pipe(
+ *   Param.atLeast(2),
+ *   Param.withAlias("-i")
+ * )
+ *
+ * // Parse: --input file1.txt --input file2.txt --input file3.txt
+ * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const atLeast: {
+    /**
+     * Wraps an option to require it to be specified at least `min` times.
+     *
+     * **Details**
+     *
+     * This combinator transforms an option to accept at least `min`
+     * occurrences on the command line, returning an array of all provided values.
+     *
+     * **Example** (Requiring repeated values)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * // Require at least 2 input files
+     * const inputs = Param.string(Param.flagKind, "input").pipe(
+     *   Param.atLeast(2),
+     *   Param.withAlias("-i")
+     * )
+     *
+     * // Parse: --input file1.txt --input file2.txt --input file3.txt
+     * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <A>(min: number): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, ReadonlyArray<A>>;
+    /**
+     * Wraps an option to require it to be specified at least `min` times.
+     *
+     * **Details**
+     *
+     * This combinator transforms an option to accept at least `min`
+     * occurrences on the command line, returning an array of all provided values.
+     *
+     * **Example** (Requiring repeated values)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * // Require at least 2 input files
+     * const inputs = Param.string(Param.flagKind, "input").pipe(
+     *   Param.atLeast(2),
+     *   Param.withAlias("-i")
+     * )
+     *
+     * // Parse: --input file1.txt --input file2.txt --input file3.txt
+     * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A>(self: Param<Kind, A>, min: number): Param<Kind, ReadonlyArray<A>>;
+};
+/**
+ * Filters and transforms parsed values, failing with a custom error message
+ * if the filter function returns `Option.none()`.
+ *
+ * **When to use**
+ *
+ * Use when you need validation and transformation in a single parameter
+ * combinator.
+ *
+ * **Example** (Filtering and transforming values)
+ *
+ * ```ts
+ * import { Option } from "effect"
+ * import { Param } from "effect/unstable/cli"
+ * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
+ *   Param.filterMap(
+ *     (n) => n > 0 ? Option.some(n) : Option.none(),
+ *     (n) => `Expected positive integer, got ${n}`
+ *   )
+ * )
+ * ```
+ *
+ * @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 `Option.none()`.
+     *
+     * **When to use**
+     *
+     * Use when you need validation and transformation in a single parameter
+     * combinator.
+     *
+     * **Example** (Filtering and transforming values)
+     *
+     * ```ts
+     * import { Option } from "effect"
+     * import { Param } from "effect/unstable/cli"
+     * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
+     *   Param.filterMap(
+     *     (n) => n > 0 ? Option.some(n) : Option.none(),
+     *     (n) => `Expected positive integer, got ${n}`
+     *   )
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <A, B>(filter: (a: A) => Option.Option<B>, onNone: (a: A) => string): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>;
+    /**
+     * Filters and transforms parsed values, failing with a custom error message
+     * if the filter function returns `Option.none()`.
+     *
+     * **When to use**
+     *
+     * Use when you need validation and transformation in a single parameter
+     * combinator.
+     *
+     * **Example** (Filtering and transforming values)
+     *
+     * ```ts
+     * import { Option } from "effect"
+     * import { Param } from "effect/unstable/cli"
+     * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
+     *   Param.filterMap(
+     *     (n) => n > 0 ? Option.some(n) : Option.none(),
+     *     (n) => `Expected positive integer, got ${n}`
+     *   )
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, filter: (a: A) => Option.Option<B>, onNone: (a: A) => string): Param<Kind, B>;
+};
+/**
+ * Filters parsed values, failing with a custom error message if the predicate returns false.
+ *
+ * **Example** (Filtering parsed values)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const evenNumber = Param.integer(Param.flagKind, "num").pipe(
+ *   Param.filter(
+ *     (n) => n % 2 === 0,
+ *     (n) => `Expected even number, got ${n}`
+ *   )
+ * )
+ * ```
+ *
+ * @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** (Filtering parsed values)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const evenNumber = Param.integer(Param.flagKind, "num").pipe(
+     *   Param.filter(
+     *     (n) => n % 2 === 0,
+     *     (n) => `Expected even number, got ${n}`
+     *   )
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <A>(predicate: Predicate.Predicate<A>, onFalse: (a: A) => string): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, A>;
+    /**
+     * Filters parsed values, failing with a custom error message if the predicate returns false.
+     *
+     * **Example** (Filtering parsed values)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const evenNumber = Param.integer(Param.flagKind, "num").pipe(
+     *   Param.filter(
+     *     (n) => n % 2 === 0,
+     *     (n) => `Expected even number, got ${n}`
+     *   )
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A>(self: Param<Kind, A>, predicate: Predicate.Predicate<A>, onFalse: (a: A) => string): Param<Kind, A>;
+};
+/**
+ * Sets a custom metavar (placeholder name) for the param in help documentation.
+ *
+ * **Details**
+ *
+ * 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** (Setting metavars)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const port = Param.integer(Param.flagKind, "port").pipe(
+ *   Param.withMetavar("PORT"),
+ *   Param.filter(
+ *     (p) => p >= 1 && p <= 65535,
+ *     () => "Port must be between 1 and 65535"
+ *   )
+ * )
+ * ```
+ *
+ * @category metadata
+ * @since 4.0.0
+ */
+export declare const withMetavar: {
+    /**
+     * Sets a custom metavar (placeholder name) for the param in help documentation.
+     *
+     * **Details**
+     *
+     * 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** (Setting metavars)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const port = Param.integer(Param.flagKind, "port").pipe(
+     *   Param.withMetavar("PORT"),
+     *   Param.filter(
+     *     (p) => p >= 1 && p <= 65535,
+     *     () => "Port must be between 1 and 65535"
+     *   )
+     * )
+     * ```
+     *
+     * @category metadata
+     * @since 4.0.0
+     */
+    <K extends ParamKind>(metavar: string): <A>(self: Param<K, A>) => Param<K, A>;
+    /**
+     * Sets a custom metavar (placeholder name) for the param in help documentation.
+     *
+     * **Details**
+     *
+     * 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** (Setting metavars)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const port = Param.integer(Param.flagKind, "port").pipe(
+     *   Param.withMetavar("PORT"),
+     *   Param.filter(
+     *     (p) => p >= 1 && p <= 65535,
+     *     () => "Port must be between 1 and 65535"
+     *   )
+     * )
+     * ```
+     *
+     * @category metadata
+     * @since 4.0.0
+     */
+    <K extends ParamKind, A>(self: Param<K, A>, metavar: string): Param<K, A>;
+};
+/**
+ * Validates parsed values against a Schema, providing detailed error messages.
+ *
+ * **Example** (Validating with schemas)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Param } from "effect/unstable/cli"
+ * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
+ *
+ * const Email = Schema.String.pipe(
+ *   Schema.check(isEmail)
+ * )
+ *
+ * const email = Param.string(Param.flagKind, "email").pipe(
+ *   Param.withSchema(Email)
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const withSchema: {
+    /**
+     * Validates parsed values against a Schema, providing detailed error messages.
+     *
+     * **Example** (Validating with schemas)
+     *
+     * ```ts
+     * import { Schema } from "effect"
+     * import { Param } from "effect/unstable/cli"
+     * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
+     *
+     * const Email = Schema.String.pipe(
+     *   Schema.check(isEmail)
+     * )
+     *
+     * const email = Param.string(Param.flagKind, "email").pipe(
+     *   Param.withSchema(Email)
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <A, B>(schema: Schema.Codec<B, A, Environment, Environment>): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>;
+    /**
+     * Validates parsed values against a Schema, providing detailed error messages.
+     *
+     * **Example** (Validating with schemas)
+     *
+     * ```ts
+     * import { Schema } from "effect"
+     * import { Param } from "effect/unstable/cli"
+     * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
+     *
+     * const Email = Schema.String.pipe(
+     *   Schema.check(isEmail)
+     * )
+     *
+     * const email = Param.string(Param.flagKind, "email").pipe(
+     *   Param.withSchema(Email)
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, schema: Schema.Codec<B, A, Environment, Environment>): Param<Kind, B>;
+};
+/**
+ * Provides a fallback param to use if this param fails to parse.
+ *
+ * **Example** (Falling back to another parameter)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const config = Param.file(Param.flagKind, "config").pipe(
+ *   Param.orElse(() => Param.string(Param.flagKind, "config-url"))
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const orElse: {
+    /**
+     * Provides a fallback param to use if this param fails to parse.
+     *
+     * **Example** (Falling back to another parameter)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const config = Param.file(Param.flagKind, "config").pipe(
+     *   Param.orElse(() => Param.string(Param.flagKind, "config-url"))
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <B, Kind extends ParamKind>(orElse: (error: CliError.CliError) => Param<Kind, B>): <A>(self: Param<Kind, A>) => Param<Kind, A | B>;
+    /**
+     * Provides a fallback param to use if this param fails to parse.
+     *
+     * **Example** (Falling back to another parameter)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const config = Param.file(Param.flagKind, "config").pipe(
+     *   Param.orElse(() => Param.string(Param.flagKind, "config-url"))
+     * )
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: (error: CliError.CliError) => Param<Kind, B>): Param<Kind, A | B>;
+};
+/**
+ * Provides a fallback param and returns a `Result` indicating which param
+ * succeeded.
+ *
+ * **Details**
+ *
+ * The original param's value is returned as `Result.succeed`, while the
+ * fallback param's value is returned as `Result.fail`.
+ *
+ * **Example** (Returning fallback results)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * const configSource = Param.file(Param.flagKind, "config").pipe(
+ *   Param.orElseResult(() => Param.string(Param.flagKind, "config-url"))
+ * )
+ * // Returns Result<string, string>
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export declare const orElseResult: {
+    /**
+     * Provides a fallback param and returns a `Result` indicating which param
+     * succeeded.
+     *
+     * **Details**
+     *
+     * The original param's value is returned as `Result.succeed`, while the
+     * fallback param's value is returned as `Result.fail`.
+     *
+     * **Example** (Returning fallback results)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const configSource = Param.file(Param.flagKind, "config").pipe(
+     *   Param.orElseResult(() => Param.string(Param.flagKind, "config-url"))
+     * )
+     * // Returns Result<string, string>
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, B>(orElse: (error: CliError.CliError) => Param<Kind, B>): <A>(self: Param<Kind, A>) => Param<Kind, Result.Result<A, B>>;
+    /**
+     * Provides a fallback param and returns a `Result` indicating which param
+     * succeeded.
+     *
+     * **Details**
+     *
+     * The original param's value is returned as `Result.succeed`, while the
+     * fallback param's value is returned as `Result.fail`.
+     *
+     * **Example** (Returning fallback results)
+     *
+     * ```ts
+     * import { Param } from "effect/unstable/cli"
+     *
+     * const configSource = Param.file(Param.flagKind, "config").pipe(
+     *   Param.orElseResult(() => Param.string(Param.flagKind, "config-url"))
+     * )
+     * // Returns Result<string, string>
+     * ```
+     *
+     * @category combinators
+     * @since 4.0.0
+     */
+    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: (error: CliError.CliError) => Param<Kind, B>): Param<Kind, Result.Result<A, B>>;
 };
 export {};
 //# sourceMappingURL=Param.d.ts.map