effect 4.0.7 → 4.1.0

package/src/cli/Argument.ts

@@ -748,6 +748,7 @@ export const map: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -799,6 +800,7 @@ export const mapEffect: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -850,6 +852,7 @@ export const mapEffect: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -909,6 +912,7 @@ export const mapEffect: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -955,6 +959,7 @@ export const mapTryCatch: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1001,6 +1006,7 @@ export const mapTryCatch: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void

package/src/cli/CliOutput.ts

@@ -16,7 +16,7 @@ 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 type { FlagDoc, HelpDoc } from "./HelpDoc.ts"
 import * as Ansi from "./internal/ansi.ts"
 import * as TerminalCapabilities from "./TerminalCapabilities.ts"
 
@@ -453,6 +453,23 @@ const escapeControlCharacters = (text: string): string =>
 /**
  * Creates a default formatter with configurable options.
  *
+ * **Details**
+ *
+ * - `colors`: force ANSI colors on or off. Defaults to terminal detection.
+ * - `inheritedFlags`: how subcommand help renders flags inherited from
+ *   ancestor commands. `"full"` (default) lists them under `INHERITED FLAGS`,
+ *   `"summary"` replaces the section with a pointer to the parent command's
+ *   help, and `"none"` omits it.
+ * - `globalFlags`: the same choice for `GLOBAL FLAGS`, with the summary
+ *   pointing at the help of the nearest command that declares global flags
+ *   (the root command for built-in flags). Commands that declare global flags
+ *   always list them in full.
+ *
+ * **Gotchas**
+ *
+ * Per-flag filtering in a custom formatter matches names, not flag identities.
+ * Renaming a flag without updating the filter silently stops it from matching.
+ *
  * **Example** (Creating default formatters)
  *
  * ```ts import.meta.vitest
@@ -467,6 +484,9 @@ const escapeControlCharacters = (text: string): string =>
  * // Auto-detect colors based on terminal support (default behavior)
  * const autoFormatter = CliOutput.defaultFormatter()
  *
+ * // Point subcommand help at the declaring scope for global flags
+ * const compactFormatter = CliOutput.defaultFormatter({ globalFlags: "summary" })
+ *
  * const error = new CliError.InvalidValue({
  *   option: "foo",
  *   value: "bar",
@@ -477,14 +497,64 @@ const escapeControlCharacters = (text: string): string =>
  * noColorFormatter.formatError(error).includes("Invalid value") // => true
  * colorFormatter.formatVersion("my-tool", "1.2.3").includes("my-tool") // => true
  * autoFormatter.formatVersion("my-tool", "1.2.3").includes("1.2.3") // => true
+ * compactFormatter.formatVersion("my-tool", "1.2.3").includes("my-tool") // => true
+ * ```
+ *
+ * **Example** (Hiding one inherited flag)
+ *
+ * Filter only `inheritedFlags` to keep `--profile` visible on its declaring
+ * command while hiding it on descendants. Other inherited flags still render.
+ *
+ * ```ts import.meta.vitest
+ * import { Context, Effect, Option } from "effect"
+ * import { CliOutput } from "effect/cli"
+ *
+ * const base = CliOutput.defaultFormatter({ colors: false })
+ * const formatter: CliOutput.Formatter = {
+ *   ...base,
+ *   formatHelpDoc: (doc) =>
+ *     base.formatHelpDoc({
+ *       ...doc,
+ *       inheritedFlags: doc.inheritedFlags?.filter((flag) => flag.name !== "profile")
+ *     })
+ * }
+ *
+ * const program = Effect.gen(function*() {
+ *   const output = yield* CliOutput.Formatter
+ *   return output.formatHelpDoc({
+ *     description: "Deploy the application",
+ *     usage: "app deploy",
+ *     annotations: Context.empty(),
+ *     flags: [],
+ *     inheritedFlags: ["profile", "region"].map((name) => ({
+ *       name,
+ *       aliases: [],
+ *       type: "string",
+ *       description: Option.none(),
+ *       required: false
+ *     }))
+ *   })
+ * }).pipe(Effect.provide(CliOutput.layer(formatter)))
+ *
+ * const help = await Effect.runPromise(program)
+ * help.includes("--profile") // => false
+ * help.includes("--region") // => true
  * ```
  *
  * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
-export const defaultFormatter = (options?: { colors?: boolean }): Formatter => {
+export const defaultFormatter = (options?: {
+  readonly colors?: boolean | undefined
+  readonly inheritedFlags?: "full" | "summary" | "none" | undefined
+  readonly globalFlags?: "full" | "summary" | "none" | undefined
+}): Formatter => {
   const useColor = options?.colors ?? Ansi.detectColors()
+  const helpOptions: HelpOptions = {
+    inheritedFlags: options?.inheritedFlags ?? "full",
+    globalFlags: options?.globalFlags ?? "full"
+  }
 
   // Color palette using ANSI escape codes
   const colors = useColor
@@ -512,7 +582,7 @@ export const defaultFormatter = (options?: { colors?: boolean }): Formatter => {
   const bold = useColor ? "\x1b[1m" : ""
 
   return {
-    formatHelpDoc: (doc: HelpDoc): string => formatHelpDocImpl(doc, colors),
+    formatHelpDoc: (doc: HelpDoc): string => formatHelpDocImpl(doc, colors, helpOptions),
     formatCliError: (error): string => escapeControlCharacters(error.message),
     formatError: (error): string => {
       return `\n${bold}${red}ERROR${reset}\n  ${escapeControlCharacters(error.message)}${reset}`
@@ -671,11 +741,18 @@ interface ColorFunctions {
   readonly magenta: (text: string) => string
 }
 
+type FlagSectionMode = "full" | "summary" | "none"
+
+interface HelpOptions {
+  readonly inheritedFlags: FlagSectionMode
+  readonly globalFlags: FlagSectionMode
+}
+
 /**
  * Internal implementation of help formatting that accepts configurable color functions.
  * @internal
  */
