effect 4.0.6 → 4.0.7

package/src/cli/CliOutput.ts

@@ -1,22 +1,24 @@
 /**
- * Formats CLI help and errors as text.
+ * Formats and presents CLI help, errors, and version information.
  *
- * This module turns help documents, CLI errors, grouped errors, and version
- * information into strings. It does not write those strings to the terminal
- * itself. It includes the `Formatter` interface, the formatter service, a layer
- * for custom formatters, and the default formatter with configurable color
- * support.
+ * The `Formatter` service turns help documents, errors, and version
+ * information into strings. The `Presenter` service decides where the built-in
+ * help, version, and invalid-invocation output of `Command.runWith` is written,
+ * and can be replaced to suppress or redirect it.
  *
  * @stability unstable
  * @since 4.0.0
  */
 
+import * as Console from "../Console.ts"
 import * as Context from "../Context.ts"
+import * as Effect from "../Effect.ts"
 import * as Layer from "../Layer.ts"
 import * as Option from "../Option.ts"
 import type * as CliError from "./CliError.ts"
 import type { HelpDoc } from "./HelpDoc.ts"
 import * as Ansi from "./internal/ansi.ts"
+import * as TerminalCapabilities from "./TerminalCapabilities.ts"
 
 /**
  * Defines the service interface for formatting CLI output including help, errors, and version info.
@@ -205,6 +207,124 @@ export interface Formatter {
   readonly formatErrors: (errors: ReadonlyArray<CliError.CliError>) => string
 }
 
+/**
+ * Presents the built-in help, version, and invalid-invocation output of
+ * `Command.runWith`.
+ *
+ * **When to use**
+ *
+ * Use to suppress, redirect, or replace that output, for example to keep
+ * stdout clean for machine-readable results.
+ *
+ * **Details**
+ *
+ * Events carry the help document and errors rather than rendered text, so a
+ * presenter can still render them with the `Formatter` service. Presenting an
+ * event does not change the result of the run: implicit help and invalid
+ * invocations still fail with `CliError.ShowHelp`.
+ *
+ * **Gotchas**
+ *
+ * `--completions` scripts, wizard mode output, and handler failures rendered
+ * through `CliError.userMessage` do not go through the presenter.
+ *
+ * **Example** (Writing invalid-invocation output to stderr)
+ *
+ * ```ts import.meta.vitest
+ * import { Console, Effect } from "effect"
+ * import { CliOutput } from "effect/cli"
+ *
+ * const StderrPresenter = CliOutput.layerPresenter({
+ *   present: (event) =>
+ *     event._tag === "InvalidInvocation"
+ *       ? Effect.gen(function*() {
+ *         const formatter = yield* CliOutput.Formatter
+ *         yield* Console.error(formatter.formatHelpDoc(event.helpDoc))
+ *         yield* Console.error(formatter.formatErrors(event.errors))
+ *       })
+ *       : CliOutput.defaultPresenter.present(event)
+ * })
+ * ```
+ *
+ * @see {@link defaultPresenter} for the default console output
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Presenter {
+  /**
+   * Presents a CLI output event.
+   *
+   * @stability unstable
+   * @since 4.0.0
+   */
+  readonly present: (event: Presenter.Event) => Effect.Effect<void>
+}
+
+/**
+ * Types used by the `Presenter` service.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+export declare namespace Presenter {
+  /**
+   * Output events produced while running a CLI command.
+   *
+   * @stability unstable
+   * @category models
+   * @since 4.0.0
+   */
+  export type Event = Help | InvalidInvocation | Version
+
+  /**
+   * Help for a command path.
+   *
+   * **Details**
+   *
+   * `reason` is `"Requested"` for `--help`, and `"Implicit"` when the run
+   * fails with a `CliError.ShowHelp` that carries no errors, such as selecting
+   * a command that has no handler, or when `renderErrors` is `false`.
+   *
+   * @stability unstable
+   * @category models
+   * @since 4.0.0
+   */
+  export interface Help {
+    readonly _tag: "Help"
+    readonly reason: "Requested" | "Implicit"
+    readonly commandPath: ReadonlyArray<string>
+    readonly helpDoc: HelpDoc
+  }
+
+  /**
+   * Help and parse or validation errors for an invalid invocation.
+   *
+   * @stability unstable
+   * @category models
+   * @since 4.0.0
+   */
+  export interface InvalidInvocation {
+    readonly _tag: "InvalidInvocation"
+    readonly commandPath: ReadonlyArray<string>
+    readonly helpDoc: HelpDoc
+    readonly errors: ReadonlyArray<CliError.NonShowHelpErrors>
+  }
+
+  /**
+   * Version information requested with `--version`.
+   *
+   * @stability unstable
+   * @category models
+   * @since 4.0.0
+   */
+  export interface Version {
+    readonly _tag: "Version"
+    readonly name: string
+    readonly version: string
+  }
+}
+
 /**
  * Service reference for the CLI output formatter. Provides a default implementation
  * that can be overridden for custom formatting or testing.
@@ -238,6 +358,53 @@ export const Formatter: Context.Reference<Formatter> = Context.Reference(
   { defaultValue: () => defaultFormatter() }
 )
 
+/**
+ * Default presenter that renders events with the current `Formatter` and
+ * writes them with `Console`.
+ *
+ * **Details**
+ *
+ * Help and version output goes to `Console.log`. Invalid invocations write
+ * help to `Console.log` and errors to `Console.error`. When no `Formatter` is
+ * installed, the default formatter colors output when `TerminalCapabilities`
+ * says it can.
+ *
+ * @see {@link Presenter} for replacing the default output
+ * @stability unstable
+ * @category defaults
+ * @since 4.0.0
+ */
+export const defaultPresenter: Presenter = {
+  present: Effect.fnUntraced(function*(event) {
+    const context = yield* Effect.context<never>()
+    const formatter = Context.getOrUndefined(context, Formatter) ??
+      defaultFormatter({ colors: Context.get(context, TerminalCapabilities.TerminalCapabilities).canColor })
+    switch (event._tag) {
+      case "Help":
+        return yield* Console.log(formatter.formatHelpDoc(event.helpDoc))
+      case "InvalidInvocation":
+        yield* Console.log(formatter.formatHelpDoc(event.helpDoc))
+        return yield* Console.error(formatter.formatErrors(event.errors))
+      case "Version":
+        return yield* Console.log(formatter.formatVersion(event.name, event.version))
+    }
+  })
+}
+
+/**
+ * Service reference for the CLI output presenter. Defaults to
+ * `defaultPresenter`.
+ *
+ * @see {@link layerPresenter} for providing a custom presenter
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export const Presenter: Context.Reference<Presenter> = Context.Reference(
+  "effect/cli/CliOutput/Presenter",
+  { defaultValue: () => defaultPresenter }
+)
+
 /**
  * Creates a Layer that provides a custom Formatter implementation.
  *
@@ -268,6 +435,16 @@ export const Formatter: Context.Reference<Formatter> = Context.Reference(
  */
 export const layer = (formatter: Formatter): Layer.Layer<never> => Layer.succeed(Formatter)(formatter)
 
