GlobalFlag unstable
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
Creates an Action flag that performs a side effect and exits.
Signature
declare const 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 const 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]Global flag discriminated union.
Signature
type GlobalFlag<A> = Action<A> | Setting<any, A>Context passed to action handlers.
Signature
interface HandlerContext { readonly builtIns: readonly Array<Action<boolean> | Action<Option<Shell>> | 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
- 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: readonly [Action<boolean>, Action<boolean>, Action<boolean>, Action<Option.Option<Completions_.Shell>>, Setting<"log-level", Option.Option<LogLevelType>>]Completions
unstableDefines the --completions global flag, which prints a shell completion script for
the given shell.
Details
Accepted values are bash, zsh, fish, powershell, sh, and pwsh;
sh is normalized to bash and pwsh to powershell.
Signature
declare const Completions: Action<Option.Option<Completions_.Shell>>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>