GlobalFlag.ts

GlobalFlag.ts overview

Global flags for Effect CLI command trees. Global flags are parsed outside a single command’s local flags and can apply to a command and its descendants.

This module defines two kinds of global flags: action flags, which run an effect and stop normal command execution, and setting flags, which provide a parsed value to the command handler through the Effect context. It also defines the built-in help, version, shell-completion, and log-level flags used by Command.run and Command.runWith.

Since v4.0.0

---

Exports Grouped by Category

• constructors
  • action
  • setting
• models
  • Action (interface)
  • BuiltInSettingContext (type alias)
  • GlobalFlag (type alias)
  • HandlerContext (interface)
  • Setting (interface)
• references
  • BuiltIns
  • Completions
  • Help
  • LogLevel
  • Version
• utils
  • Setting (namespace)
    • Identifier (type alias)

---

constructors

action

Creates an Action flag that performs a side effect and exits.

Signature

declare const action: <A>(options: {
  readonly flag: Flag.Flag<A>
  readonly run: (value: A, context: HandlerContext) => Effect.Effect<void>
}) => Action<A>

Source

Since v4.0.0

setting

Creates a Setting flag that configures the command handler’s environment.

Signature

declare const setting: <const Id extends string>(
  id: Id
) => <A>(options: { readonly flag: Flag.Flag<A> }) => Setting<Id, A>

Source

Since v4.0.0

models

Action (interface)

Action flag: side effect + exit (–help, –version, –completions).

Signature

export interface Action<A> {
  readonly _tag: "Action"
  readonly flag: Flag.Flag<A>
  readonly run: (value: A, context: HandlerContext) => Effect.Effect<void>
}

Source

Since v4.0.0

BuiltInSettingContext (type alias)

Built-in setting context identifiers.

Signature

type BuiltInSettingContext = Setting.Identifier<"log-level">

Source

Since v4.0.0

GlobalFlag (type alias)

Global flag discriminated union.

Signature

type GlobalFlag<A> = Action<A> | Setting<any, A>

Source

Since v4.0.0

HandlerContext (interface)

Context passed to action handlers.

Signature

export interface HandlerContext {
  readonly command: Command.Command.Any
  readonly commandPath: ReadonlyArray<string>
  readonly version: string
}

Source

Since v4.0.0

Setting (interface)

Setting flag: configure command handler’s environment (–log-level, –config).

Signature

export interface Setting<Id extends string, A> extends Context.Service<Setting.Identifier<Id>, A> {
  readonly _tag: "Setting"
  readonly id: Id
  readonly flag: Flag.Flag<A>
}

Source

Since v4.0.0

references

BuiltIns

Built-in global flags in default precedence order.

When to use

Use when extending or inspecting the default global-flag set that Command.runWith prepends before user-defined global flags.

Details

The built-ins are Help, Version, Completions, and LogLevel. Command.runWith prepends these built-ins when collecting and parsing global flags.

Gotchas

Action flags are processed in active flag order and the first present action exits, so this array controls built-in action precedence.

See

• Help for the help action flag
• Version for the version action flag
• Completions for the shell-completions action flag
• LogLevel for the built-in log-level setting flag

Signature

declare const BuiltIns: ReadonlyArray<GlobalFlag<any>>

Source

Since v4.0.0

Completions

Defines the --completions global flag, which prints a shell completion script for the given shell.

Details

Accepted values are bash, zsh, fish, and sh; sh is normalized to bash.

Signature

declare const Completions: Action<Option.Option<"bash" | "zsh" | "fish">>

Source

Since v4.0.0

Help

Defines the --help / -h global flag, which shows help documentation for the active command path.

See

• BuiltIns for the default list containing this flag
• action for defining custom action global flags

Signature

declare const Help: Action<boolean>

Source

Since v4.0.0

LogLevel

Defines the global setting flag for command log level.

When to use

Use to add a built-in --log-level option that configures the minimum log level for the command.

Signature

declare const LogLevel: Setting<"log-level", Option.Option<LogLevelType>>

Source

Since v4.0.0

Version

Defines the global action flag for showing command version information.

When to use

Use to add a built-in --version / -v flag to a command runner.

Signature

declare const Version: Action<boolean>

Source

Since v4.0.0

utils

Setting (namespace)

Namespace containing type helpers for global setting flags.

Source

Since v4.0.0

Identifier (type alias)

Type-level service identifier used by Setting global flags for the parsed value associated with a setting id.

Signature

type`effect/unstable/cli/GlobalFlag/${Id}` = `effect/unstable/cli/GlobalFlag/${Id}`

Source

Since v4.0.0