Render CLI UserError through the output formatter

[tim-smart]

Summary

• add an optional user-facing message to CliError.UserError, with safe fallbacks from its cause
• render direct UserError failures through the installed CliOutput.Formatter while preserving the failure
• add renderErrors: false so host applications can own rendering
• cover message fallback, formatting, handler rendering, parse-path behavior, and opt-out behavior

Validation

• nix develop -c pnpm exec vitest run packages/effect/test/unstable/cli/Errors.test.ts packages/effect/test/unstable/cli/Command.test.ts packages/effect/test/unstable/cli/Param.test.ts
• nix develop -c pnpm --dir packages/effect check
• nix develop -c pnpm lint

Closes EFF-540
Closes #7089

[changeset-bot]

🦋 Changeset detected

Latest commit: 6439b67

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 30 packages

Name	Type
effect	Patch
@effect/ai-anthropic	Patch
@effect/ai-openai	Patch
@effect/ai-openai-compat	Patch
@effect/ai-openrouter	Patch
@effect/atom-react	Patch
@effect/atom-solid	Patch
@effect/atom-vue	Patch
@effect/docgen	Patch
@effect/doctest	Patch
@effect/openapi-generator	Patch
@effect/opentelemetry	Patch
@effect/platform-browser	Patch
@effect/platform-bun	Patch
@effect/platform-deno	Patch
@effect/platform-node	Patch
@effect/platform-node-shared	Patch
@effect/sql-clickhouse	Patch
@effect/sql-d1	Patch
@effect/sql-libsql	Patch
@effect/sql-mssql	Patch
@effect/sql-mysql2	Patch
@effect/sql-pg	Patch
@effect/sql-pglite	Patch
@effect/sql-sqlite-bun	Patch
@effect/sql-sqlite-do	Patch
@effect/sql-sqlite-node	Patch
@effect/sql-sqlite-react-native	Patch
@effect/sql-sqlite-wasm	Patch
@effect/vitest	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pullfrog]

ℹ️ No critical issues — one minor test-name nit inline.

Reviewed changes

This PR adds user-facing rendering for CliError.UserError failures and an opt-out for host applications:

• CliError.UserError now accepts an optional userMessage and falls back safely through string cause, Error.message, and a generic default.
• UserError is marked with [Runtime.errorReported] = false so the runtime logger does not duplicate CLI-rendered output (consistent with ShowHelp).
• Command.run / runWith gained a renderErrors option and now render direct UserError failures through the installed CliOutput.Formatter before rethrowing the original error.
• Tests cover message fallback, control-character escaping, custom-formatter integration, argument-path wrapping, and renderErrors: false opt-out.

  ^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[github-actions]

Bundle Size Analysis

Generated from PR build output; treat the content below as untrusted.

File Name	Current Size	Previous Size	Difference
basic.ts	6.92 KB	6.92 KB	0.00 KB (0.00%)
batching.ts	9.72 KB	9.72 KB	0.00 KB (0.00%)
brand.ts	6.60 KB	6.60 KB	0.00 KB (0.00%)
cache.ts	10.59 KB	10.59 KB	0.00 KB (0.00%)
config.ts	20.83 KB	20.83 KB	0.00 KB (0.00%)
differ.ts	19.67 KB	19.67 KB	0.00 KB (0.00%)
http-client.ts	21.50 KB	21.50 KB	0.00 KB (0.00%)
logger.ts	10.81 KB	10.81 KB	0.00 KB (0.00%)
metric.ts	8.86 KB	8.86 KB	0.00 KB (0.00%)
optic.ts	6.68 KB	6.68 KB	0.00 KB (0.00%)
pubsub.ts	14.86 KB	14.86 KB	0.00 KB (0.00%)
queue.ts	11.54 KB	11.54 KB	0.00 KB (0.00%)
schedule.ts	10.71 KB	10.71 KB	0.00 KB (0.00%)
schema-class.ts	19.38 KB	19.38 KB	0.00 KB (0.00%)
schema-fromJsonSchemaDocument.ts	29.20 KB	29.20 KB	0.00 KB (0.00%)
schema-representation-roundtrip.ts	25.51 KB	25.51 KB	0.00 KB (0.00%)
schema-string-transformation.ts	13.49 KB	13.49 KB	0.00 KB (0.00%)
schema-string.ts	11.03 KB	11.03 KB	0.00 KB (0.00%)
schema-template-literal.ts	15.30 KB	15.30 KB	0.00 KB (0.00%)
schema-toArbitraryLazy.ts	21.43 KB	21.43 KB	0.00 KB (0.00%)
schema-toCodeDocument.ts	23.87 KB	23.87 KB	0.00 KB (0.00%)
schema-toCodecJson.ts	18.64 KB	18.64 KB	0.00 KB (0.00%)
schema-toEquivalence.ts	18.47 KB	18.47 KB	0.00 KB (0.00%)
schema-toFormatter.ts	18.32 KB	18.32 KB	0.00 KB (0.00%)
schema-toJsonSchemaDocument.ts	22.09 KB	22.09 KB	0.00 KB (0.00%)
schema-toRepresentation.ts	19.01 KB	19.01 KB	0.00 KB (0.00%)
schema.ts	18.62 KB	18.62 KB	0.00 KB (0.00%)
stm.ts	12.59 KB	12.59 KB	0.00 KB (0.00%)
stream.ts	9.67 KB	9.67 KB	0.00 KB (0.00%)

[pullfrog]

✅ No new issues found.

Reviewed changes

Reviewed the delta since the prior Pullfrog review (2baddb95 → 6439b674):

• Fixed Runtime.errorReported semantics for UserError — the marker defaults to true and is flipped to false only after the CLI runner renders the error, so errors caught before rendering or handled with renderErrors: false still reach the runtime reporter.
• Extended renderErrors to parse error details — showHelp now respects the flag, suppressing parse/validation error output while still printing the help document.
• Prevented double-rendering in the wizard path — the re-invocation of runWith for wizard-generated arguments passes renderErrors: false.
• Tightened UserError.message fallback — empty userMessage and empty string causes now fall through to the next fallback.
• Added tests for the new reporting semantics, wizard single-render behavior, help-only output when renderErrors: false, and empty-message fallback.
• Renamed the misleading Errors.test.ts test flagged in the prior review to describe the "reported before render" behavior accurately.

  ^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}