effect 4.0.4 → 4.0.6

package/src/cli/Command.ts

@@ -30,10 +30,10 @@ import * as Terminal from "../Terminal.ts"
 import type { Contravariant, Covariant, NoInfer, Simplify } from "../Types.ts"
 import * as CliConfig from "./CliConfig.ts"
 import * as CliError from "./CliError.ts"
-import * as CliOutput from "./CliOutput.ts"
 import * as GlobalFlag from "./GlobalFlag.ts"
 import { checkForDuplicateFlags, makeCommand, makeParser, toImpl, TypeId } from "./internal/command.ts"
 import { mergeConfig, parseConfig } from "./internal/config.ts"
+import { resolveFormatter } from "./internal/formatter.ts"
 import { getGlobalFlagsForCommandPath, getGlobalFlagsForCommandTree, getHelpForCommandPath } from "./internal/help.ts"
 import * as Lexer from "./internal/lexer.ts"
 import * as Parser from "./internal/parser.ts"
@@ -1121,6 +1121,247 @@ export const withHandler: {
 ): Command<Name, A, ContextInput, E, Exclude<R, BuiltInSettingContext>> =>
   makeCommand({ ...toImpl(self), handle: handler } as any))
 
+/**
+ * Validates the parsed input of a command before the handler runs.
+ *
+ * **Details**
+ *
+ * Use this for rules that involve several flags or arguments, such as
+ * mutually exclusive flags. The validation receives the same input as the
+ * handler, with defaults, prompts and the wizard already applied. A failure
+ * is shown with the command help, like a parse error, and the handler does
+ * not run. Fail with `CliError.ValidationError` to supply the message, or
+ * with any other `CliError`. Validations run in the order they were added and
+ * stop at the first failure. Adding a handler later with `withHandler` keeps
+ * them.
+ *
+ * A validation sees only the input that exists where it is applied. Add it
+ * after `withSharedFlags` to see the shared flags. Added after
+ * `withSubcommands`, it also runs when a subcommand is selected, with the
+ * parent's shared flags as input.
+ *
+ * **Example** (Rejecting mutually exclusive flags)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
+ * import { CliError, Command, Flag } from "effect/cli"
+ * import { ChildProcessSpawner } from "effect/process"
+ * import { TestConsole } from "effect/testing"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   TestConsole.layer,
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
+ *
+ * const download = Command.make("download", {
+ *   useApi: Flag.Boolean("use-api").pipe(Flag.withDefault(false)),
+ *   useDocker: Flag.Boolean("use-docker").pipe(Flag.withDefault(false))
+ * }, () => Effect.void).pipe(
+ *   Command.validate(({ useApi, useDocker }) =>
+ *     useApi && useDocker
+ *       ? Effect.fail(
+ *         new CliError.ValidationError({
+ *           message: "--use-api and --use-docker are mutually exclusive"
+ *         })
+ *       )
+ *       : Effect.void
+ *   )
+ * )
+ *
+ * const error = await Effect.runPromise(
+ *   Command.runWith(download, { version: "1.0.0" })(["--use-api", "--use-docker"]).pipe(
+ *     Effect.flip,
+ *     Effect.provide(CliTestLayer)
+ *   )
+ * )
+ * error._tag // => "ShowHelp"
+ * error.errors[0].message // => "--use-api and --use-docker are mutually exclusive"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const validate: {
+  /**
+   * Validates the parsed input of a command before the handler runs.
+   *
+   * **Details**
+   *
+   * Use this for rules that involve several flags or arguments, such as
+   * mutually exclusive flags. The validation receives the same input as the
+   * handler, with defaults, prompts and the wizard already applied. A failure
+   * is shown with the command help, like a parse error, and the handler does
+   * not run. Fail with `CliError.ValidationError` to supply the message, or
+   * with any other `CliError`. Validations run in the order they were added and
+   * stop at the first failure. Adding a handler later with `withHandler` keeps
+   * them.
+   *
+   * A validation sees only the input that exists where it is applied. Add it
+   * after `withSharedFlags` to see the shared flags. Added after
+   * `withSubcommands`, it also runs when a subcommand is selected, with the
+   * parent's shared flags as input.
+   *
+   * **Example** (Rejecting mutually exclusive flags)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
+   * import { CliError, Command, Flag } from "effect/cli"
+   * import { ChildProcessSpawner } from "effect/process"
+   * import { TestConsole } from "effect/testing"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   TestConsole.layer,
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
+   *
+   * const download = Command.make("download", {
+   *   useApi: Flag.Boolean("use-api").pipe(Flag.withDefault(false)),
+   *   useDocker: Flag.Boolean("use-docker").pipe(Flag.withDefault(false))
+   * }, () => Effect.void).pipe(
+   *   Command.validate(({ useApi, useDocker }) =>
+   *     useApi && useDocker
+   *       ? Effect.fail(
+   *         new CliError.ValidationError({
+   *           message: "--use-api and --use-docker are mutually exclusive"
+   *         })
+   *       )
+   *       : Effect.void
+   *   )
+   * )
+   *
+   * const error = await Effect.runPromise(
+   *   Command.runWith(download, { version: "1.0.0" })(["--use-api", "--use-docker"]).pipe(
+   *     Effect.flip,
+   *     Effect.provide(CliTestLayer)
+   *   )
+   * )
+   * error._tag // => "ShowHelp"
+   * error.errors[0].message // => "--use-api and --use-docker are mutually exclusive"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <Input>(f: (input: Input) => Effect.Effect<void, CliError.CliError, Environment>): <Name extends string, ContextInput, E, R>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<Name, Input, ContextInput, E, R>
+  /**
+   * Validates the parsed input of a command before the handler runs.
+   *
+   * **Details**
+   *
+   * Use this for rules that involve several flags or arguments, such as
+   * mutually exclusive flags. The validation receives the same input as the
+   * handler, with defaults, prompts and the wizard already applied. A failure
+   * is shown with the command help, like a parse error, and the handler does
+   * not run. Fail with `CliError.ValidationError` to supply the message, or
+   * with any other `CliError`. Validations run in the order they were added and
+   * stop at the first failure. Adding a handler later with `withHandler` keeps
+   * them.
+   *
+   * A validation sees only the input that exists where it is applied. Add it
+   * after `withSharedFlags` to see the shared flags. Added after
+   * `withSubcommands`, it also runs when a subcommand is selected, with the
+   * parent's shared flags as input.
+   *
+   * **Example** (Rejecting mutually exclusive flags)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
+   * import { CliError, Command, Flag } from "effect/cli"
+   * import { ChildProcessSpawner } from "effect/process"
+   * import { TestConsole } from "effect/testing"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   TestConsole.layer,
+   *   Layer.succeed(Terminal.Terminal, Terminal.make({
+   *     columns: Effect.succeed(80),
+   *     rows: Effect.succeed(24),
+   *     readInput: Effect.die("unused"),
+   *     readLine: Effect.die("unused"),
+   *     display: () => Effect.void
+   *   })),
+   *   Layer.succeed(
+   *     ChildProcessSpawner.ChildProcessSpawner,
+   *     ChildProcessSpawner.make(() => Effect.die("unused"))
+   *   )
+   * )
+   *
+   * const download = Command.make("download", {
+   *   useApi: Flag.Boolean("use-api").pipe(Flag.withDefault(false)),
+   *   useDocker: Flag.Boolean("use-docker").pipe(Flag.withDefault(false))
+   * }, () => Effect.void).pipe(
+   *   Command.validate(({ useApi, useDocker }) =>
+   *     useApi && useDocker
+   *       ? Effect.fail(
+   *         new CliError.ValidationError({
+   *           message: "--use-api and --use-docker are mutually exclusive"
+   *         })
+   *       )
+   *       : Effect.void
+   *   )
+   * )
+   *
+   * const error = await Effect.runPromise(
+   *   Command.runWith(download, { version: "1.0.0" })(["--use-api", "--use-docker"]).pipe(
+   *     Effect.flip,
+   *     Effect.provide(CliTestLayer)
+   *   )
+   * )
+   * error._tag // => "ShowHelp"
+   * error.errors[0].message // => "--use-api and --use-docker are mutually exclusive"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <Name extends string, Input, ContextInput, E, R>(
+    self: Command<Name, Input, ContextInput, E, R>,
+    f: (input: Input) => Effect.Effect<void, CliError.CliError, Environment>
+  ): Command<Name, Input, ContextInput, E, R>
+} = dual(2, <Name extends string, Input, ContextInput, E, R>(
+  self: Command<Name, Input, ContextInput, E, R>,
+  f: (input: Input) => Effect.Effect<void, CliError.CliError, Environment>
+): Command<Name, Input, ContextInput, E, R> => {
+  const impl = toImpl(self)
+  return makeCommand({
+    ...impl,
+    parse: (raw) => Effect.tap(impl.parse(raw), f)
+  }) as any
+})
+
 interface SubcommandGroupInternal {
   readonly group: string | undefined
   readonly commands: NonEmptyReadonlyArray<Command.Any>
@@ -1475,7 +1716,7 @@ export const withSubcommands: {
     unlisted: impl.unlisted,
     annotations: impl.annotations,
     globalFlags: impl.globalFlags,
-    examples: impl.examples,
+    resolveExamples: impl.resolveExamples,
     service: impl.service,
     subcommands: normalized.groups,
     parse,
@@ -1597,7 +1838,7 @@ export const withSharedFlags: {
       unlisted: impl.unlisted,
       annotations: impl.annotations,
       globalFlags: impl.globalFlags,
-      examples: impl.examples,
+      resolveExamples: impl.resolveExamples,
       service: impl.service as Context.Key<CommandContext<Name>, NextContextInput>,
       subcommands: impl.subcommands,
       parse,
@@ -2163,6 +2404,10 @@ export const annotateMerge: {
  * Examples are exposed in structured `HelpDoc` data and rendered by the
  * default formatter in an `EXAMPLES` section.
  *
+ * Pass a function to build examples from the `commandPath` shown in help, so
+ * they stay correct wherever the command is mounted. The `examples` field
+ * resolves the function with the command's own name as the path.
+ *
  * **Example** (Adding usage examples)
  *
  * ```ts import.meta.vitest
@@ -2178,6 +2423,20 @@ export const annotateMerge: {
  * login.examples.map((example) => example.command) // => ["myapp login", "myapp login --token sbp_abc123"]
  * ```
  *
+ * **Example** (Deriving examples from the command path)
+ *
+ * ```ts import.meta.vitest
+ * import { Command } from "effect/cli"
+ *
+ * const deploy = Command.make("deploy").pipe(
+ *   Command.withExamples(({ commandPath }) => [
+ *     { command: `${commandPath.join(" ")} --yes`, description: "Take every default" }
+ *   ])
+ * )
+ *
+ * deploy.examples.map((example) => example.command) // => ["deploy --yes"]
+ * ```
+ *
  * @stability unstable
  * @category combinators
  * @since 4.0.0
@@ -2191,6 +2450,10 @@ export const withExamples: {
    * Examples are exposed in structured `HelpDoc` data and rendered by the
    * default formatter in an `EXAMPLES` section.
    *
+   * Pass a function to build examples from the `commandPath` shown in help, so
+   * they stay correct wherever the command is mounted. The `examples` field
+   * resolves the function with the command's own name as the path.
+   *
    * **Example** (Adding usage examples)
    *
    * ```ts import.meta.vitest
@@ -2206,11 +2469,29 @@ export const withExamples: {
    * login.examples.map((example) => example.command) // => ["myapp login", "myapp login --token sbp_abc123"]
    * ```
    *
+   * **Example** (Deriving examples from the command path)
+   *
+   * ```ts import.meta.vitest
+   * import { Command } from "effect/cli"
+   *
+   * const deploy = Command.make("deploy").pipe(
+   *   Command.withExamples(({ commandPath }) => [
+   *     { command: `${commandPath.join(" ")} --yes`, description: "Take every default" }
+   *   ])
+   * )
+   *
+   * deploy.examples.map((example) => example.command) // => ["deploy --yes"]
+   * ```
+   *
    * @stability unstable
    * @category combinators
    * @since 4.0.0
    */