+/**
+ * Creates a Layer that provides a custom Presenter implementation.
+ *
+ * @see {@link Presenter} for the events a presenter receives
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerPresenter = (presenter: Presenter): Layer.Layer<never> => Layer.succeed(Presenter)(presenter)
+
 const escapeControlCharacters = (text: string): string =>
   // oxlint-disable-next-line no-control-regex
   text.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, (character) =>

package/src/cli/Command.ts

@@ -30,6 +30,7 @@ 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"
@@ -3062,19 +3063,24 @@ 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* resolveFormatter
-    const helpDoc = yield* getHelpForCommandPath(command, error.commandPath, builtIns)
-    yield* Console.log(formatter.formatHelpDoc(helpDoc))
-    if (renderErrors && error.errors.length > 0) {
-      yield* Console.error(formatter.formatErrors(error.errors as any))
-    }
+    const presenter = yield* CliOutput.Presenter
+    const { commandPath, errors } = error
+    const helpDoc = yield* getHelpForCommandPath(command, commandPath, builtIns)
+    yield* presenter.present(
+      renderErrors && errors.length > 0
+        ? { _tag: "InvalidInvocation", commandPath, helpDoc, errors }
+        : { _tag: "Help", reason: "Implicit", commandPath, helpDoc }
+    )
   })
 
-const showUserError = (error: CliError.UserError): Effect.Effect<void> =>
+const showUserError = (error: object, userMessage: string): Effect.Effect<void> =>
   Effect.gen(function*() {
     const formatter = yield* resolveFormatter
-    yield* Console.error(formatter.formatError(error))
-    error[Runtime.errorReported] = false
+    const rendered = error instanceof CliError.UserError
+      ? error
+      : new CliError.UserError({ cause: error, userMessage })
+    yield* Console.error(formatter.formatError(rendered))
+    Object.assign(error, { [Runtime.errorReported]: false })
   })
 
 /**
@@ -3085,10 +3091,12 @@ const showUserError = (error: CliError.UserError): Effect.Effect<void> =>
  * Use when command-line arguments should come from `Stdio` at the application
  * entry point.
  *
- * Help documents are always rendered. By default, parse error details and
- * `CliError.UserError` failures are also rendered with the installed
- * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
- * `false` when the host application owns error rendering.
+ * Help, version, and parse error output is written through
+ * `CliOutput.Presenter`. Help documents are always presented. By default,
+ * parse error details are also presented, and handler failures annotated with
+ * `CliError.userMessage`, including `CliError.UserError`, are rendered with the
+ * installed `CliOutput.Formatter` before the error is rethrown. Set
+ * `renderErrors` to `false` when the host application owns error rendering.
  *
  * **Example** (Running commands with standard input)
  *
@@ -3148,10 +3156,12 @@ export const run: {
    * Use when command-line arguments should come from `Stdio` at the application
    * entry point.
    *
-   * Help documents are always rendered. By default, parse error details and
-   * `CliError.UserError` failures are also rendered with the installed
-   * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
-   * `false` when the host application owns error rendering.
+   * Help, version, and parse error output is written through
+   * `CliOutput.Presenter`. Help documents are always presented. By default,
+   * parse error details are also presented, and handler failures annotated with
+   * `CliError.userMessage`, including `CliError.UserError`, are rendered with the
+   * installed `CliOutput.Formatter` before the error is rethrown. Set
+   * `renderErrors` to `false` when the host application owns error rendering.
    *
    * **Example** (Running commands with standard input)
    *
@@ -3218,10 +3228,12 @@ export const run: {
    * Use when command-line arguments should come from `Stdio` at the application
    * entry point.
    *
-   * Help documents are always rendered. By default, parse error details and
-   * `CliError.UserError` failures are also rendered with the installed
-   * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
-   * `false` when the host application owns error rendering.
+   * Help, version, and parse error output is written through
+   * `CliOutput.Presenter`. Help documents are always presented. By default,
+   * parse error details are also presented, and handler failures annotated with
+   * `CliError.userMessage`, including `CliError.UserError`, are rendered with the
+   * installed `CliOutput.Formatter` before the error is rethrown. Set
+   * `renderErrors` to `false` when the host application owns error rendering.
    *
    * **Example** (Running commands with standard input)
    *
@@ -3301,10 +3313,12 @@ export const run: {
  * Use when you need to test CLI applications or programmatically execute
  * commands with specific arguments.
  *
- * Help documents are always rendered. By default, parse error details and
- * `CliError.UserError` failures are also rendered with the installed
- * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
- * `false` when the host application owns error rendering.
+ * Help, version, and parse error output is written through
+ * `CliOutput.Presenter`. Help documents are always presented. By default,
+ * parse error details are also presented, and handler failures annotated with
+ * `CliError.userMessage`, including `CliError.UserError`, are rendered with the
+ * installed `CliOutput.Formatter` before the error is rethrown. Set
+ * `renderErrors` to `false` when the host application owns error rendering.
  *
  * **Example** (Running commands with explicit arguments)
  *
@@ -3387,6 +3401,9 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
       // 3. Parse command arguments from remaining tokens
       const parsedArgs = yield* Parser.parseArgs({ tokens: remainder, trailingOperands }, command)
       const commandPath = [command.name, ...Parser.getCommandPath(parsedArgs)] as const
+      const toShowHelp = Effect.mapError((error: CliError.CliError) =>
+        error._tag === "ShowHelp" ? error : new CliError.ShowHelp({ commandPath, errors: [error] })
+      )
       const handlerCtx: GlobalFlag.HandlerContext = { builtIns, command, commandPath, version: config.version }
       const activeFlags = getGlobalFlagsForCommandPath(command, commandPath, builtIns)
 
@@ -3409,7 +3426,7 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
           return entries !== undefined && entries.length > 0
         })
         if (!hasEntry) continue
-        const [, value] = yield* flag.flag.parse(emptyArgs)
+        const [, value] = yield* flag.flag.parse(emptyArgs).pipe(toShowHelp)
         if (flag === GlobalFlag.Wizard) {
           const { colors } = yield* Prompt.Theme
           return yield* Effect.gen(function*() {
@@ -3442,23 +3459,17 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
       if (parsedArgs.errors && parsedArgs.errors.length > 0) {
         return yield* new CliError.ShowHelp({ commandPath, errors: parsedArgs.errors })
       }
-      const parseResult = yield* Effect.result(commandImpl.parse(parsedArgs))
-      if (parseResult._tag === "Failure") {
-        return yield* new CliError.ShowHelp({
-          commandPath,
-          errors: [parseResult.failure as CliError.NonShowHelpErrors]
-        })
-      }
+      const input = yield* commandImpl.parse(parsedArgs).pipe(toShowHelp)
 
       // 7. Provide setting values
-      let program = commandImpl.handle(parseResult.success, [command.name])
+      let program = commandImpl.handle(input, [command.name])
       const logLevel = activeFlags.includes(GlobalFlag.LogLevel)
-        ? (yield* GlobalFlag.LogLevel.flag.parse(emptyArgs))[1]
+        ? (yield* GlobalFlag.LogLevel.flag.parse(emptyArgs).pipe(toShowHelp))[1]
         : Option.none()
       program = Effect.provideService(program, GlobalFlag.LogLevel, logLevel)
       for (const flag of activeFlags) {
         if (flag._tag !== "Setting" || flag === GlobalFlag.LogLevel) continue
-        const [, value] = yield* flag.flag.parse(emptyArgs)
+        const [, value] = yield* flag.flag.parse(emptyArgs).pipe(toShowHelp)
         program = Effect.provideService(program, flag, value)
       }
 
@@ -3479,11 +3490,12 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
       (error) => Effect.andThen(showHelp(command, error, config.renderErrors !== false), Effect.fail(error))
     ),
     Effect.catchFilter(
-      (error) =>
-        config.renderErrors !== false && CliError.isCliError(error) && error._tag === "UserError"
-          ? Result.succeed(error)
-          : Result.fail(error),
-      (error) => Effect.andThen(showUserError(error), Effect.fail(error))
+      (error) => {
+        if (config.renderErrors === false || !Predicate.isObjectKeyword(error)) return Result.fail(error)
+        const userMessage = CliError.getUserMessage(error)
+        return userMessage === undefined ? Result.fail(error) : Result.succeed({ error, userMessage })
+      },
+      ({ error, userMessage }) => Effect.andThen(showUserError(error, userMessage), Effect.fail(error))
     ),
     Effect.catchFilter(
       (e) =>

package/src/cli/Completions.ts

@@ -7,7 +7,9 @@
  * @stability unstable
  * @since 4.0.0
  */
