Param unstable

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.

58 exports Since v4.0.0 Source

Combinators

atLeast

unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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/cli"

const evenNumber = Param.Int(Param.flagKind, "num").pipe(
  Param.filter(
    (n) => n % 2 === 0,
    (n) => `Expected even number, got ${n}`
  )
)
evenNumber.kind // => "flag"

filterMap

unstable

Since v4.0.0

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/cli"
const positiveInt = Param.Int(Param.flagKind, "count").pipe(
  Param.filterMap(
    (n) => n > 0 ? Option.some(n) : Option.none(),
    (n) => `Expected positive integer, got ${n}`
  )
)
positiveInt.kind // => "flag"

map

unstable

Since v4.0.0

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/cli"

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

mapEffect

unstable

Since v4.0.0

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/cli"
import { ChildProcessSpawner } from "effect/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

unstable

Since v4.0.0

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/cli"
import { ChildProcessSpawner } from "effect/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

unstable

Since v4.0.0

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/cli"

// Create an optional port option
// - When not provided: returns Option.none()
// - When provided: returns Option.some(parsedValue)
const port = Param.optional(Param.Int(Param.flagKind, "port"))
port.kind // => "flag"

orElse

unstable

Since v4.0.0

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/cli"

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

orElseResult

unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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/cli"

const force = Param.Boolean(Param.flagKind, "force").pipe(
  Param.withAlias("-f"),
  Param.withAlias("-F")
)

// Also works on composed params:
const count = Param.Int(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

unstable

Since v4.0.0

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/cli"

// Using the pipe operator to make an option optional
const port = Param.Int(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

unstable

Since v4.0.0

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/cli"

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

withFallbackConfig

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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>;
}

withOptionalValue

unstable

Since v4.1.0

Lets a flag be given without a value, in which case value is used.

Details

Follows GNU-style optional values. An explicit value must be attached with = (--watch=until-done), and a bare --watch is parsed as --watch=<value>. The flag never consumes the next token. It is still required unless it is made optional or given a default.

Signature

declare const withOptionalValue: {
  (value: string): <A>(self: Param<"flag", A>) => Param<"flag", A>;
  <A>(self: Param<"flag", A>, value: string): Param<"flag", A>;
}

Example Flag with an optional value

import { Param } from "effect/cli"

const watch = Param.String(Param.flagKind, "watch").pipe(
  Param.withOptionalValue("first-failure"),
  Param.optional
)
watch.kind // => "flag"

withSchema

unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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/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"]

ChoiceWithValue

unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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/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"]

File

unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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/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"]

Finite

unstable

Since v4.0.0

Creates a finite number parameter.

Signature

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

Example Creating finite number parameters

import { Param } from "effect/cli"

const rateFlag = Param.Finite(Param.flagKind, "rate")

const thresholdArg = Param.Finite(Param.argumentKind, "threshold")

const kinds = [rateFlag.kind, thresholdArg.kind] // => ["flag", "argument"]

Int

unstable

Since v4.0.0

Creates an integer parameter.

Signature

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

Example Creating integer parameters

import { Param } from "effect/cli"

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

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

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

KeyValuePair

unstable

Since v4.0.0

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/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"]

Literals

unstable

Since v4.0.0

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

Signature

declare function Literals<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/cli"

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

makeSingle

unstable

Since v4.0.0

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 optionalValue?: string;
  readonly primitiveType: Primitive<A>;
  readonly typeName?: string;
}): Single<Kind, A>

Never

unstable

Since v4.0.0

A parameter that always fails to parse.

Signature

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

Example Creating sentinel parameters

import { Param } from "effect/cli"

const disabledDebugParam = Param.Never(Param.flagKind)

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

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

Path

unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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/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

unstable

Since v4.0.0

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/cli"

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

Param.isParam(maybeParam) // => true

isSingle

unstable

Since v4.0.0

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/cli"

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

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

Metadata

withHidden

unstable

Since v4.0.0

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/cli"

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

withMetavar

unstable

Since v4.0.0

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/cli"

const port = Param.Int(Param.flagKind, "port").pipe(
  Param.withMetavar("PORT"),
  Param.filter(
    (p) => p >= 1 && p <= 65535,
    () => "Port must be between 1 and 65535"
  )
)
port.kind // => "flag"

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: "Transform" | "Single" | "Map" | "Optional" | "Variadic";
  readonly kind: Kind;
  readonly parse: Parse<A>;
}

ParamKind

type unstable

Since v4.0.0

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

Signature

type ParamKind = "argument" | "flag"

Parse

type unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 optionalValue?: string;
  readonly primitiveType: Primitive<A>;
  readonly typeName?: string;
}

Transform

interface unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

Represent options which can be used to configure variadic parameters.

Signature

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

Other

Param

unstable

Since v4.0.0

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

Details

Signature

Example Requiring repeated values

Details

Signature

Example Limiting repeated values

Details

Signature

Example Bounding repeated values

Signature

Example Filtering parsed values

When to use

Signature

Example Filtering and transforming values

Signature

Example Mapping parsed values

Signature

Example Mapping parsed values effectfully

Signature

Example Mapping thrown errors

Details

Signature

Example Making parameters optional

Signature

Example Falling back to another parameter

Details

Signature

Example Returning fallback results

Details

Signature

Example Accepting multiple values

When to use

Details

Signature

Example Adding parameter aliases

Details

Signature

Example Providing default values

Details

Signature

Example Adding help descriptions

When to use

Details

Gotchas

See

Signature

When to use

Details

Gotchas

See

Signature

Details

Signature

Example Flag with an optional value

Signature

Example Validating with schemas

When to use

See

Signature

When to use

See

Signature

Signature

Example Creating boolean parameters

Signature

Example Creating valued choices

Signature

Example Creating date parameters

Details

Signature

Example Creating directory parameters

Details

Signature

Example Creating file parameters

Details

Signature

Example Parsing file contents

Signature

Example Validating file contents

Signature