-  (examples: ReadonlyArray<Command.Example>): <const Name extends string, Input, E, R, ContextInput>(
+  (
+    examples:
+      | ReadonlyArray<Command.Example>
+      | ((context: { readonly commandPath: ReadonlyArray<string> }) => ReadonlyArray<Command.Example>)
+  ): <const Name extends string, Input, E, R, ContextInput>(
     self: Command<Name, Input, ContextInput, E, R>
   ) => Command<Name, Input, ContextInput, E, R>
   /**
@@ -2221,6 +2502,10 @@ export const withExamples: {
    * Examples are exposed in structured `HelpDoc` data and rendered by the
    * default formatter in an `EXAMPLES` section.
    *
+   * Pass a function to build examples from the `commandPath` shown in help, so
+   * they stay correct wherever the command is mounted. The `examples` field
+   * resolves the function with the command's own name as the path.
+   *
    * **Example** (Adding usage examples)
    *
    * ```ts import.meta.vitest
@@ -2236,18 +2521,40 @@ export const withExamples: {
    * login.examples.map((example) => example.command) // => ["myapp login", "myapp login --token sbp_abc123"]
    * ```
    *
+   * **Example** (Deriving examples from the command path)
+   *
+   * ```ts import.meta.vitest
+   * import { Command } from "effect/cli"
+   *
+   * const deploy = Command.make("deploy").pipe(
+   *   Command.withExamples(({ commandPath }) => [
+   *     { command: `${commandPath.join(" ")} --yes`, description: "Take every default" }
+   *   ])
+   * )
+   *
+   * deploy.examples.map((example) => example.command) // => ["deploy --yes"]
+   * ```
+   *
    * @stability unstable
    * @category combinators
    * @since 4.0.0
    */
   <const Name extends string, Input, E, R, ContextInput>(
     self: Command<Name, Input, ContextInput, E, R>,
-    examples: ReadonlyArray<Command.Example>
+    examples:
+      | ReadonlyArray<Command.Example>
+      | ((context: { readonly commandPath: ReadonlyArray<string> }) => ReadonlyArray<Command.Example>)
   ): Command<Name, Input, ContextInput, E, R>
 } = dual(2, <const Name extends string, Input, E, R, ContextInput>(
   self: Command<Name, Input, ContextInput, E, R>,
-  examples: ReadonlyArray<Command.Example>
-) => makeCommand({ ...toImpl(self), examples }))
+  examples:
+    | ReadonlyArray<Command.Example>
+    | ((context: { readonly commandPath: ReadonlyArray<string> }) => ReadonlyArray<Command.Example>)
+) =>
+  makeCommand({
+    ...toImpl(self),
+    resolveExamples: Predicate.isFunction(examples) ? (commandPath) => examples({ commandPath }) : () => examples
+  }))
 
 /* ========================================================================== */
 /* Providing Services                                                         */