+import type { Command } from "./Command.ts"
 import * as Bash from "./internal/completions/bash.ts"
+import * as Descriptor from "./internal/completions/descriptor.ts"
 import * as Fish from "./internal/completions/fish.ts"
 import * as PowerShell from "./internal/completions/powershell.ts"
 import * as Zsh from "./internal/completions/zsh.ts"
@@ -106,6 +108,55 @@ export type ArgumentType =
   | { readonly _tag: "Choice"; readonly values: ReadonlyArray<string> }
   | { readonly _tag: "Path"; readonly pathType: "file" | "directory" | "either" }
 
+/**
+ * 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.
+ *
+ * **Example** (Generating a Zsh completion script at build time)
+ *
+ * ```ts import.meta.vitest
+ * 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
+ * ```
+ *
+ * @see {@link generate} for turning the descriptor into a shell script
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.7
+ */
+export const fromCommand = (command: Command.Any): CommandDescriptor => Descriptor.fromCommand(command)
+
 /**
  * Generates a shell completion script for a command descriptor.
  *

package/src/cli/Flag.ts

@@ -1155,6 +1155,11 @@ export const withFallbackConfig: {
 /**
  * Adds a fallback prompt that is shown when a required flag is missing.
  *
+ * **Gotchas**
+ *
+ * When `TerminalCapabilities.canPrompt` is `false`, the prompt is skipped and
+ * the original `MissingOption` error is returned.
+ *
  * **Example** (Falling back to prompts)
  *
  * ```ts import.meta.vitest
@@ -1174,6 +1179,11 @@ export const withFallbackPrompt: {
   /**
    * Adds a fallback prompt that is shown when a required flag is missing.
    *
+   * **Gotchas**
+   *
+   * When `TerminalCapabilities.canPrompt` is `false`, the prompt is skipped and
+   * the original `MissingOption` error is returned.
+   *
    * **Example** (Falling back to prompts)
    *
    * ```ts import.meta.vitest
@@ -1193,6 +1203,11 @@ export const withFallbackPrompt: {
   /**
    * Adds a fallback prompt that is shown when a required flag is missing.
    *
+   * **Gotchas**
+   *
+   * When `TerminalCapabilities.canPrompt` is `false`, the prompt is skipped and
+   * the original `MissingOption` error is returned.
+   *
    * **Example** (Falling back to prompts)
    *
    * ```ts import.meta.vitest

package/src/cli/GlobalFlag.ts

@@ -17,11 +17,10 @@ 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,9 +168,9 @@ export const Help: Action<boolean> = Action({
     Flag.withDefault(false)
   ),
   run: Effect.fnUntraced(function*(_, { builtIns, command, commandPath }) {
-    const formatter = yield* resolveFormatter
+    const presenter = yield* CliOutput.Presenter
     const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, builtIns)
-    yield* Console.log(formatter.formatHelpDoc(helpDoc))
+    yield* presenter.present({ _tag: "Help", reason: "Requested", commandPath, helpDoc })
   })
 })
 
@@ -193,8 +192,8 @@ export const Version: Action<boolean> = Action({
     Flag.withDefault(false)
   ),
   run: Effect.fnUntraced(function*(_, { command, version }) {
-    const formatter = yield* resolveFormatter
-    yield* Console.log(formatter.formatVersion(command.name, version))
+    const presenter = yield* CliOutput.Presenter
+    yield* presenter.present({ _tag: "Version", name: command.name, version })
   })
 })
 
@@ -249,7 +248,7 @@ export const Completions: Action<Option.Option<Completions_.Shell>> = Action({
   ),
   run: Effect.fnUntraced(function*(shell, { command }) {
     if (Option.isNone(shell)) return
-    const descriptor = CommandDescriptor.fromCommand(command)
+    const descriptor = Completions_.fromCommand(command)
     yield* Console.log(
       Completions_.generate(command.name, shell.value, descriptor)
     )

package/src/cli/Param.ts

@@ -25,6 +25,7 @@ import * as CliError from "./CliError.ts"
 import type { Environment } from "./Command.ts"
 import * as Primitive from "./Primitive.ts"
 import * as Prompt from "./Prompt.ts"
+import * as TerminalCapabilities from "./TerminalCapabilities.ts"
 
 const TypeId = "~effect/cli/Param"
 
@@ -1931,6 +1932,9 @@ export const withFallbackConfig: {
  *
  * This only handles missing options and missing arguments. Invalid values do not
  * prompt, and prompt cancellation re-fails with the original missing error.
+ * When `TerminalCapabilities.canPrompt` is `false`, the fallback is skipped
+ * entirely: no prompt is built or shown, and the original missing error is
+ * returned.
  *
  * @see {@link FallbackPrompt} for accepted fallback prompt forms
  * @see {@link withFallbackConfig} for loading a fallback from config
@@ -1958,6 +1962,9 @@ export const withFallbackPrompt: {
    *
    * This only handles missing options and missing arguments. Invalid values do not
    * prompt, and prompt cancellation re-fails with the original missing error.
+   * When `TerminalCapabilities.canPrompt` is `false`, the fallback is skipped
+   * entirely: no prompt is built or shown, and the original missing error is
+   * returned.
    *
    * @see {@link FallbackPrompt} for accepted fallback prompt forms
    * @see {@link withFallbackConfig} for loading a fallback from config
@@ -1985,6 +1992,9 @@ export const withFallbackPrompt: {
    *
    * This only handles missing options and missing arguments. Invalid values do not
    * prompt, and prompt cancellation re-fails with the original missing error.
+   * When `TerminalCapabilities.canPrompt` is `false`, the fallback is skipped
+   * entirely: no prompt is built or shown, and the original missing error is
+   * returned.
    *
    * @see {@link FallbackPrompt} for accepted fallback prompt forms
    * @see {@link withFallbackConfig} for loading a fallback from config
@@ -1999,11 +2009,16 @@ export const withFallbackPrompt: {
   self: Param<Kind, A>,
   prompt: FallbackPrompt<B>
 ): Param<Kind, A | B> => {
-  const runPrompt = (error: CliError.MissingOption | CliError.MissingArgument, args: ParsedArgs) =>
-    Effect.flatMap(Prompt.isPrompt(prompt) ? Effect.succeed(prompt) : prompt, Prompt.run).pipe(
-      Effect.map((value) => [args.arguments, value as A | B] as const),
-      Effect.catchTag("QuitError", () => Effect.fail(error))
-    )
+  const runPrompt = Effect.fnUntraced(function*(
+    error: CliError.MissingOption | CliError.MissingArgument,
+    args: ParsedArgs
+  ) {
+    const { canPrompt } = yield* TerminalCapabilities.TerminalCapabilities
+    if (!canPrompt) return yield* Effect.fail(error)
+    const built = Prompt.isPrompt(prompt) ? prompt : yield* prompt
+    const value = yield* Effect.catchTag(Prompt.run(built), "QuitError", () => Effect.fail(error))
+    return [args.arguments, value as A | B] as const
+  })
   return transform(
     self,
     (parse) => (args) =>
@@ -3191,7 +3206,15 @@ const parseFlag: <A>(
     return yield* new CliError.MissingOption({ option: name })
   }
 
-  // Parse the first value (later we can handle multiple)
+  if (providedValues.length > 1) {
+    return yield* new CliError.InvalidValue({
+      option: name,
+      value: `${providedValues.length} occurrences`,
+      expected: "at most 1 value",
+      kind: "flag"
+    })
+  }
+
   const arg = providedValues[0]
   const value = yield* Effect.mapError(
     primitiveType.parse(arg),

package/src/cli/TerminalCapabilities.ts

@@ -5,7 +5,9 @@
  * the current process. The layer reads the same variables through
  * `ConfigProvider`, plus the TTY state of `Stdio`. Unless a
  * `CliOutput.Formatter` is provided, the built-in help, version, and error
- * output of `Command` follows `canColor`.
+ * output of `Command` follows `canColor`. Fallback prompts added with
+ * `Flag.withFallbackPrompt` or `Argument.withFallbackPrompt` only run when
+ * `canPrompt` is `true`.
  *
  * @stability unstable
  * @since 4.0.0
@@ -25,8 +27,9 @@ import * as Stdio from "../Stdio.ts"
  * `canColor` says whether styling will be rendered rather than stored as
  * bytes. `canAnimate` says whether output is being watched, so pacing means
  * something. `canPrompt` says whether a question can be asked and answered.
- * Only `canColor` is read by the built-in `Command` output; the other two are
- * for application code that renders its own output.
+ * The built-in `Command` output reads `canColor`, and fallback prompts for
+ * missing flags and arguments are skipped when `canPrompt` is `false`.
+ * `canAnimate` is for application code that renders its own output.
  *
  * @stability unstable
  * @category models