Command.runWith has no way to opt out of its own console-rendered help/error output on parse failures

[Coly010]

Effect version

4.0.0-beta.93 (effect/unstable/cli)

Description

Command.runWith's parser (packages/effect/src/unstable/cli/Command.ts) unconditionally renders its own help/error output to the console whenever a run fails with CliError.ShowHelp, with no way for a host application to opt out of, redirect, or make that rendering conditional on the specific failure. The catchFilter at the end of runWith catches every ShowHelp failure and calls showHelp(command, error) before re-failing with the same error:

const showHelp = <Name extends string, Input, E, R, ContextInput>(
  command: Command<Name, Input, ContextInput, E, R>,
  error: CliError.ShowHelp
): Effect.Effect<void, CliError.CliError, Environment> =>
  Effect.gen(function*() {
    const formatter = yield* CliOutput.Formatter
    const helpDoc = yield* getHelpForCommandPath(command, error.commandPath, GlobalFlag.BuiltIns)
    yield* Console.log(formatter.formatHelpDoc(helpDoc))
    if (error.errors.length > 0) {
      yield* Console.error(formatter.formatErrors(error.errors as any))
    }
  })

// ...
Effect.catchFilter(
  (error) =>
    CliError.isCliError(error) && error._tag === "ShowHelp"
      ? Result.succeed(error)
      : Result.fail(error),
  (error) => Effect.andThen(showHelp(command, error), Effect.fail(error))
),

A host CLI that wants full ownership of its own error/usage rendering — to match a different CLI framework's exact wording, to choose which stream a given failure lands on, or to suppress the built-in render entirely for specific failure tags — has no supported way to do that. runWith's config parameter is just { version: string }; there's no hook to skip, replace, or redirect the internal Console.log/Console.error calls.

Today the only way to get that control is to swap out the ambient Console.Console service for the duration of the run, buffer every log/error write, wait for the run's Exit, inspect the ShowHelp's errors array to classify what should have happened, and then selectively replay/redirect/drop the buffered writes. That means:

• Re-implementing (outside the library) which ShowHelp cases the library itself would consider "should still show usage" vs. "already showed everything needed" — knowledge only runWith/showHelp really have.
• Coupling to showHelp's exact Console call pattern (that it's exactly one log then, conditionally, one error) — any change to that internal implementation silently breaks the workaround.
• No way to prevent the render for a subset of failures without inspecting error internals from outside the library (e.g. wanting to keep the help dump for an unrecognized flag but suppress it for a missing required flag, to match a host framework that treats those differently).

Reproduction

import { Effect, Console } from "effect"
import { Command, Flag } from "effect/unstable/cli"

const cmd = Command.make("greet", { name: Flag.string("name") }, () => Effect.void)

const writes: Array<string> = []
const bufferingConsole = {
  ...console,
  log: (...args: unknown[]) => Effect.sync(() => writes.push(`log: ${args.join(" ")}`)),
  error: (...args: unknown[]) => Effect.sync(() => writes.push(`error: ${args.join(" ")}`)),
}

const program = Command.runWith(cmd, { version: "1.0.0" })([]).pipe(
  Effect.provideService(Console.Console, bufferingConsole as any),
  Effect.exit,
)

Effect.runPromise(program).then((exit) => {
  console.log("writes:", writes) // always has the library's own help+error render
  console.log("exit:", exit)     // caller ALSO gets the ShowHelp error to handle itself
})

Running this for a missing required flag (name never supplied) produces both:

1. The library's own Console.log/Console.error render (captured in writes above), which happens unconditionally.
2. The ShowHelp failure surfacing through exit, for the caller to render again if it wants its own error message.

There is no runWith option to get #2 without #1.

Suggested fix

A few shapes that would work, roughly in order of preference:

• A. Add a runWith config option (e.g. renderHelp?: boolean, default true) that skips the internal showHelp call entirely, so a host that wants to own rendering gets the bare ShowHelp failure with no console side effect at all.
• B. Let runWith accept a render hook (e.g. config.onShowHelp?: (error: CliError.ShowHelp, formatter: CliOutput.Formatter) => Effect.Effect<void>) in place of the hardcoded Console.log/Console.error pair, so a host can redirect output per-failure-tag without needing to intercept Console at all.
• C. At minimum, export showHelp (or an equivalent pure "format without printing" function) as public API, so hosts that need to suppress the built-in render can still reproduce it faithfully on their own terms instead of re-deriving formatter.formatHelpDoc/formatErrors's call order by trial and error.

Happy to open a PR for whichever direction maintainers prefer — we're working around this downstream in our own CLI (built on effect/unstable/cli) by swapping the ambient Console.Console service, but it's fragile against any change to showHelp's internals and duplicates classification logic the library already has.