Param

Defines the shared parameter model for CLI arguments and flags.

A Param<Kind, A> describes how to consume parsed command-line input and return a typed value. The Kind decides whether the parameter reads positional arguments or named flags. Argument and Flag build on this module to share parsing structure, primitive constructors, help metadata, aliases, defaults, prompts, configuration fallbacks, validation, schema decoding, fallback parameters, and traversal helpers.

57 exports Added in v4.0.0 Source

Combinators

atLeast

Added in v4.0.0 Source

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.

Signature

declare const atLeast: {
  <A>(min: number): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, readonly Array<A>>;
  <Kind extends ParamKind, A>(self: Param<Kind, A>, min: number): Param<Kind, readonly Array<A>>;
}

Example

(Requiring repeated values)

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"]
inputs.kind // => "flag"

atMost

Added in v4.0.0 Source

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.

Signature

declare const atMost: {
  <A>(max: number): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, readonly Array<A>>;
  <Kind extends ParamKind, A>(self: Param<Kind, A>, max: number): Param<Kind, readonly Array<A>>;
}

Example

(Limiting repeated values)

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"]
suppressions.kind // => "flag"

between

Added in v4.0.0 Source

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.

Signature

declare const between: {
  <A>(min: number, max: number): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, readonly Array<A>>;
  <Kind extends ParamKind, A>(self: Param<Kind, A>, min: number, max: number): Param<Kind, readonly Array<A>>;
}

Example

(Bounding repeated values)

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"]
const kinds = [files.kind, tags.kind] // => ["flag", "flag"]

filter

Added in v4.0.0 Source

Filters parsed values, failing with a custom error message if the predicate returns false.

Signature

declare const filter: {
  <A>(predicate: Predicate<A>, onFalse: (a: A) => string): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, A>;
  <Kind extends ParamKind, A>(self: Param<Kind, A>, predicate: Predicate<A>, onFalse: (a: A) => string): Param<Kind, A>;
}

Example

(Filtering parsed values)

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}`
  )
)
evenNumber.kind // => "flag"

filterMap

Added in v4.0.0 Source

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.

Signature

declare const filterMap: {
  <A, B>(filter: (a: A) => Option<B>, onNone: (a: A) => string): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>;
  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, filter: (a: A) => Option<B>, onNone: (a: A) => string): Param<Kind, B>;
}

Example

(Filtering and transforming values)

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}`
  )
)
positiveInt.kind // => "flag"

map

Added in v4.0.0 Source

Transforms the parsed value of an option using a mapping function.

Signature

declare const map: {
  <A, B>(f: (a: A) => B): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>;
  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, f: (a: A) => B): Param<Kind, B>;
}

Example

(Mapping parsed values)

import { Param } from "effect/unstable/cli"

const port = Param.integer(Param.flagKind, "port").pipe(
  Param.map((n) => ({ port: n, url: `http://localhost:${n}` }))
)
port.kind // => "flag"

mapEffect

Added in v4.0.0 Source

Transforms the parsed value of an option using an effectful mapping function.

Signature

declare const mapEffect: {
  <A, B>(f: (a: A) => Effect<B, CliError, Environment>): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>;
  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, f: (a: A) => Effect<B, CliError, Environment>): Param<Kind, B>;
}

Example

(Mapping parsed values effectfully)

import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
import { CliError, Param } from "effect/unstable/cli"
import { ChildProcessSpawner } from "effect/unstable/process"

const CliTestLayer = Layer.mergeAll(
  FileSystem.layerNoop({}),
  Path.layer,
  Stdio.layerTest({}),
  Layer.succeed(Terminal.Terminal, Terminal.make({
    columns: Effect.succeed(80),
    rows: Effect.succeed(24),
    readInput: Effect.die("unused"),
    readLine: Effect.die("unused"),
    display: () => Effect.void
  })),
  Layer.succeed(
    ChildProcessSpawner.ChildProcessSpawner,
    ChildProcessSpawner.make(() => Effect.die("unused"))
  )
)

const 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"
        })
      )
  )
)

const [, value] = await Effect.runPromise(
  validatedEmail.parse({
    arguments: [],
    flags: { email: ["alice@example.com"] }
  }).pipe(Effect.provide(CliTestLayer))
)
value // => "alice@example.com"

mapTryCatch

Added in v4.0.0 Source

Transforms the parsed value of an option using a function that may throw, converting any thrown errors into failure messages.

Signature

