Skip to content

Completions

The Completions module turns a plain description of an Effect CLI command tree into shell completion scripts for Bash, Zsh, and Fish. It is the low-level script generation surface used by the unstable CLI package and by the built-in completions global flag.

7 exports Added in v4.0.0 Source

Constructors

generate

Added in v4.0.0 Source

Generates a shell completion script for a command descriptor.

When to use

Use when you need an installable completion script from an existing CommandDescriptor.

Details

Dispatches by shell to Bash, Zsh, or Fish generation and returns a static script string for executableName.

See

Signature

declare function generate(
  executableName: string,
  shell: Shell,
  descriptor: CommandDescriptor,
): string;

Models

ArgumentDescriptor interface

Added in v4.0.0 Source

Describes a positional argument for completions.

Signature

interface ArgumentDescriptor {
  readonly description: string | undefined;
  readonly name: string;
  readonly required: boolean;
  readonly type: ArgumentType;
  readonly variadic: boolean;
}

ArgumentType type

Added in v4.0.0 Source

Describes the supported argument value shapes.

Signature

type ArgumentType =
  | {
      readonly _tag: "String";
    }
  | {
      readonly _tag: "Integer";
    }
  | {
      readonly _tag: "Float";
    }
  | {
      readonly _tag: "Date";
    }
  | {
      readonly _tag: "Choice";
      readonly values: ReadonlyArray<string>;
    }
  | {
      readonly _tag: "Path";
      readonly pathType: "file" | "directory" | "either";
    };

CommandDescriptor interface

Added in v4.0.0 Source

Describes a command for completion script generation.

Signature

interface CommandDescriptor {
  readonly arguments: readonly Array<ArgumentDescriptor>;
  readonly description: string | undefined;
  readonly flags: readonly Array<FlagDescriptor>;
  readonly name: string;
  readonly subcommands: readonly Array<CommandDescriptor>;
}

FlagDescriptor interface

Added in v4.0.0 Source

Describes a command flag for completions.

Signature

interface FlagDescriptor {
  readonly aliases: readonly Array<string>;
  readonly description: string | undefined;
  readonly name: string;
  readonly type: FlagType;
}

FlagType type

Added in v4.0.0 Source

Describes the supported flag value shapes.

Signature

type FlagType =
  | {
      readonly _tag: "Boolean";
    }
  | {
      readonly _tag: "String";
    }
  | {
      readonly _tag: "Integer";
    }
  | {
      readonly _tag: "Float";
    }
  | {
      readonly _tag: "Date";
    }
  | {
      readonly _tag: "Choice";
      readonly values: ReadonlyArray<string>;
    }
  | {
      readonly _tag: "Path";
      readonly pathType: "file" | "directory" | "either";
    };

Shell type

Added in v4.0.0 Source

Shell type used to generate completion scripts.

Signature

type Shell = "bash" | "zsh" | "fish";