Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

Completions unstable

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

7 exports Since v4.0.0 Source

Constructors

generate

unstable
Since v4.0.0

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, Fish, or PowerShell generation and returns a static script string for executableName.

See

Signature

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

Models

ArgumentDescriptor

interface unstable
Since v4.0.0

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 unstable
Since v4.0.0

Describes the supported argument value shapes.

Signature

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

CommandDescriptor

interface unstable
Since v4.0.0

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 unstable
Since v4.0.0

Describes a command flag for completions.

Signature

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

FlagType

type unstable
Since v4.0.0

Describes the supported flag value shapes.

Signature

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

Shell

type unstable
Since v4.0.0

Shell type used to generate completion scripts.

Signature

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