@@ -2755,7 +3062,7 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
 ): Effect.Effect<void, CliError.CliError, Environment> =>
   Effect.gen(function*() {
     const { builtIns } = yield* CliConfig.CliConfig
-    const formatter = yield* CliOutput.Formatter
+    const formatter = yield* resolveFormatter
     const helpDoc = yield* getHelpForCommandPath(command, error.commandPath, builtIns)
     yield* Console.log(formatter.formatHelpDoc(helpDoc))
     if (renderErrors && error.errors.length > 0) {
@@ -2765,7 +3072,7 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
 
 const showUserError = (error: CliError.UserError): Effect.Effect<void> =>
   Effect.gen(function*() {
-    const formatter = yield* CliOutput.Formatter
+    const formatter = yield* resolveFormatter
     yield* Console.error(formatter.formatError(error))
     error[Runtime.errorReported] = false
   })

package/src/cli/Completions.ts

@@ -48,6 +48,16 @@ export interface FlagDescriptor {
   readonly aliases: ReadonlyArray<string>
   readonly description: string | undefined
   readonly type: FlagType
+  /**
+   * Whether the flag's value is optional. Its value can only be attached with
+   * `=` (`--name=value`), never given as the next word.
+   */
+  readonly optionalValue?: boolean | undefined
+  /**
+   * Long name that sets a boolean flag to `false`. Defaults to `no-<name>`;
+   * `false` means the flag has no negated form.
+   */
+  readonly negation?: string | false | undefined
 }
 
 /**

package/src/cli/Flag.ts

@@ -611,6 +611,224 @@ export const withDescription: {
   <A>(self: Flag<A>, description: string): Flag<A>
 } = dual(2, <A>(self: Flag<A>, description: string) => Param.withDescription(self, description))
 
+/**
+ * Lets a flag be given without a value, in which case `value` is used.
+ *
+ * **Details**
+ *
+ * Follows GNU-style optional values, like `--color[=WHEN]`. An explicit value
+ * must be attached with `=` (`--watch=until-done` or `-w=until-done`). A bare
+ * `--watch` is parsed as `--watch=<value>`, so `value` is validated like any
+ * other input. The flag never consumes the next token, so in `--watch build`,
+ * `build` stays a positional argument or subcommand. The flag is still
+ * required unless it is made optional or given a default.
+ *
+ * **Example** (Flag with an optional value)
+ *
+ * ```ts import.meta.vitest
+ * import { Flag } from "effect/cli"
+ *
+ * const watch = Flag.Literals("watch", ["first-failure", "until-done"]).pipe(
+ *   Flag.withOptionalValue("first-failure"),
+ *   Flag.optional
+ * )
+ * // --watch             => Option.some("first-failure")
+ * // --watch=until-done  => Option.some("until-done")
+ * // (absent)            => Option.none()
+ * // In help: --watch [=choice]
+ * watch.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withOptionalValue: {
+  /**
+   * Lets a flag be given without a value, in which case `value` is used.
+   *
+   * **Details**
+   *
+   * Follows GNU-style optional values, like `--color[=WHEN]`. An explicit value
+   * must be attached with `=` (`--watch=until-done` or `-w=until-done`). A bare
+   * `--watch` is parsed as `--watch=<value>`, so `value` is validated like any
+   * other input. The flag never consumes the next token, so in `--watch build`,
+   * `build` stays a positional argument or subcommand. The flag is still
+   * required unless it is made optional or given a default.
+   *
+   * **Example** (Flag with an optional value)
+   *
+   * ```ts import.meta.vitest
+   * import { Flag } from "effect/cli"
+   *
+   * const watch = Flag.Literals("watch", ["first-failure", "until-done"]).pipe(
+   *   Flag.withOptionalValue("first-failure"),
+   *   Flag.optional
+   * )
+   * // --watch             => Option.some("first-failure")
+   * // --watch=until-done  => Option.some("until-done")
+   * // (absent)            => Option.none()
+   * // In help: --watch [=choice]
+   * watch.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  (value: string): <A>(self: Flag<A>) => Flag<A>
+  /**
+   * Lets a flag be given without a value, in which case `value` is used.
+   *
+   * **Details**
+   *
+   * Follows GNU-style optional values, like `--color[=WHEN]`. An explicit value
+   * must be attached with `=` (`--watch=until-done` or `-w=until-done`). A bare
+   * `--watch` is parsed as `--watch=<value>`, so `value` is validated like any
+   * other input. The flag never consumes the next token, so in `--watch build`,
+   * `build` stays a positional argument or subcommand. The flag is still
+   * required unless it is made optional or given a default.
+   *
+   * **Example** (Flag with an optional value)
+   *
+   * ```ts import.meta.vitest
+   * import { Flag } from "effect/cli"
+   *
+   * const watch = Flag.Literals("watch", ["first-failure", "until-done"]).pipe(
+   *   Flag.withOptionalValue("first-failure"),
+   *   Flag.optional
+   * )
+   * // --watch             => Option.some("first-failure")
+   * // --watch=until-done  => Option.some("until-done")
+   * // (absent)            => Option.none()
+   * // In help: --watch [=choice]
+   * watch.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <A>(self: Flag<A>, value: string): Flag<A>
+} = dual(2, <A>(self: Flag<A>, value: string) => Param.withOptionalValue(self, value))
+
+/**
+ * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+ *
+ * **Details**
+ *
+ * The new name replaces the default, so `--no-<name>` is no longer accepted
+ * and shell completions offer the new name instead. Has no effect on
+ * non-boolean flags.
+ *
+ * **Example** (Renaming a boolean flag's negation)
+ *
+ * ```ts import.meta.vitest
+ * import { Flag } from "effect/cli"
+ *
+ * const validate = Flag.Boolean("validate").pipe(
+ *   Flag.withDefault(true),
+ *   Flag.withNegation("skip-validate")
+ * )
+ * // --validate       => true
+ * // --skip-validate  => false
+ * // --no-validate    => unrecognized flag
+ * validate.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withNegation: {
+  /**
+   * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+   *
+   * **Details**
+   *
+   * The new name replaces the default, so `--no-<name>` is no longer accepted
+   * and shell completions offer the new name instead. Has no effect on
+   * non-boolean flags.
+   *
+   * **Example** (Renaming a boolean flag's negation)
+   *
+   * ```ts import.meta.vitest
+   * import { Flag } from "effect/cli"
+   *
+   * const validate = Flag.Boolean("validate").pipe(
+   *   Flag.withDefault(true),
+   *   Flag.withNegation("skip-validate")
+   * )
+   * // --validate       => true
+   * // --skip-validate  => false
+   * // --no-validate    => unrecognized flag
+   * validate.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  (name: string): <A>(self: Flag<A>) => Flag<A>
+  /**
+   * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+   *
+   * **Details**
+   *
+   * The new name replaces the default, so `--no-<name>` is no longer accepted
+   * and shell completions offer the new name instead. Has no effect on
+   * non-boolean flags.
+   *
+   * **Example** (Renaming a boolean flag's negation)
+   *
+   * ```ts import.meta.vitest
+   * import { Flag } from "effect/cli"
+   *
+   * const validate = Flag.Boolean("validate").pipe(
+   *   Flag.withDefault(true),
+   *   Flag.withNegation("skip-validate")
+   * )
+   * // --validate       => true
+   * // --skip-validate  => false
+   * // --no-validate    => unrecognized flag
+   * validate.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <A>(self: Flag<A>, name: string): Flag<A>
+} = dual(2, <A>(self: Flag<A>, name: string) => Param.withNegation(self, name))
+
+/**
+ * Removes the negated `--no-<name>` form of a boolean flag.
+ *
+ * **Details**
+ *
+ * The negated form is then rejected as an unrecognized flag and left out of
+ * shell completions. Has no effect on non-boolean flags.
+ *
+ * **Example** (Disabling a boolean flag's negation)
+ *
+ * ```ts import.meta.vitest
+ * import { Flag } from "effect/cli"
+ *
+ * const unsafe = Flag.Boolean("unsafe").pipe(
+ *   Flag.withDefault(false),
+ *   Flag.withoutNegation
+ * )
+ * // --unsafe     => true
+ * // --no-unsafe  => unrecognized flag
+ * unsafe.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withoutNegation = <A>(self: Flag<A>): Flag<A> => Param.withoutNegation(self)
+
 // -------------------------------------------------------------------------------------
 // metadata
 // -------------------------------------------------------------------------------------

package/src/cli/GlobalFlag.ts

@@ -17,11 +17,11 @@ import * as Context from "../Context.ts"
 import * as Effect from "../Effect.ts"
 import type { LogLevel as LogLevelType } from "../LogLevel.ts"
 import * as Option from "../Option.ts"
-import * as CliOutput from "./CliOutput.ts"
 import type * as Command from "./Command.ts"
 import * as Completions_ from "./Completions.ts"
 import * as Flag from "./Flag.ts"
 import * as CommandDescriptor from "./internal/completions/descriptor.ts"
+import { resolveFormatter } from "./internal/formatter.ts"
 import * as HelpInternal from "./internal/help.ts"
 
 /* ========================================================================== */
@@ -169,7 +169,7 @@ export const Help: Action<boolean> = Action({
     Flag.withDefault(false)
   ),
   run: Effect.fnUntraced(function*(_, { builtIns, command, commandPath }) {
-    const formatter = yield* CliOutput.Formatter
+    const formatter = yield* resolveFormatter
     const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, builtIns)
     yield* Console.log(formatter.formatHelpDoc(helpDoc))
   })
@@ -193,7 +193,7 @@ export const Version: Action<boolean> = Action({
     Flag.withDefault(false)
   ),
   run: Effect.fnUntraced(function*(_, { command, version }) {
-    const formatter = yield* CliOutput.Formatter
+    const formatter = yield* resolveFormatter
     yield* Console.log(formatter.formatVersion(command.name, version))
   })
 })