-const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
+const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions, options: HelpOptions): string => {
   const sections: Array<string> = []
 
   // Description section
@@ -717,60 +794,51 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
     sections.push("")
   }
 
-  // Flags section
-  if (doc.flags.length > 0) {
-    sections.push(colors.bold("FLAGS"))
-
-    const flagRows: Array<Row> = doc.flags.map((flag) => {
-      const names: Array<string> = []
-
-      // Add main name with -- prefix first
-      names.push(colors.green(`--${flag.name}`))
-
-      // Add aliases after (like -f) to match expected ordering
-      for (const alias of flag.aliases) {
-        names.push(colors.green(alias))
-      }
-
-      const namesPart = names.join(", ")
+  const renderFlags = (title: string, flags: ReadonlyArray<FlagDoc>) => {
+    sections.push(colors.bold(title))
+    sections.push(renderTable(flags.map((flag) => {
+      const names = [`--${flag.name}`, ...flag.aliases].map(colors.green).join(", ")
       const typePart = flag.type !== "boolean" ? ` ${colors.dim(flag.type)}` : ""
-
       return {
-        left: namesPart + typePart,
+        left: names + typePart,
         right: Option.getOrElse(flag.description, () => "")
       }
-    })
-
-    sections.push(renderTable(flagRows))
+    })))
     sections.push("")
   }
 
-  // Global Flags section
-  if (doc.globalFlags && doc.globalFlags.length > 0) {
-    sections.push(colors.bold("GLOBAL FLAGS"))
-
-    const globalFlagRows: Array<Row> = doc.globalFlags.map((flag) => {
-      const names: Array<string> = []
-
-      // Add main name with -- prefix first
-      names.push(colors.green(`--${flag.name}`))
-
-      // Add aliases after (like -f) to match expected ordering
-      for (const alias of flag.aliases) {
-        names.push(colors.green(alias))
-      }
-
-      const namesPart = names.join(", ")
-      const typePart = flag.type !== "boolean" ? ` ${colors.dim(flag.type)}` : ""
+  const summaries: Array<string> = []
+  const renderFlagSection = (
+    title: string,
+    flags: ReadonlyArray<FlagDoc> | undefined,
+    mode: FlagSectionMode,
+    summaryPath: ReadonlyArray<string> | undefined
+  ) => {
+    if (!flags || flags.length === 0 || mode === "none") return
+    if (mode === "summary" && summaryPath && summaryPath.length > 0) {
+      summaries.push(`Run '${summaryPath.join(" ")} --help' for ${title.toLowerCase()}`)
+    } else {
+      renderFlags(title, flags)
+    }
+  }
 
-      return {
-        left: namesPart + typePart,
-        right: Option.getOrElse(flag.description, () => "")
-      }
-    })
+  if (doc.flags.length > 0) {
+    renderFlags("FLAGS", doc.flags)
+  }
 
-    sections.push(renderTable(globalFlagRows))
-    sections.push("")
+  const commandPath = doc.commandPath
+  renderFlagSection("INHERITED FLAGS", doc.inheritedFlags, options.inheritedFlags, commandPath?.slice(0, -1))
+  // Keep globals discoverable on their declaring command, even in "none" mode.
+  const globalFlagsScope = doc.globalFlagsScope ?? commandPath?.slice(0, 1)
+  const declaresGlobalFlags = commandPath === undefined || globalFlagsScope?.length === commandPath.length
+  renderFlagSection(
+    "GLOBAL FLAGS",
+    doc.globalFlags,
+    declaresGlobalFlags ? "full" : options.globalFlags,
+    globalFlagsScope
+  )
+  if (summaries.length > 0) {
+    sections.push(...summaries, "")
   }
 
   // Subcommands section

package/src/cli/Command.ts

@@ -72,6 +72,7 @@ import * as Prompt from "./Prompt.ts"
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -461,6 +462,7 @@ export type Services<C> = C extends Command<
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -573,6 +575,7 @@ export const isCommand = (u: unknown): u is Command.Any => Predicate.hasProperty
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -667,6 +670,7 @@ export const make: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -762,6 +766,7 @@ export const make: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -857,6 +862,7 @@ export const make: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -961,6 +967,7 @@ export const make: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -1018,6 +1025,7 @@ export const withHandler: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1077,6 +1085,7 @@ export const withHandler: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1437,6 +1446,7 @@ const normalizeSubcommandEntries = (
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -1508,6 +1518,7 @@ export const withSubcommands: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1587,6 +1598,7 @@ export const withSubcommands: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1947,6 +1959,7 @@ type ExtractSubcommandContext<T extends ReadonlyArray<Command.SubcommandEntry>>
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -2000,6 +2013,7 @@ export const withDescription: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -2055,6 +2069,7 @@ export const withDescription: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -2588,6 +2603,7 @@ const mapHandler = <Name extends string, Input, E, R, ContextInput, E2, R2>(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -2651,6 +2667,7 @@ export const provide: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -2721,6 +2738,7 @@ export const provide: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -2982,6 +3000,7 @@ export const provideEffectDiscard: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -3114,6 +3133,7 @@ const showUserError = (error: object, userMessage: string): Effect.Effect<void>
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -3179,6 +3199,7 @@ export const run: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -3251,6 +3272,7 @@ export const run: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -3334,6 +3356,7 @@ export const run: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void

package/src/cli/Flag.ts

@@ -290,6 +290,7 @@ export const Directory = (name: string, options?: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -981,6 +982,7 @@ export const withHidden = <A>(self: Flag<A>): Flag<A> => Param.withHidden(self)
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -1171,6 +1173,38 @@ export const withFallbackConfig: {
  * name.kind // => "flag"
  * ```
  *
+ * **Example** (Showing an introduction before fallback prompts)
+ *
+ * The prompt can be built by an effect, which only runs when the prompt is
+ * needed. Share a cached introduction between the prompt builders and
+ * `Command.provideEffectDiscard`: it runs once, before the first prompt, and
+ * also runs when every flag is supplied. Flags declared after the first
+ * prompted flag may not have been validated yet when the introduction runs.
+ *
+ * ```ts import.meta.vitest
+ * import { Console, Effect } from "effect"
+ * import { Command, Flag, Prompt } from "effect/cli"
+ *
+ * const program = Effect.gen(function*() {
+ *   const intro = yield* Effect.cached(Console.log("Welcome to demo"))
+ *
+ *   const ask = (name: string) =>
+ *     Flag.String(name).pipe(
+ *       Flag.withFallbackPrompt(
+ *         Effect.as(intro, Prompt.String({ message: `${name}?` }))
+ *       )
+ *     )
+ *
+ *   const demo = Command.make(
+ *     "demo",
+ *     { name: ask("name"), dir: ask("dir") },
+ *     (input) => Console.log(input)
+ *   ).pipe(Command.provideEffectDiscard(intro))
+ *
+ *   yield* Command.run(demo, { version: "1.0.0" })
+ * })
+ * ```
+ *
  * @stability unstable
  * @category combinators
  * @since 4.0.0
@@ -1195,6 +1229,38 @@ export const withFallbackPrompt: {
    * name.kind // => "flag"
    * ```
    *
+   * **Example** (Showing an introduction before fallback prompts)
+   *
+   * The prompt can be built by an effect, which only runs when the prompt is
+   * needed. Share a cached introduction between the prompt builders and
+   * `Command.provideEffectDiscard`: it runs once, before the first prompt, and
+   * also runs when every flag is supplied. Flags declared after the first
+   * prompted flag may not have been validated yet when the introduction runs.
+   *
+   * ```ts import.meta.vitest
+   * import { Console, Effect } from "effect"
+   * import { Command, Flag, Prompt } from "effect/cli"
+   *
+   * const program = Effect.gen(function*() {
+   *   const intro = yield* Effect.cached(Console.log("Welcome to demo"))
+   *
+   *   const ask = (name: string) =>
+   *     Flag.String(name).pipe(
+   *       Flag.withFallbackPrompt(
+   *         Effect.as(intro, Prompt.String({ message: `${name}?` }))
+   *       )
+   *     )
+   *
+   *   const demo = Command.make(
+   *     "demo",
+   *     { name: ask("name"), dir: ask("dir") },
+   *     (input) => Console.log(input)
+   *   ).pipe(Command.provideEffectDiscard(intro))
+   *
+   *   yield* Command.run(demo, { version: "1.0.0" })
+   * })
+   * ```
+   *
    * @stability unstable
    * @category combinators
    * @since 4.0.0
@@ -1219,6 +1285,38 @@ export const withFallbackPrompt: {
    * name.kind // => "flag"
    * ```
    *
+   * **Example** (Showing an introduction before fallback prompts)
+   *
+   * The prompt can be built by an effect, which only runs when the prompt is
+   * needed. Share a cached introduction between the prompt builders and
+   * `Command.provideEffectDiscard`: it runs once, before the first prompt, and
+   * also runs when every flag is supplied. Flags declared after the first
+   * prompted flag may not have been validated yet when the introduction runs.
+   *
+   * ```ts import.meta.vitest
+   * import { Console, Effect } from "effect"
+   * import { Command, Flag, Prompt } from "effect/cli"
+   *
+   * const program = Effect.gen(function*() {
+   *   const intro = yield* Effect.cached(Console.log("Welcome to demo"))
+   *
+   *   const ask = (name: string) =>
+   *     Flag.String(name).pipe(
+   *       Flag.withFallbackPrompt(
+   *         Effect.as(intro, Prompt.String({ message: `${name}?` }))
+   *       )
+   *     )
+   *
+   *   const demo = Command.make(
+   *     "demo",
+   *     { name: ask("name"), dir: ask("dir") },
+   *     (input) => Console.log(input)
+   *   ).pipe(Command.provideEffectDiscard(intro))
+   *
+   *   yield* Command.run(demo, { version: "1.0.0" })
+   * })
+   * ```
+   *
    * @stability unstable
    * @category combinators
    * @since 4.0.0
@@ -1320,6 +1418,7 @@ export const map: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -1365,6 +1464,7 @@ export const mapEffect: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1410,6 +1510,7 @@ export const mapEffect: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1463,6 +1564,7 @@ export const mapEffect: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -1520,6 +1622,7 @@ export const mapTryCatch: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1577,6 +1680,7 @@ export const mapTryCatch: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -2146,6 +2250,7 @@ export const orElse: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -2194,6 +2299,7 @@ export const orElseResult: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -2242,6 +2348,7 @@ export const orElseResult: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void

package/src/cli/HelpDoc.ts

@@ -82,10 +82,27 @@ export interface HelpDoc {
   readonly flags: ReadonlyArray<FlagDoc>
 
   /**
-   * Global flags available to all commands (e.g., --help, --version).
+   * Shared flags inherited from ancestor commands.
+   */
+  readonly inheritedFlags?: ReadonlyArray<FlagDoc>
+
+  /**
+   * Global flags active at this command, including built-ins (e.g., --help).
    */
   readonly globalFlags?: ReadonlyArray<FlagDoc>
 
+  /**
+   * Root-to-command path of the nearest ancestor (or this command) declaring
+   * global flags. Defaults to the root for built-ins.
+   */
+  readonly globalFlagsScope?: ReadonlyArray<string>
+
+  /**
+   * Command names from the root command to this command, e.g.
+   * `["myapp", "deploy"]`.
+   */
+  readonly commandPath?: ReadonlyArray<string>
+
   /**
    * Custom command annotations.
    */