GlobalFlag
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, wizard, shell-completion, and log-level flags used by Command.run and Command.runWith.
Constructors
Signature
declare function action<A>(options: {
readonly flag: Flag<A>;
readonly run: (value: A, context: HandlerContext) => Effect<void>;
}): Action<A>;Creates a Setting flag that configures the command handler's environment.
Signature
declare function setting<Id extends string>(
id: Id,
): <A>(options: { readonly flag: Flag<A> }) => Setting<Id, A>;Models
Action flag: side effect + exit (--help, --version, --completions).
Signature
interface Action<A> {
readonly _tag: "Action";
readonly flag: Flag<A>;
readonly run: (value: A, context: HandlerContext) => Effect<void>;
}Global flag included in the default command-runner configuration.
Signature
type BuiltIn = (typeof BuiltIns)[number];GlobalFlag type
Global flag discriminated union.
Signature
type GlobalFlag<A> = Action<A> | Setting<any, A>;HandlerContext interface
Context passed to action handlers.
Signature
interface HandlerContext {
readonly builtIns: readonly Array<Action<boolean> | Action<Option<"bash" | "zsh" | "fish">> | Setting<"log-level", Option<LogLevel>>>;
readonly command: Any;
readonly commandPath: readonly Array<string>;
readonly version: string;
}Other
References
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, Wizard, 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
Helpfor the help action flagVersionfor the version action flagCompletionsfor the shell-completions action flagLogLevelfor the built-in log-level setting flag
Signature
declare const BuiltIns: readonly [
Action<boolean>,
Action<boolean>,
Action<boolean>,
Action<Option.Option<"bash" | "zsh" | "fish">>,
Setting<"log-level", Option.Option<LogLevelType>>,
];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">>;Defines the --help / -h global flag, which shows help documentation for the active command path.
See
Signature
declare const Help: Action<boolean>;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>>;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>;Defines the global action flag for starting interactive wizard mode.
Details
Command.run and Command.runWith handle this action specially so the generated arguments can be passed back through the command parser.
Signature
declare const Wizard: Action<boolean>;
Creates an Action flag that performs a side effect and exits.