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

Shell for supported shell names
CommandDescriptor for the command shape used by completion generation

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"