effect 4.0.0-beta.14 → 4.0.0-beta.15

package/src/unstable/cli/Command.ts

@@ -6,7 +6,7 @@ import * as Console from "../../Console.ts"
 import * as Effect from "../../Effect.ts"
 import type * as FileSystem from "../../FileSystem.ts"
 import { dual } from "../../Function.ts"
-import * as Layer from "../../Layer.ts"
+import type * as Layer from "../../Layer.ts"
 import * as Option from "../../Option.ts"
 import type * as Path from "../../Path.ts"
 import type { Pipeable } from "../../Pipeable.ts"
@@ -22,7 +22,7 @@ import * as CliOutput from "./CliOutput.ts"
 import * as GlobalFlag from "./GlobalFlag.ts"
 import { checkForDuplicateFlags, makeCommand, toImpl, TypeId } from "./internal/command.ts"
 import { parseConfig } from "./internal/config.ts"
-import { getHelpForCommandPath } from "./internal/help.ts"
+import { getGlobalFlagsForCommandPath, getGlobalFlagsForCommandTree, getHelpForCommandPath } from "./internal/help.ts"
 import * as Lexer from "./internal/lexer.ts"
 import * as Parser from "./internal/parser.ts"
 import * as Param from "./Param.ts"
@@ -588,7 +588,7 @@ export const make: {
     name: Name,
     config: Config,
     handler: (config: Command.Config.Infer<Config>) => Effect.Effect<void, E, R>
-  ): Command<Name, Command.Config.Infer<Config>, E, R>
+  ): Command<Name, Command.Config.Infer<Config>, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>
 } = ((
   name: string,
   config?: Command.Config,
@@ -661,7 +661,7 @@ export const withHandler: {
    */
   <A, R, E>(handler: (value: A) => Effect.Effect<void, E, R>): <Name extends string, XR, XE>(
     self: Command<Name, A, XE, XR>
-  ) => Command<Name, A, E, R>
+  ) => Command<Name, A, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>
   /* ========================================================================== */
   /* Combinators                                                                */
   /* ========================================================================== */
@@ -693,11 +693,12 @@ export const withHandler: {
   <Name extends string, A, XR, XE, R, E>(
     self: Command<Name, A, XE, XR>,
     handler: (value: A) => Effect.Effect<void, E, R>
-  ): Command<Name, A, E, R>
+  ): Command<Name, A, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>
 } = dual(2, <Name extends string, A, XR, XE, R, E>(
   self: Command<Name, A, XE, XR>,
   handler: (value: A) => Effect.Effect<void, E, R>
-): Command<Name, A, E, R> => makeCommand({ ...toImpl(self), handle: handler }))
+): Command<Name, A, E, Exclude<R, GlobalFlag.BuiltInSettingContext>> =>
+  makeCommand({ ...toImpl(self), handle: handler }))
 
 interface SubcommandGroupInternal {
   readonly group: string | undefined
@@ -942,6 +943,7 @@ export const withSubcommands: {
     shortDescription: impl.shortDescription,
     alias: impl.alias,
     annotations: impl.annotations,
+    globalFlags: impl.globalFlags,
     examples: impl.examples,
     service: impl.service,
     subcommands: normalized.groups,
@@ -950,7 +952,50 @@ export const withSubcommands: {
   })
 })
 
+/**
+ * Declares global flags for a command scope.
+ *
+ * Declared global flags apply to the command and all of its descendants.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withGlobalFlags: {
+  /**
+   * Declares global flags for a command scope.
+   *
+   * Declared global flags apply to the command and all of its descendants.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <const GlobalFlags extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>>(globalFlags: GlobalFlags): <Name extends string, Input, E, R>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, Exclude<R, ExtractGlobalFlagContext<GlobalFlags>>>
+  /**
+   * Declares global flags for a command scope.
+   *
+   * Declared global flags apply to the command and all of its descendants.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <Name extends string, Input, E, R, const GlobalFlags extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>>(self: Command<Name, Input, E, R>, globalFlags: GlobalFlags): Command<Name, Input, E, Exclude<R, ExtractGlobalFlagContext<GlobalFlags>>>
+} = dual(
+  2,
+  <Name extends string, Input, E, R, const GlobalFlags extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>>(
+    self: Command<Name, Input, E, R>,
+    globalFlags: GlobalFlags
+  ): Command<Name, Input, E, Exclude<R, ExtractGlobalFlagContext<GlobalFlags>>> => {
+    const impl = toImpl(self)
+    const next = Array.from(new Set([...impl.globalFlags, ...globalFlags]))
+    return makeCommand({ ...impl, globalFlags: next })
+  }
+)
+
 // Type extractors for subcommand arrays - T[number] gives union of all elements
+type ExtractGlobalFlagContext<T extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>> = T[number] extends
+  GlobalFlag.Setting<infer Id, any> ? GlobalFlag.Setting.Identifier<Id> : never
 type ExtractSubcommand<T> = T extends Command<any, any, any, any> ? T
   : T extends Command.SubcommandGroup<infer Commands> ? Commands[number]
   : never
@@ -1534,6 +1579,45 @@ export const provideEffectDiscard: {
 /* Execution                                                                  */
 /* ========================================================================== */
 
