Primitive
Parses raw command-line strings into typed values.
A Primitive<A> receives one string and returns an Effect that either produces an A or fails with a parser message. Argument and Flag build on these primitives to add names, aliases, defaults, prompts, configuration fallbacks, repetition, and help metadata. Primitive parsers cover common scalar values, paths, files, structured config files, schema-decoded input, redacted values, and key-value pairs.
Constructors
Signature
declare const boolean: Primitive<boolean>;Creates a primitive that accepts only specific choice values mapped to custom types.
Signature
declare function choice<A>(choices: readonly Array<readonly [string, A]>): Primitive<A>Creates a primitive that parses Date objects from string input.
Signature
declare const date: Primitive<Date>;Creates a primitive that reads a file and parses its content as structured data.
Details
The parser is selected from options.format when provided, otherwise from the file extension. Supported formats include INI, JSON, TOML, YAML, and YML.
Signature
declare function fileParse(options?: FileParseOptions): Primitive<unknown>;fileSchema
Reads and parses file content using the specified schema.
Signature
declare function fileSchema<A>(
schema: ConstraintDecoder<A, Environment>,
options?: {
readonly errorFormatter?: Formatter<string>;
readonly format?: "json" | "ini" | "toml" | "yaml";
},
): Primitive<A>;Creates a primitive that reads and returns the contents of a file as a string.
Signature
declare const fileText: Primitive<string>;Creates a primitive that parses floating-point numbers from string input.
Signature
declare const float: Primitive<number>;Creates a primitive that parses integer numbers from string input.
Signature
declare const integer: Primitive<number>;keyValuePair
Parses a single key=value pair into a record object.
Signature
declare const keyValuePair: Primitive<Record<string, string>>;Creates a sentinel primitive that always fails to parse a value.
When to use
Use when you need a CLI primitive for flags that do not accept values.
Signature
declare const none: Primitive<never>;Creates a primitive that validates and resolves file system paths.
Signature
declare function path(pathType: PathType, mustExist?: boolean): Primitive<string>;Creates a primitive that wraps string input in Redacted.
Details
The wrapped value is hidden when formatted or inspected, while the original string remains available through the Redacted API when explicitly needed.
Signature
declare const redacted: Primitive<Redacted.Redacted<string>>;Creates a primitive that accepts any string value without validation.
Signature
declare const string: Primitive<string>;Getters
getTypeName
Gets a human-readable type name for a primitive.
When to use
Use when you need the display type name for a Primitive, such as when generating CLI help documentation.
Signature
declare function getTypeName<A>(primitive: Primitive<A>): string;Models
Specifies the type of path validation to perform.
Signature
type PathType = "file" | "directory" | "either";Represents a primitive type that can parse string input into a typed value.
Signature
interface Primitive<out A> extends Variance<A> {
readonly _tag: string;
readonly parse: (value: string) => Effect<A, string, Environment>;
}Options
FileParseOptions type
Represents options which can be provided to methods that deal with parsing file content.
Signature
type FileParseOptions = {
readonly format?: "ini" | "json" | "toml" | "yaml";
};FileSchemaOptions type
Represents options which can be provided to methods that deal with parsing file content and decoding the file content with a Schema.
Signature
type FileSchemaOptions = Struct.Simplify<
FileParseOptions & {
readonly errorFormatter?: Formatter<string>;
}
>;
Creates a primitive that parses boolean values from string input.
Details
Recognizes various forms of true/false values: - True values: "true", "1", "y", "yes", "on" - False values: "false", "0", "n", "no", "off"