Skip to content

CliError

Defines structured errors for the unstable CLI parser and runner.

CLI errors describe problems such as unknown or duplicate flags, missing flags or arguments, unexpected positional arguments, invalid values, unknown subcommands, user handler failures, and requests to show command help. This module includes the CliError union, the isCliError guard, schema-backed error classes with display messages, and the NonShowHelpErrors union used when parse or validation errors should be shown with help output.

13 exports Added in v4.0.0 Source

Errors

CliError type

Added in v4.0.0 Source

Union type representing all possible CLI error conditions.

Signature

type CliError =
  | UnrecognizedOption
  | DuplicateOption
  | MissingOption
  | MissingArgument
  | UnexpectedArgument
  | InvalidValue
  | UnknownSubcommand
  | ShowHelp
  | UserError;

DuplicateOption

Added in v4.0.0 Source

Error thrown when duplicate option names are detected between parent and child commands.

Signature

declare class DuplicateOption extends {
  readonly _tag: "DuplicateOption";
  readonly childCommand: string;
  readonly option: string;
  readonly parentCommand: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "DuplicateOption";
    readonly childCommand: string;
    readonly option: string;
    readonly parentCommand: string;
  }, options?: MakeOptions]);
  readonly "~effect/cli/CliError": "~effect/cli/CliError";
  message: string;
}

InvalidValue

Added in v4.0.0 Source

Error thrown when an option or argument value is invalid.

Signature

declare class InvalidValue extends {
  readonly _tag: "InvalidValue";
  readonly expected: string;
  readonly kind: "flag" | "argument";
  readonly option: string;
  readonly value: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "InvalidValue";
    readonly expected: string;
    readonly kind: "flag" | "argument";
    readonly option: string;
    readonly value: string;
  }, options?: MakeOptions]);
  readonly "~effect/cli/CliError": "~effect/cli/CliError";
  message: string;
}

MissingArgument

Added in v4.0.0 Source

Error thrown when a required positional argument is missing.

Signature

declare class MissingArgument extends {
  readonly _tag: "MissingArgument";
  readonly argument: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "MissingArgument";
    readonly argument: string;
  }, options?: MakeOptions]);
  readonly "~effect/cli/CliError": "~effect/cli/CliError";
  message: string;
}

MissingOption

Added in v4.0.0 Source

Error thrown when a required option is missing.

Signature

declare class MissingOption extends {
  readonly _tag: "MissingOption";
  readonly option: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "MissingOption";
    readonly option: string;
  }, options?: MakeOptions]);
  readonly "~effect/cli/CliError": "~effect/cli/CliError";
  message: string;
}

NonShowHelpErrors type

Added in v4.0.0 Source

Type of CLI errors that are not ShowHelp.

Details

These errors can be accumulated and attached to ShowHelp.errors when the runner should display help along with the underlying parse or validation failures.

Signature

type NonShowHelpErrors = typeof NonShowHelpErrors.Type;

ShowHelp

Added in v4.0.0 Source

Error data requesting CLI help rendering for a command path.

Details

It is used for explicit help requests and for parse or validation failures that should be shown with help text. When errors is non-empty, the runtime exit code is 1; otherwise it is 0.

Signature

declare class ShowHelp extends {
  readonly _tag: "ShowHelp";
  readonly commandPath: readonly Array<string>;
  readonly errors: readonly Array<UnrecognizedOption | DuplicateOption | MissingOption | MissingArgument | UnexpectedArgument | InvalidValue | UnknownSubcommand | UserError>;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "ShowHelp";
    readonly commandPath: readonly Array<string>;
    readonly errors: readonly Array<UnrecognizedOption | DuplicateOption | MissingOption | MissingArgument | UnexpectedArgument | InvalidValue | UnknownSubcommand | UserError>;
  }, options?: MakeOptions]);
  readonly "~effect/cli/CliError": "~effect/cli/CliError";
  readonly "~effect/Runtime/errorExitCode": 0 | 1;
  readonly "~effect/Runtime/errorReported": false;
  message: string;
}

UnexpectedArgument

Added in v4.0.0 Source

Error thrown when positional arguments remain after a command has parsed all of its parameters.

Signature

declare class UnexpectedArgument extends {
  readonly _tag: "UnexpectedArgument";
  readonly arguments: readonly Array<string>;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "UnexpectedArgument";
    readonly arguments: readonly Array<string>;
  }, options?: MakeOptions]);
  readonly "~effect/cli/CliError": "~effect/cli/CliError";
  message: string;
}

UnknownSubcommand

Added in v4.0.0 Source

Error thrown when an unknown subcommand is encountered.

Signature

declare class UnknownSubcommand extends {
  readonly _tag: "UnknownSubcommand";
  readonly parent?: readonly Array<string>;
  readonly subcommand: string;
  readonly suggestions: readonly Array<string>;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "UnknownSubcommand";
    readonly parent?: readonly Array<string>;
    readonly subcommand: string;
    readonly suggestions: readonly Array<string>;
  }, options?: MakeOptions]);
  readonly "~effect/cli/CliError": "~effect/cli/CliError";
  message: string;
}

UnrecognizedOption

Added in v4.0.0 Source

Error thrown when an unrecognized option is encountered.

Signature

declare class UnrecognizedOption extends {
  readonly _tag: "UnrecognizedOption";
  readonly command?: readonly Array<string>;
  readonly option: string;
  readonly suggestions: readonly Array<string>;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "UnrecognizedOption";
    readonly command?: readonly Array<string>;
    readonly option: string;
    readonly suggestions: readonly Array<string>;
  }, options?: MakeOptions]);
  readonly "~effect/cli/CliError": "~effect/cli/CliError";
  message: string;
}

UserError

Added in v4.0.0 Source

Error wrapper for user handler failures in the CLI error channel.

Signature

declare class UserError extends {
  readonly _tag: "UserError";
  readonly cause: unknown;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "UserError";
    readonly cause: unknown;
  }, options?: MakeOptions]);
  readonly "~effect/cli/CliError": "~effect/cli/CliError";
}

Guards

isCliError

Added in v4.0.0 Source

Type guard to check if a value is a CLI error.

Signature

declare function isCliError(u: unknown): u is CliError;

Schemas

NonShowHelpErrors

Added in v4.0.0 Source

Schema for concrete CLI errors that can be reported together with help output.

Details

This excludes ShowHelp itself, allowing parse and validation errors to be stored in ShowHelp.errors without nesting another help-control value.

Signature

declare const NonShowHelpErrors: Schema.Union<
  readonly [
    typeof UnrecognizedOption,
    typeof DuplicateOption,
    typeof MissingOption,
    typeof MissingArgument,
    typeof UnexpectedArgument,
    typeof InvalidValue,
    typeof UnknownSubcommand,
    typeof UserError,
  ]
>;