+const getOutOfScopeGlobalFlagErrors = (
+  allFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>,
+  activeFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>,
+  flagMap: Record<string, ReadonlyArray<string>>,
+  commandPath: ReadonlyArray<string>
+): ReadonlyArray<CliError.CliError> => {
+  const activeSet = new Set(activeFlags)
+  const errors: Array<CliError.CliError> = []
+  const seen = new Set<string>()
+
+  for (const flag of allFlags) {
+    if (activeSet.has(flag)) {
+      continue
+    }
+
+    const singles = Param.extractSingleParams(flag.flag)
+    for (const single of singles) {
+      const entries = flagMap[single.name]
+      if (!entries || entries.length === 0) {
+        continue
+      }
+      const option = `--${single.name}`
+      if (seen.has(option)) {
+        continue
+      }
+      seen.add(option)
+      errors.push(
+        new CliError.UnrecognizedOption({
+          option,
+          suggestions: [],
+          command: commandPath
+        })
+      )
+    }
+  }
+
+  return errors
+}
+
 const showHelp = <Name extends string, Input, E, R>(
   command: Command<Name, Input, E, R>,
   commandPath: ReadonlyArray<string>,
@@ -1541,7 +1625,7 @@ const showHelp = <Name extends string, Input, E, R>(
 ): Effect.Effect<void, never, Environment> =>
   Effect.gen(function*() {
     const formatter = yield* CliOutput.Formatter
-    const helpDoc = yield* getHelpForCommandPath(command, commandPath, GlobalFlag.Registry)
+    const helpDoc = yield* getHelpForCommandPath(command, commandPath, GlobalFlag.BuiltIns)
     yield* Console.log(formatter.formatHelpDoc(helpDoc))
     if (errors && errors.length > 0) {
       yield* Console.error(formatter.formatErrors(errors))
@@ -1698,11 +1782,11 @@ export const runWith = <const Name extends string, Input, E, R>(
     function*(args: ReadonlyArray<string>) {
       const { tokens, trailingOperands } = Lexer.lex(args)
 
-      // 1. Read global flags from registry
-      const flags = Array.from(yield* GlobalFlag.Registry)
+      // 1. Collect known global flags from the command tree
+      const allFlags = getGlobalFlagsForCommandTree(command, GlobalFlag.BuiltIns)
 
       // 2. Extract global flag tokens
-      const allFlagParams = flags.flatMap((f) => Param.extractSingleParams(f.flag))
+      const allFlagParams = allFlags.flatMap((f) => Param.extractSingleParams(f.flag))
       const globalRegistry = Parser.createFlagRegistry(allFlagParams.filter(Param.isFlagParam))
       const { flagMap, remainder } = Parser.consumeKnownFlags(tokens, globalRegistry)
       const emptyArgs: Param.ParsedArgs = { flags: flagMap, arguments: [] }
@@ -1711,9 +1795,17 @@ export const runWith = <const Name extends string, Input, E, R>(
       const parsedArgs = yield* Parser.parseArgs({ tokens: remainder, trailingOperands }, command)
       const commandPath = [command.name, ...Parser.getCommandPath(parsedArgs)] as const
       const handlerCtx: GlobalFlag.HandlerContext = { command, commandPath, version: config.version }
+      const activeFlags = getGlobalFlagsForCommandPath(command, commandPath, GlobalFlag.BuiltIns)
 
-      // 4. Process action flags — first present action wins, then exit
-      for (const flag of flags) {
+      // 4. Reject globals that were passed outside the active command scope
+      const outOfScopeErrors = getOutOfScopeGlobalFlagErrors(allFlags, activeFlags, flagMap, commandPath)
+      if (outOfScopeErrors.length > 0) {
+        const parseErrors = parsedArgs.errors ?? []
+        return yield* showHelp(command, commandPath, [...outOfScopeErrors, ...parseErrors])
+      }
+
+      // 5. Process action flags — first present action wins, then exit
+      for (const flag of activeFlags) {
         if (flag._tag !== "Action") continue
         const singles = Param.extractSingleParams(flag.flag)
         const hasEntry = singles.some((s) => {
@@ -1726,7 +1818,7 @@ export const runWith = <const Name extends string, Input, E, R>(
         return
       }
 
-      // 5. Handle parsing errors
+      // 6. Handle parsing errors
       if (parsedArgs.errors && parsedArgs.errors.length > 0) {
         return yield* showHelp(command, commandPath, parsedArgs.errors)
       }
@@ -1735,29 +1827,25 @@ export const runWith = <const Name extends string, Input, E, R>(
         return yield* showHelp(command, commandPath, [parseResult.failure])
       }
 
-      // 6. Provide setting values
-      let contextLayer: Layer.Layer<never> = Layer.empty
-      for (const flag of flags) {
+      // 7. Provide setting values
+      let program = commandImpl.handle(parseResult.success, [command.name])
+      for (const flag of activeFlags) {
         if (flag._tag !== "Setting") continue
         const [, value] = yield* flag.flag.parse(emptyArgs)
-        contextLayer = Layer.merge(contextLayer, Layer.succeed(flag, value))
+        program = Effect.provideService(program, flag, value)
       }
 
-      // 7. Apply built-in setting behavior
-      if (flags.includes(GlobalFlag.LogLevel)) {
-        const [, logLevel] = yield* GlobalFlag.LogLevel.flag.parse(emptyArgs)
-        contextLayer = Layer.merge(
-          contextLayer,
-          Option.match(logLevel, {
-            onNone: () => Layer.empty,
-            onSome: (level) => Layer.succeed(References.MinimumLogLevel, level)
-          })
-        )
-      }
+      const [, logLevel] = yield* GlobalFlag.LogLevel.flag.parse(emptyArgs)
+      program = Effect.provideService(program, GlobalFlag.LogLevel, logLevel)
+
+      // 8. Apply built-in setting behavior
+      const services = Option.match(logLevel, {
+        onNone: () => ServiceMap.empty(),
+        onSome: (level) => ServiceMap.make(References.MinimumLogLevel, level)
+      })
 
-      // 8. Run command handler with composed context
-      const program = commandImpl.handle(parseResult.success, [command.name])
-      yield* Effect.provide(program, contextLayer)
+      // 9. Run command handler with composed context
+      yield* Effect.provideServices(program, services)
     },
     Effect.catchIf(
       ((error: any) =>

package/src/unstable/cli/GlobalFlag.ts

@@ -4,7 +4,6 @@
 
 import * as Console from "../../Console.ts"
 import * as Effect from "../../Effect.ts"
-import { dual } from "../../Function.ts"
 import type { LogLevel as LogLevelType } from "../../LogLevel.ts"
 import * as Option from "../../Option.ts"
 import * as ServiceMap from "../../ServiceMap.ts"
@@ -49,18 +48,30 @@ export interface Action<A> {
  * @since 4.0.0
  * @category models
  */
-export interface Setting<A> extends ServiceMap.Reference<A> {
+export interface Setting<Id extends string, A> extends ServiceMap.Service<Setting.Identifier<Id>, A> {
   readonly _tag: "Setting"
+  readonly id: Id
   readonly flag: Flag.Flag<A>
 }
 
+/**
+ * @since 4.0.0
+ */
+export declare namespace Setting {
+  /**
+   * @since 4.0.0
+   * @category models
+   */
+  export type Identifier<Id extends string> = `effect/unstable/cli/GlobalFlag/${Id}`
+}
+
 /**
  * Global flag discriminated union.
  *
  * @since 4.0.0
  * @category models
  */
-export type GlobalFlag<A> = Action<A> | Setting<A>
+export type GlobalFlag<A> = Action<A> | Setting<any, A>
 
 /* ========================================================================== */
 /* Constructors                                                               */
@@ -90,17 +101,19 @@ export const action = <A>(options: {
  * @since 4.0.0
  * @category constructors
  */
-export const setting = <A>(options: {
+export const setting = <const Id extends string>(
+  id: Id
+) =>
+<A>(options: {
   readonly flag: Flag.Flag<A>
-  readonly defaultValue: () => A
-}): Setting<A> => {
+}): Setting<Id, A> => {
   settingIdCounter += 1
-  const ref = ServiceMap.Reference<A>(
-    `effect/cli/GlobalFlag/Setting/${settingIdCounter}`,
-    { defaultValue: options.defaultValue }
+  const ref = ServiceMap.Service<Setting.Identifier<Id>, A>(
+    `effect/unstable/cli/GlobalFlag/${id}/${settingIdCounter}`
   )
   return Object.assign(ref, {
     _tag: "Setting" as const,
+    id,
     flag: options.flag
   })
 }
@@ -130,7 +143,7 @@ export const Help: Action<boolean> = action({
   run: (_, { command, commandPath }) =>
     Effect.gen(function*() {
       const formatter = yield* CliOutput.Formatter
-      const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, Registry)
+      const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, BuiltIns)
       yield* Console.log(formatter.formatHelpDoc(helpDoc))
     })
 })
@@ -184,7 +197,7 @@ export const Completions: Action<Option.Option<"bash" | "zsh" | "fish">> = actio
  * @since 4.0.0
  * @category references
  */
-export const LogLevel: Setting<Option.Option<LogLevelType>> = setting({
+export const LogLevel: Setting<"log-level", Option.Option<LogLevelType>> = setting("log-level")({
   flag: Flag.choiceWithValue(
     "log-level",
     [
@@ -201,121 +214,30 @@ export const LogLevel: Setting<Option.Option<LogLevelType>> = setting({
   ).pipe(
     Flag.optional,
     Flag.withDescription("Sets the minimum log level")
-  ),
-  defaultValue: () => Option.none()
+  )
 })
 
 /* ========================================================================== */
-/* Registry                                                                   */
+/* References                                                                 */
 /* ========================================================================== */
 
 /**
- * The ordered set of global flag references.
- * The parser iterates this set to know which flags to extract.
+ * Built-in global flags in default precedence order.
  *
  * @since 4.0.0
  * @category references
  */
-export const Registry: ServiceMap.Reference<
-  Set<GlobalFlag<any>>
-> = ServiceMap.Reference("effect/cli/GlobalFlag/Registry", {
-  defaultValue: () =>
-    new Set<GlobalFlag<any>>([
-      Help,
-      Version,
-      Completions,
-      LogLevel
-    ])
-})
-
-/* ========================================================================== */
-/* Public API                                                                 */
-/* ========================================================================== */
+export const BuiltIns: ReadonlyArray<GlobalFlag<any>> = [
+  Help,
+  Version,
+  Completions,
+  LogLevel
+]
 
 /**
- * Adds a global flag to the registry.
+ * Built-in setting context identifiers.
  *
  * @since 4.0.0
- * @category modifiers
- */
-export const add: {
-  /* ========================================================================== */
-  /* Public API                                                                 */
-  /* ========================================================================== */
-
-  /**
-   * Adds a global flag to the registry.
-   *
-   * @since 4.0.0
-   * @category modifiers
-   */
-  <A>(flag: GlobalFlag<A>): <B, E, R>(
-    self: Effect.Effect<B, E, R>
-  ) => Effect.Effect<B, E, R>
-  /* ========================================================================== */
-  /* Public API                                                                 */
-  /* ========================================================================== */
-
-  /**
-   * Adds a global flag to the registry.
-   *
-   * @since 4.0.0
-   * @category modifiers
-   */
-  <B, E, R, A>(self: Effect.Effect<B, E, R>, flag: GlobalFlag<A>): Effect.Effect<B, E, R>
-} = dual(
-  2,
-  Effect.fnUntraced(function*<B, E, R, A>(
-    self: Effect.Effect<B, E, R>,
-    flag: GlobalFlag<A>
-  ) {
-    const currentRegistry = yield* Registry
-    const nextRegistry = new Set([...currentRegistry, flag])
-    return yield* Effect.provideService(self, Registry, nextRegistry)
-  })
-)
-
-/**
- * Removes a global flag by its reference.
- *
- * @since 4.0.0
- * @category modifiers
- */
-export const remove: {
-  /**
-   * Removes a global flag by its reference.
-   *
-   * @since 4.0.0
-   * @category modifiers
-   */
-  <A>(flag: GlobalFlag<A>): <B, E, R>(
-    self: Effect.Effect<B, E, R>
-  ) => Effect.Effect<B, E, R>
-  /**
-   * Removes a global flag by its reference.
-   *
-   * @since 4.0.0
-   * @category modifiers
-   */
-  <B, E, R, A>(self: Effect.Effect<B, E, R>, flag: GlobalFlag<A>): Effect.Effect<B, E, R>
-} = dual(
-  2,
-  Effect.fnUntraced(function*<B, E, R, A>(
-    self: Effect.Effect<B, E, R>,
-    flag: GlobalFlag<A>
-  ) {
-    const currentRegistry = yield* Registry
-    const nextRegistry = new Set(currentRegistry)
-    nextRegistry.delete(flag)
-    return yield* Effect.provideService(self, Registry, nextRegistry)
-  })
-)
-
-/**
- * Removes all global flags (built-in and user-defined).
- *
- * @since 4.0.0
- * @category modifiers
+ * @category models
  */
-export const clear = <B, E, R>(self: Effect.Effect<B, E, R>): Effect.Effect<B, E, R> =>
-  Effect.provideService(self, Registry, new Set())
+export type BuiltInSettingContext = Setting.Identifier<"log-level">

package/src/unstable/cli/internal/command.ts

@@ -12,6 +12,7 @@ import { pipeArguments } from "../../../Pipeable.ts"
 import * as Predicate from "../../../Predicate.ts"
 import * as ServiceMap from "../../../ServiceMap.ts"
 import * as CliError from "../CliError.ts"
+import type * as GlobalFlag from "../GlobalFlag.ts"
 import type { ArgDoc, ExampleDoc, FlagDoc, HelpDoc, SubcommandGroupDoc } from "../HelpDoc.ts"
 import * as Param from "../Param.ts"
 import * as Primitive from "../Primitive.ts"
@@ -36,6 +37,7 @@ export interface CommandInternal<Name extends string, Input, E, R> extends Comma
   readonly config: ConfigInternal
   readonly service: ServiceMap.Service<CommandContext<Name>, Input>
   readonly annotations: ServiceMap.ServiceMap<never>
+  readonly globalFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
   readonly parse: (input: ParsedTokens) => Effect.Effect<Input, CliError.CliError, Environment>
   readonly handle: (
     input: Input,
@@ -88,6 +90,7 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
   readonly config: ConfigInternal
   readonly service?: ServiceMap.Service<CommandContext<Name>, Input> | undefined
   readonly annotations?: ServiceMap.ServiceMap<never> | undefined
+  readonly globalFlags?: ReadonlyArray<GlobalFlag.GlobalFlag<any>> | undefined
   readonly description?: string | undefined
   readonly shortDescription?: string | undefined
   readonly alias?: string | undefined
@@ -101,6 +104,7 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
   const service = options.service ?? ServiceMap.Service<CommandContext<Name>, Input>(`${TypeId}/${options.name}`)
   const config = options.config
   const annotations = options.annotations ?? ServiceMap.empty()
+  const globalFlags = options.globalFlags ?? []
   const subcommands = options.subcommands ?? []
 
   const handle = (
@@ -191,6 +195,7 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
     name: options.name,
     examples: options.examples ?? [],
     annotations,
+    globalFlags,
     subcommands,
     config,
     service,

package/src/unstable/cli/internal/help.ts

@@ -6,46 +6,127 @@
  * Extracted from command.ts to avoid circular dependencies.
  */
 import * as Effect from "../../../Effect.ts"
-import type * as ServiceMap from "../../../ServiceMap.ts"
 import type { Command } from "../Command.ts"
-import type { GlobalFlag } from "../GlobalFlag.ts"
+import type * as GlobalFlag from "../GlobalFlag.ts"
 import type { FlagDoc, HelpDoc } from "../HelpDoc.ts"
 import * as Param from "../Param.ts"
 import * as Primitive from "../Primitive.ts"
 import { toImpl } from "./command.ts"
 
+const dedupeGlobalFlags = (
+  flags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
+): ReadonlyArray<GlobalFlag.GlobalFlag<any>> => {
+  const seen = new Set<GlobalFlag.GlobalFlag<any>>()
+  const deduped: Array<GlobalFlag.GlobalFlag<any>> = []
+  for (const flag of flags) {
+    if (seen.has(flag)) {
+      continue
+    }
+    seen.add(flag)
+    deduped.push(flag)
+  }
+  return deduped
+}
+
 /**
- * Helper function to get help documentation for a specific command path.
- * Navigates through the command hierarchy to find the right command.
- * Reads global flags from the registry and includes them in the help doc.
+ * Returns the resolved command lineage for the provided path.
+ * Includes the root command as the first element.
  */
-export const getHelpForCommandPath = <Name extends string, Input, E, R>(
+export const getCommandsForCommandPath = <Name extends string, Input, E, R>(
   command: Command<Name, Input, E, R>,
-  commandPath: ReadonlyArray<string>,
-  registry: ServiceMap.Reference<Set<GlobalFlag<unknown>>>
-): Effect.Effect<HelpDoc, never, never> =>
-  Effect.gen(function*() {
-    let currentCommand: Command.Any = command
+  commandPath: ReadonlyArray<string>
+): ReadonlyArray<Command.Any> => {
+  const commands: Array<Command.Any> = [command]
+  let currentCommand: Command.Any = command
 
-    for (let i = 1; i < commandPath.length; i++) {
-      const subcommandName = commandPath[i]
-      let subcommand: Command.Any | undefined = undefined
+  for (let i = 1; i < commandPath.length; i++) {
+    const subcommandName = commandPath[i]
+    let subcommand: Command.Any | undefined = undefined
 
-      for (const group of currentCommand.subcommands) {
-        subcommand = group.commands.find((sub) => sub.name === subcommandName)
-        if (subcommand) {
-          break
-        }
+    for (const group of currentCommand.subcommands) {
+      subcommand = group.commands.find((sub) => sub.name === subcommandName)
+      if (subcommand) {
+        break
       }
+    }
 
-      if (subcommand) {
-        currentCommand = subcommand
+    if (!subcommand) {
+      break
+    }
+
+    commands.push(subcommand)
+    currentCommand = subcommand
+  }
+
+  return commands
+}
+
+/**
+ * Returns active global flags for a command path.
+ * Built-ins are prepended and declarations are collected root -> leaf.
+ */
+export const getGlobalFlagsForCommandPath = <Name extends string, Input, E, R>(
+  command: Command<Name, Input, E, R>,
+  commandPath: ReadonlyArray<string>,
+  builtIns: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
+): ReadonlyArray<GlobalFlag.GlobalFlag<any>> => {
+  const commands = getCommandsForCommandPath(command, commandPath)
+  const declared = commands.flatMap((current) => toImpl(current).globalFlags)
+  return dedupeGlobalFlags([
+    ...builtIns,
+    ...declared
+  ])
+}
+
+const collectDeclaredGlobalFlags = (command: Command.Any): ReadonlyArray<GlobalFlag.GlobalFlag<any>> => {
+  const collected: Array<GlobalFlag.GlobalFlag<any>> = []
+
+  const visit = (current: Command.Any): void => {
+    const impl = toImpl(current)
+    for (const flag of impl.globalFlags) {
+      collected.push(flag)
+    }
+    for (const group of current.subcommands) {
+      for (const subcommand of group.commands) {
+        visit(subcommand)
       }
     }
+  }
+
+  visit(command)
+  return dedupeGlobalFlags(collected)
+}
+
+/**
+ * Returns all global flags declared in a command tree.
+ * Built-ins are prepended and command declarations are deduplicated by identity.
+ */
+export const getGlobalFlagsForCommandTree = <Name extends string, Input, E, R>(
+  command: Command<Name, Input, E, R>,
+  builtIns: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
+): ReadonlyArray<GlobalFlag.GlobalFlag<any>> =>
+  dedupeGlobalFlags([
+    ...builtIns,
+    ...collectDeclaredGlobalFlags(command)
+  ])
+
+/**
+ * Helper function to get help documentation for a specific command path.
+ * Navigates through the command hierarchy to find the right command.
+ * Reads active global flags for the path and includes them in the help doc.
+ */
+export const getHelpForCommandPath = <Name extends string, Input, E, R>(
+  command: Command<Name, Input, E, R>,
+  commandPath: ReadonlyArray<string>,
+  builtIns: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
+): Effect.Effect<HelpDoc, never, never> =>
+  Effect.gen(function*() {
+    const commands = getCommandsForCommandPath(command, commandPath)
+    const currentCommand = commands.length > 0 ? commands[commands.length - 1] : command
 
     const baseDoc = toImpl(currentCommand).buildHelpDoc(commandPath)
 
-    const flags = yield* registry
+    const flags = getGlobalFlagsForCommandPath(command, commandPath, builtIns)
     const globalFlagDocs: Array<FlagDoc> = []
     for (const flag of flags) {
       const singles = Param.extractSingleParams(flag.flag)