declare const mapTryCatch: {
  <A, B>(f: (a: A) => B, onError: (error: unknown) => string): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>;
  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, f: (a: A) => B, onError: (error: unknown) => string): Param<Kind, B>;
}

Example

(Mapping thrown errors)

import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
import { Param } from "effect/unstable/cli"
import { ChildProcessSpawner } from "effect/unstable/process"

const CliTestLayer = Layer.mergeAll(
  FileSystem.layerNoop({}),
  Path.layer,
  Stdio.layerTest({}),
  Layer.succeed(Terminal.Terminal, Terminal.make({
    columns: Effect.succeed(80),
    rows: Effect.succeed(24),
    readInput: Effect.die("unused"),
    readLine: Effect.die("unused"),
    display: () => Effect.void
  })),
  Layer.succeed(
    ChildProcessSpawner.ChildProcessSpawner,
    ChildProcessSpawner.make(() => Effect.die("unused"))
  )
)

const parsedJson = Param.string(Param.flagKind, "config").pipe(
  Param.mapTryCatch(
    (str) => JSON.parse(str),
    (error) =>
      `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
  )
)

const [, value] = await Effect.runPromise(
  parsedJson.parse({
    arguments: [],
    flags: { config: ['{"enabled":true}'] }
  }).pipe(Effect.provide(CliTestLayer))
)
value // => { enabled: true }

optional

Added in v4.0.0 Source

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().

Signature

declare function optional<Kind extends ParamKind, A>(param: Param<Kind, A>): Param<Kind, Option<A>>

Example

(Making parameters optional)

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"))
port.kind // => "flag"

orElse

Added in v4.0.0 Source

Provides a fallback param to use if this param fails to parse.

Signature

declare const orElse: {
  <B, Kind extends ParamKind>(orElse: LazyArg<Param<Kind, B>>): <A>(self: Param<Kind, A>) => Param<Kind, B | A>;
  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: LazyArg<Param<Kind, B>>): Param<Kind, A | B>;
}

Example

(Falling back to another parameter)

import { Param } from "effect/unstable/cli"

const config = Param.file(Param.flagKind, "config").pipe(
  Param.orElse(() => Param.string(Param.flagKind, "config-url"))
)
config.kind // => "flag"

orElseResult

Added in v4.0.0 Source

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.

Signature

declare const orElseResult: {
  <Kind extends ParamKind, B>(orElse: LazyArg<Param<Kind, B>>): <A>(self: Param<Kind, A>) => Param<Kind, Result<A, B>>;
  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: LazyArg<Param<Kind, B>>): Param<Kind, Result<A, B>>;
}

Example

(Returning fallback results)

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>
configSource.kind // => "flag"

variadic

Added in v4.0.0 Source

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.

Signature

declare function variadic<Kind extends ParamKind, A>(self: Param<Kind, A>, options?: VariadicParamOptions): Param<Kind, readonly Array<A>>

Example

(Accepting multiple values)

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
})
const kinds = [tags.kind, inputs.kind, limited.kind] // => ["flag", "flag", "flag"]

withAlias

Added in v4.0.0 Source

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.

Signature

declare const withAlias: {
  <Kind extends ParamKind, A>(alias: string): (self: Param<Kind, A>) => Param<Kind, A>;
  <Kind extends ParamKind, A>(self: Param<Kind, A>, alias: string): Param<Kind, A>;
}

Example

(Adding parameter aliases)

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
)
const kinds = [force.kind, count.kind] // => ["flag", "flag"]

withDefault

Added in v4.0.0 Source

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.

Signature

declare const withDefault: {
  <B>(defaultValue: B | Effect<B, CliError, Environment>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, B | A>;
  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, defaultValue: B | Effect<B, CliError, Environment>): Param<Kind, A | B>;
}

Example

(Providing default values)

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)
)
const kinds = [port.kind, verbose.kind] // => ["flag", "flag"]

withDescription

Added in v4.0.0 Source

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.

Signature

declare const withDescription: {
  <Kind extends ParamKind, A>(description: string): (self: Param<Kind, A>) => Param<Kind, A>;
  <Kind extends ParamKind, A>(self: Param<Kind, A>, description: string): Param<Kind, A>;
}

Example

(Adding help descriptions)

import { Param } from "effect/unstable/cli"

const verbose = Param.boolean(Param.flagKind, "verbose").pipe(
  Param.withAlias("-v"),
  Param.withDescription("Enable verbose output")
)
verbose.kind // => "flag"

withFallbackConfig

Added in v4.0.0 Source

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

withDefault for a pure default value
withFallbackPrompt for prompting interactively when input is missing

Signature

declare const withFallbackConfig: {
  <B>(config: Config<B>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, B | A>;
  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, config: Config<B>): Param<Kind, A | B>;
}

withFallbackPrompt

Added in v4.0.0 Source

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

FallbackPrompt for accepted fallback prompt forms
withFallbackConfig for loading a fallback from config
withDefault for a pure default value

Signature

declare const withFallbackPrompt: {
  <B>(prompt: FallbackPrompt<B>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, B | A>;
  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, prompt: FallbackPrompt<B>): Param<Kind, A | B>;
}

withSchema

Added in v4.0.0 Source

Validates parsed values against a Schema, providing detailed error messages.

Signature

declare const withSchema: {
  <A, B>(schema: ConstraintCodec<B, A, Environment, unknown>): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>;
  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, schema: ConstraintCodec<B, A, Environment, unknown>): Param<Kind, B>;
}

Example

(Validating with schemas)

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)
)
email.kind // => "flag"

Constants

argumentKind

Added in v4.0.0 Source

Defines the kind discriminator for positional argument parameters.

When to use

Use to build low-level Param constructors or type positions for positional argument parameters.

See

flagKind for the named flag parameter discriminator
ParamKind for the full parameter kind union

Signature

declare const argumentKind: "argument"

flagKind

Added in v4.0.0 Source

Defines the kind discriminator for flag parameters.

When to use

Use to build low-level Param constructors or type positions for named flag parameters.

See

argumentKind for the positional argument parameter discriminator

Signature

declare const flagKind: "flag"

Constructors

boolean

Added in v4.0.0 Source

Creates a boolean parameter.

Signature

declare function boolean<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, boolean>

Example

(Creating boolean parameters)

import { Param } from "effect/unstable/cli"

// 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 (true) or --no-verbose (false).
// The flag is required unless made optional or given a fallback.
// Boolean positional arguments accept true/false.
const kinds = [verboseFlag.kind, enableArg.kind] // => ["flag", "argument"]

choice

Added in v4.0.0 Source

Constructs command-line params that represent a choice between several string inputs.

Signature

declare function choice<Kind extends ParamKind, Choices extends readonly Array<string>>(kind: Kind, name: string, choices: Choices): Param<Kind, Choices[number]>

Example

(Creating string choices)

import { Param } from "effect/unstable/cli"

const logLevel = Param.choice(Param.flagKind, "log-level", [
  "debug",
  "info",
  "warn",
  "error"
])
logLevel.kind // => "flag"

choiceWithValue

Added in v4.0.0 Source

Constructs command-line params that represent a choice between several inputs. The input will be mapped to it's associated value during parsing.

Signature

declare function choiceWithValue<Kind extends ParamKind, Choices extends readonly Array<readonly [string, any]>>(kind: Kind, name: string, choices: Choices): Param<Kind, Choices[number][1]>

Example

(Creating valued choices)

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" }]
])
animal.kind // => "flag"

date

Added in v4.0.0 Source

Creates a date parameter that parses ISO date strings.

Signature

declare function date<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, Date>

Example

(Creating date parameters)

import { Param } from "effect/unstable/cli"

// Create a date flag
const startFlag = Param.date(Param.flagKind, "start-date")

// Create a date argument
const dueDateArg = Param.date(Param.argumentKind, "due-date")

// Usage in CLI: --start-date "2023-12-25" or as positional: "2023-01-01"
// Parses to JavaScript Date object
const kinds = [startFlag.kind, dueDateArg.kind] // => ["flag", "argument"]

Example

(Creating directory parameters)

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
const kinds = [outputDir.kind, sourceDir.kind] // => ["flag", "flag"]

file

Added in v4.0.0 Source

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".

Signature

declare function file<Kind extends ParamKind>(kind: Kind, name: string, options?: {
  readonly mustExist?: boolean;
}): Param<Kind, string>

Example

(Creating file parameters)

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
const kinds = [outputFile.kind, inputFile.kind] // => ["flag", "flag"]

fileParse

Added in v4.0.0 Source

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.

Signature

declare function fileParse<Kind extends ParamKind>(kind: Kind, name: string, options?: FileParseOptions): Param<Kind, unknown>

Example

(Parsing file contents)

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"
})
const kinds = [config.kind, jsonConfig.kind] // => ["flag", "flag"]

fileSchema

Added in v4.0.0 Source

Creates a parameter that reads and validates file content using a schema.

Signature

declare function fileSchema<Kind extends ParamKind, A>(kind: Kind, name: string, schema: ConstraintDecoder<A, Environment>, options?: {
  readonly errorFormatter?: Formatter<string>;
  readonly format?: "json" | "ini" | "toml" | "yaml";
}): Param<Kind, A>

Example

(Validating file contents)

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)
const kinds = [config.kind, yamlConfig.kind] // => ["flag", "flag"]

fileText

Added in v4.0.0 Source

Creates a parameter that reads and returns file content as a string.

Signature

declare function fileText<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, string>

Example

(Reading file text)

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)
const kinds = [configContent.kind, templateContent.kind] // => ["flag", "argument"]

float

Added in v4.0.0 Source

Creates a floating-point number parameter.

Signature

declare function float<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, number>

Example

(Creating float parameters)

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
const kinds = [rateFlag.kind, thresholdArg.kind] // => ["flag", "argument"]

integer

Added in v4.0.0 Source

Creates an integer parameter.

Signature

declare function integer<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, number>

Example

(Creating integer parameters)

import { Param } from "effect/unstable/cli"

// Create an integer flag
const portFlag = Param.integer(Param.flagKind, "port")

// Create an integer argument
const countArg = Param.integer(Param.argumentKind, "count")

// Usage in CLI: --port 8080 or as positional argument: 42
const kinds = [portFlag.kind, countArg.kind] // => ["flag", "argument"]

keyValuePair

Added in v4.0.0 Source

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.

Signature

declare function keyValuePair<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, Record<string, string>>

Example

(Parsing key-value pairs)

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
const kinds = [env.kind, props.kind] // => ["flag", "flag"]

makeSingle

Added in v4.0.0 Source

Constructs a leaf Single parameter from its kind, name, primitive parser, and optional help metadata.

Details

The returned parser reads either one positional argument or the named flag, depending on kind.

Signature

declare function makeSingle<Kind extends ParamKind, A>(params: {
  readonly aliases?: readonly Array<string>;
  readonly description?: Option<string>;
  readonly hidden?: boolean;
  readonly kind: Kind;
  readonly name: string;
  readonly primitiveType: Primitive<A>;
  readonly typeName?: string;
}): Single<Kind, A>

none

Added in v4.0.0 Source

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.

Signature

declare function none<Kind extends ParamKind>(kind: Kind): Param<Kind, never>

Example

(Creating sentinel parameters)

import { Param } from "effect/unstable/cli"

const disabledDebugParam = Param.none(Param.flagKind)

const makeDebugParam = (enableDebug: boolean) =>
  enableDebug ? Param.string(Param.flagKind, "debug") : disabledDebugParam

makeDebugParam(true) === disabledDebugParam // => false
makeDebugParam(false) === disabledDebugParam // => true

path

Added in v4.0.0 Source

Creates a path parameter that accepts file or directory paths.

Signature

declare function path<Kind extends ParamKind>(kind: Kind, name: string, options?: {
  readonly mustExist?: boolean;
  readonly pathType?: PathType;
  readonly typeName?: string;
}): Param<Kind, string>

Example

(Creating path parameters)

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"
})
const kinds = [outputPath.kind, inputPath.kind, configFile.kind] // => ["flag", "flag", "flag"]

redacted

Added in v4.0.0 Source

Creates a redacted parameter for sensitive data like passwords. The value is masked in help output and logging.

Signature

declare function redacted<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, Redacted<string>>

Example

(Creating redacted parameters)

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)
const kinds = [password.kind, apiKey.kind] // => ["flag", "argument"]

string

Added in v4.0.0 Source

Creates a string parameter.

Signature

declare function string<Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, string>

Example

(Creating string parameters)

import { Param } from "effect/unstable/cli"

// 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
const kinds = [nameFlag.kind, fileArg.kind] // => ["flag", "argument"]

Guards

isParam

Added in v4.0.0 Source

Type guard to check if a value is a Param.

Signature

declare function isParam(u: unknown): u is Param<any, ParamKind>

Example

(Checking for params)

import { Param } from "effect/unstable/cli"

const maybeParam = Param.string(Param.flagKind, "name")

Param.isParam(maybeParam) // => true

isSingle

Added in v4.0.0 Source

Type guard to check if a param is a Single param (not composed).

Signature

declare function isSingle<Kind extends ParamKind, A>(param: Param<Kind, A>): param is Single<Kind, A>

Example

(Checking for single params)

import { Param } from "effect/unstable/cli"

const nameParam = Param.string(Param.flagKind, "name")
const optionalParam = Param.optional(nameParam)

Param.isSingle(nameParam) // => true
Param.isSingle(optionalParam) // => false

Metadata

withHidden

Added in v4.0.0 Source

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.

Signature

declare function withHidden<Kind extends ParamKind, A>(self: Param<Kind, A>): Param<Kind, A>

Example

(Hiding a flag from help)

import { Param } from "effect/unstable/cli"

const experimental = Param.boolean(Param.flagKind, "experimental-foo").pipe(
  Param.withHidden
)
experimental.kind // => "flag"

withMetavar

Added in v4.0.0 Source

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.

Signature

declare const withMetavar: {
  <K extends ParamKind>(metavar: string): <A>(self: Param<K, A>) => Param<K, A>;
  <K extends ParamKind, A>(self: Param<K, A>, metavar: string): Param<K, A>;
}

Example

(Setting metavars)

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"
  )
)
port.kind // => "flag"

interface Optional<Kind extends ParamKind, A> extends Param<Kind, Option.Option<A>> {
  readonly _tag: "Optional";
  readonly kind: Kind;
  readonly param: Param<Kind, A>;
}

Param interface

Added in v4.0.0 Source

Polymorphic CLI parameter shared by Argument and Flag.

Details

A parameter knows whether it consumes positional arguments or flags and parses a ParsedArgs value into its typed result.

Signature

interface Param<Kind extends ParamKind, out A> extends Variance<A> {
  readonly _tag: "Single" | "Map" | "Transform" | "Optional" | "Variadic";
  readonly kind: Kind;
  readonly parse: Parse<A>;
}

ParamKind type

Added in v4.0.0 Source

Discriminator for whether a Param parses positional arguments or command-line flags.

Signature

type ParamKind = "argument" | "flag"

Parse type

Added in v4.0.0 Source

Function type used by parameters to parse currently available flags and positional arguments.

Details

It returns the remaining positional arguments together with the parsed value, or fails with a CliError while requiring the CLI parsing environment.

Signature

type Parse<A> = (args: ParsedArgs) => Effect.Effect<readonly [leftover: ReadonlyArray<string>, value: A], CliError.CliError, Environment>

ParsedArgs interface

Added in v4.0.0 Source

Input context passed to Param.parse implementations.

flags: already-collected flag values by canonical flag name
arguments: remaining positional arguments to be consumed

Signature

interface ParsedArgs {
  readonly arguments: readonly Array<string>;
  readonly flags: Flags;
}

Single interface

Added in v4.0.0 Source

Leaf parameter that reads one named argument or flag with a primitive parser.

Details

Single parameters carry the user-facing name, aliases, description, primitive type, and optional metavar/type name used in help output.

Signature

interface Single<Kind extends ParamKind, out A> extends Param<Kind, A> {
  readonly _tag: "Single";
  readonly aliases: readonly Array<string>;
  readonly description: Option<string>;
  readonly hidden: boolean;
  readonly kind: Kind;
  readonly name: string;
  readonly primitiveType: Primitive<A>;
  readonly typeName?: string;
}

Transform interface

Added in v4.0.0 Source

Parameter node that rewrites another parameter's parser, allowing effectful validation, fallback behavior, or error translation while preserving the same parameter kind.

Signature

interface Transform<Kind extends ParamKind, in out A, out B> extends Param<Kind, B> {
  readonly _tag: "Transform";
  readonly alternatives: readonly Array<LazyArg<Param<Kind, unknown>>>;
  readonly f: (parse: Parse<A>, alternatives: readonly Array<LazyArg<Parse<unknown>>>) => Parse<B>;
  readonly kind: Kind;
  readonly param: Param<Kind, A>;
}

Variadic interface

Added in v4.0.0 Source

Parameter node that parses another parameter zero or more times and returns all parsed values as an array, respecting optional minimum and maximum occurrence bounds.

Signature

interface Variadic<Kind extends ParamKind, A> extends Param<Kind, ReadonlyArray<A>> {
  readonly _tag: "Variadic";
  readonly kind: Kind;
  readonly max: Option<number>;
  readonly min: Option<number>;
  readonly param: Param<Kind, A>;
}

Options

VariadicParamOptions type

Added in v4.0.0 Source

Represent options which can be used to configure variadic parameters.

Signature

type VariadicParamOptions = {
  readonly max?: number;
  readonly min?: number;
}

Other

Param

Added in v4.0.0 Source

Namespace containing type-level utilities attached to the Param interface.