Skip to content
// EFFECT DAYS 2026

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.

8 exports Since v4.0.0 Source

Constructors

fromCommand

unstable
Since v4.0.7

Converts a command tree into a CommandDescriptor for completion script generation.

When to use

Use when you need to generate a completion script from an existing Command, for example in a build step, without running the CLI or capturing the output of the built-in --completions flag.

Details

Reads the command's flags, arguments, and subcommands, including flags shared with subcommands and aliases. Hidden flags and unlisted subcommands are omitted, matching --help. Command handlers are never run.

See

  • generate for turning the descriptor into a shell script

Signature

declare function fromCommand(command: Any): CommandDescriptor

Example Generating a Zsh completion script at build time 

import { Effect } from "effect"
import { Command, Completions, Flag } from "effect/cli"


const start = Command.make(
  "start",
  { port: Flag.Int("port") },
  ({ port }) => Effect.log(`Listening on ${port}`)
)


const cli = Command.make("server").pipe(
  Command.withSubcommands([start])
)


const script = Completions.generate(
  "server",
  "zsh",
  Completions.fromCommand(cli)
)


script.startsWith("#compdef server") // => true

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 negation?: string | false;
  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"