effect 4.0.0-beta.6 → 4.0.0-beta.62

package/src/unstable/cli/Command.ts

@@ -1,29 +1,32 @@
 /**
  * @since 4.0.0
  */
+import type { NonEmptyArray, NonEmptyReadonlyArray } from "../../Array.ts"
 import * as Console from "../../Console.ts"
+import * as Context from "../../Context.ts"
 import * as Effect from "../../Effect.ts"
 import type * as FileSystem from "../../FileSystem.ts"
 import { dual } from "../../Function.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"
 import * as Predicate from "../../Predicate.ts"
 import * as References from "../../References.ts"
 import * as Result from "../../Result.ts"
-import type * as ServiceMap from "../../ServiceMap.ts"
+import * as Stdio from "../../Stdio.ts"
 import * as Terminal from "../../Terminal.ts"
-import type { Simplify } from "../../Types.ts"
+import type { NoInfer, Simplify } from "../../Types.ts"
 import type { ChildProcessSpawner } from "../process/ChildProcessSpawner.ts"
 import * as CliError from "./CliError.ts"
 import * as CliOutput from "./CliOutput.ts"
-import { checkForDuplicateFlags, getHelpForCommandPath, makeCommand, toImpl, TypeId } from "./internal/command.ts"
-import * as CommandDescriptor from "./internal/completions/CommandDescriptor.ts"
-import * as Completions from "./internal/completions/Completions.ts"
-import { parseConfig } from "./internal/config.ts"
+import * as GlobalFlag from "./GlobalFlag.ts"
+import { checkForDuplicateFlags, makeCommand, makeParser, toImpl, TypeId } from "./internal/command.ts"
+import { mergeConfig, parseConfig } from "./internal/config.ts"
+import { getGlobalFlagsForCommandPath, getGlobalFlagsForCommandTree, getHelpForCommandPath } from "./internal/help.ts"
 import * as Lexer from "./internal/lexer.ts"
 import * as Parser from "./internal/parser.ts"
-import type * as Param from "./Param.ts"
+import * as Param from "./Param.ts"
 
 /* ========================================================================== */
 /* Public Types                                                               */
@@ -44,7 +47,7 @@ import type * as Param from "./Param.ts"
  * import { Argument, Command, Flag } from "effect/unstable/cli"
  *
  * // Simple command with no configuration
- * const version: Command.Command<"version", {}, never, never> = Command.make(
+ * const version: Command.Command<"version", {}, {}, never, never> = Command.make(
  *   "version"
  * )
  *
@@ -56,6 +59,7 @@ import type * as Param from "./Param.ts"
  *     readonly force: boolean
  *     readonly files: ReadonlyArray<string>
  *   },
+ *   {},
  *   never,
  *   never
  * > = Command.make("deploy", {
@@ -73,14 +77,15 @@ import type * as Param from "./Param.ts"
  * @since 4.0.0
  * @category models
  */
-export interface Command<Name extends string, Input, E = never, R = never> extends
-  Pipeable,
-  Effect.Yieldable<
-    Command<Name, Input, E, R>,
-    Input,
-    never,
-    CommandContext<Name>
-  >
+export interface Command<Name extends string, Input, ContextInput = {}, E = never, R = never>
+  extends
+    Pipeable,
+    Effect.Yieldable<
+      Command<Name, Input, ContextInput, E, R>,
+      ContextInput,
+      never,
+      CommandContext<Name>
+    >
 {
   readonly [TypeId]: typeof TypeId
 
@@ -94,16 +99,50 @@ export interface Command<Name extends string, Input, E = never, R = never> exten
    */
   readonly description: string | undefined
 
+  /**
+   * An optional short description used when listing subcommands.
+   */
+  readonly shortDescription: string | undefined
+
+  /**
+   * An optional alias that can be used as a shorter command name.
+   */
+  readonly alias: string | undefined
+
+  /**
+   * Optional usage examples for the command.
+   */
+  readonly examples: ReadonlyArray<Command.Example>
+
   /**
    * The subcommands available under this command.
    */
-  readonly subcommands: ReadonlyArray<Command.Any>
+  readonly subcommands: ReadonlyArray<{
+    readonly group: string | undefined
+    readonly commands: NonEmptyReadonlyArray<Command.Any>
+  }>
+
+  /**
+   * Custom annotations associated with this command.
+   */
+  readonly annotations: Context.Context<never>
 }
 
 /**
  * @since 4.0.0
  */
 export declare namespace Command {
+  /**
+   * Represents a concrete usage example for a command.
+   *
+   * @since 4.0.0
+   * @category models
+   */
+  export interface Example {
+    readonly command: string
+    readonly description?: string | undefined
+  }
+
   /**
    * Configuration object for defining command flags, arguments, and nested structures.
    *
@@ -147,6 +186,21 @@ export declare namespace Command {
       | Config
   }
 
+  /**
+   * Configuration shape accepted by `Command.withSharedFlags`.
+   *
+   * Only flags are allowed here; arguments are intentionally excluded.
+   *
+   * @since 4.0.0
+   * @category models
+   */
+  export interface FlagConfig {
+    readonly [key: string]:
+      | Param.Param<typeof Param.flagKind, any>
+      | ReadonlyArray<Param.Param<typeof Param.flagKind, any> | FlagConfig>
+      | FlagConfig
+  }
+
   /**
    * Utilities for working with command configurations.
    *
@@ -208,7 +262,26 @@ export declare namespace Command {
    * @since 4.0.0
    * @category models
    */
-  export type Any = Command<string, unknown, unknown, unknown>
+  export type Any = Command<string, unknown, unknown, unknown, unknown>
+
+  /**
+   * A grouped set of subcommands used by `Command.withSubcommands`.
+   *
+   * @since 4.0.0
+   * @category models
+   */
+  export interface SubcommandGroup<Commands extends ReadonlyArray<Any> = ReadonlyArray<Any>> {
+    readonly group: string
+    readonly commands: Commands
+  }
+
+  /**
+   * Entry type accepted by `Command.withSubcommands`.
+   *
+   * @since 4.0.0
+   * @category models
+   */
+  export type SubcommandEntry = Any | SubcommandGroup<ReadonlyArray<Any>>
 }
 
 /**
@@ -217,7 +290,7 @@ export declare namespace Command {
  * @since 4.0.0
  * @category utility types
  */
-export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal | ChildProcessSpawner
+export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal | ChildProcessSpawner | Stdio.Stdio
 
 /**
  * A utility type to extract the error type from a `Command`.
@@ -228,6 +301,7 @@ export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal
 export type Error<C> = C extends Command<
   infer _Name,
   infer _Input,
+  infer _ContextInput,
   infer _Error,
   infer _Requirements
 > ? _Error :
@@ -246,10 +320,12 @@ export type Error<C> = C extends Command<
  * import { Console, Effect } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
  *
- * const parent = Command.make("app", {
- *   verbose: Flag.boolean("verbose"),
- *   config: Flag.string("config")
- * })
+ * const parent = Command.make("app").pipe(
+ *   Command.withSharedFlags({
+ *     verbose: Flag.boolean("verbose"),
+ *     config: Flag.string("config")
+ *   })
+ * )
  *
  * const child = Command.make("deploy", {
  *   target: Flag.string("target")
@@ -283,11 +359,11 @@ export interface CommandContext<Name extends string> {
 export interface ParsedTokens {
   readonly flags: Record<string, ReadonlyArray<string>>
   readonly arguments: ReadonlyArray<string>
-  readonly errors?: ReadonlyArray<CliError.CliError>
-  readonly subcommand?: {
+  readonly errors?: ReadonlyArray<CliError.NonShowHelpErrors>
+  readonly subcommand: Option.Option<{
     readonly name: string
     readonly parsedInput: ParsedTokens
-  }
+  }>
 }
 
 /**
@@ -411,7 +487,7 @@ export const make: {
    * @since 4.0.0
    * @category constructors
    */
-  <Name extends string>(name: Name): Command<Name, {}, never, never>
+  <Name extends string>(name: Name): Command<Name, {}, {}, never, never>
 
   /* ========================================================================== */
   /* Constructors                                                               */
@@ -470,7 +546,7 @@ export const make: {
    * @since 4.0.0
    * @category constructors
    */
-  <Name extends string, const Config extends Command.Config>(name: Name, config: Config): Command<Name, Command.Config.Infer<Config>, never, never>
+  <Name extends string, const Config extends Command.Config>(name: Name, config: Config): Command<Name, Command.Config.Infer<Config>, {}, never, never>
 
   /* ========================================================================== */
   /* Constructors                                                               */
@@ -533,7 +609,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,
@@ -604,9 +680,9 @@ export const withHandler: {
    * @since 4.0.0
    * @category combinators
    */
-  <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>
+  <A, R, E>(handler: (value: A) => Effect.Effect<void, E, R>): <Name extends string, XR, XE, ContextInput>(
+    self: Command<Name, A, ContextInput, XE, XR>
+  ) => Command<Name, A, ContextInput, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>
   /* ========================================================================== */
   /* Combinators                                                                */
   /* ========================================================================== */
@@ -635,20 +711,72 @@ export const withHandler: {
    * @since 4.0.0
    * @category combinators
    */
-  <Name extends string, A, XR, XE, R, E>(
-    self: Command<Name, A, XE, XR>,
+  <Name extends string, A, XR, XE, R, E, ContextInput>(
+    self: Command<Name, A, ContextInput, XE, XR>,
     handler: (value: A) => Effect.Effect<void, E, R>
-  ): Command<Name, A, E, R>
-} = dual(2, <Name extends string, A, XR, XE, R, E>(
-  self: Command<Name, A, XE, XR>,
+  ): Command<Name, A, ContextInput, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>
+} = dual(2, <Name extends string, A, XR, XE, R, E, ContextInput>(
+  self: Command<Name, A, ContextInput, XE, XR>,
   handler: (value: A) => Effect.Effect<void, E, R>
-): Command<Name, A, E, R> => makeCommand({ ...toImpl(self), handle: handler }))
+): Command<Name, A, ContextInput, E, Exclude<R, GlobalFlag.BuiltInSettingContext>> =>
+  makeCommand({ ...toImpl(self), handle: handler }))
+
+interface SubcommandGroupInternal {
+  readonly group: string | undefined
+  readonly commands: NonEmptyReadonlyArray<Command.Any>
+}
+
+const normalizeSubcommandEntries = (
+  entries: ReadonlyArray<Command.SubcommandEntry>
+): {
+  readonly flat: ReadonlyArray<Command.Any>
+  readonly groups: ReadonlyArray<SubcommandGroupInternal>
+} => {
+  const flat: Array<Command.Any> = []
+  const grouped = new Map<string | undefined, NonEmptyArray<Command.Any>>()
+
+  const addToGroup = (group: string | undefined, command: Command.Any): void => {
+    flat.push(command)
+    const existing = grouped.get(group)
+    if (existing) {
+      existing.push(command)
+    } else {
+      grouped.set(group, [command])
+    }
+  }
+
+  for (const entry of entries) {
+    if (isCommand(entry)) {
+      addToGroup(undefined, entry)
+      continue
+    }
+    for (const command of entry.commands) {
+      addToGroup(entry.group, command)
+    }
+  }
+
+  const groups: Array<SubcommandGroupInternal> = []
+  const ungroupedCommands = grouped.get(undefined)
+
+  if (ungroupedCommands && ungroupedCommands.length > 0) {
+    groups.push({ group: undefined, commands: ungroupedCommands })
+  }
+
+  for (const [group, commands] of grouped) {
+    if (group === undefined) {
+      continue
+    }
+    groups.push({ group, commands })
+  }
+
+  return { flat, groups }
+}
 
 /**
  * Adds subcommands to a command, creating a hierarchical command structure.
  *
  * Subcommands can access their parent's parsed configuration by yielding the parent
- * command within their handler. This enables patterns like global flags that affect
+ * command within their handler. This enables shared parent flags that affect
  * all subcommands.
  *
  * @example
@@ -656,10 +784,12 @@ export const withHandler: {
  * import { Console, Effect } from "effect"
  * import { Command, Flag } from "effect/unstable/cli"
  *
- * // Parent command with global flags
- * const git = Command.make("git", {
- *   verbose: Flag.boolean("verbose")
- * })
+ * // Parent command with shared flags
+ * const git = Command.make("git").pipe(
+ *   Command.withSharedFlags({
+ *     verbose: Flag.boolean("verbose")
+ *   })
+ * )
  *
  * // Subcommand that accesses parent config
  * const clone = Command.make("clone", {
@@ -685,7 +815,7 @@ export const withSubcommands: {
    * Adds subcommands to a command, creating a hierarchical command structure.
    *
    * Subcommands can access their parent's parsed configuration by yielding the parent
-   * command within their handler. This enables patterns like global flags that affect
+   * command within their handler. This enables shared parent flags that affect
    * all subcommands.
    *
    * @example
@@ -693,10 +823,12 @@ export const withSubcommands: {
    * import { Console, Effect } from "effect"
    * import { Command, Flag } from "effect/unstable/cli"
    *
-   * // Parent command with global flags
-   * const git = Command.make("git", {
-   *   verbose: Flag.boolean("verbose")
-   * })
+   * // Parent command with shared flags
+   * const git = Command.make("git").pipe(
+   *   Command.withSharedFlags({
+   *     verbose: Flag.boolean("verbose")
+   *   })
+   * )
    *
    * // Subcommand that accesses parent config
    * const clone = Command.make("clone", {
@@ -717,11 +849,12 @@ export const withSubcommands: {
    * @since 4.0.0
    * @category combinators
    */
-  <const Subcommands extends ReadonlyArray<Command<any, any, any, any>>>(subcommands: Subcommands): <Name extends string, Input, E, R>(
-    self: Command<Name, Input, E, R>
+  <const Subcommands extends ReadonlyArray<Command.SubcommandEntry>>(subcommands: Subcommands): <Name extends string, Input, E, R, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>
   ) => Command<
     Name,
-    Input,
+    Simplify<Input | ContextInput>,
+    ContextInput,
     E | ExtractSubcommandErrors<Subcommands>,
     R | Exclude<ExtractSubcommandContext<Subcommands>, CommandContext<Name>>
   >
@@ -729,7 +862,7 @@ export const withSubcommands: {
    * Adds subcommands to a command, creating a hierarchical command structure.
    *
    * Subcommands can access their parent's parsed configuration by yielding the parent
-   * command within their handler. This enables patterns like global flags that affect
+   * command within their handler. This enables shared parent flags that affect
    * all subcommands.
    *
    * @example
@@ -737,10 +870,12 @@ export const withSubcommands: {
    * import { Console, Effect } from "effect"
    * import { Command, Flag } from "effect/unstable/cli"
    *
-   * // Parent command with global flags
-   * const git = Command.make("git", {
-   *   verbose: Flag.boolean("verbose")
-   * })
+   * // Parent command with shared flags
+   * const git = Command.make("git").pipe(
+   *   Command.withSharedFlags({
+   *     verbose: Flag.boolean("verbose")
+   *   })
+   * )
    *
    * // Subcommand that accesses parent config
    * const clone = Command.make("clone", {
@@ -766,10 +901,12 @@ export const withSubcommands: {
     Input,
     E,
     R,
-    const Subcommands extends ReadonlyArray<Command<any, any, any, any>>
-  >(self: Command<Name, Input, E, R>, subcommands: Subcommands): Command<
+    ContextInput,
+    const Subcommands extends ReadonlyArray<Command.SubcommandEntry>
+  >(self: Command<Name, Input, ContextInput, E, R>, subcommands: Subcommands): Command<
     Name,
-    Input,
+    Simplify<Input | ContextInput>,
+    ContextInput,
     E | ExtractSubcommandErrors<Subcommands>,
     R | Exclude<ExtractSubcommandContext<Subcommands>, CommandContext<Name>>
   >
@@ -778,71 +915,257 @@ export const withSubcommands: {
   Input,
   E,
   R,
-  const Subcommands extends ReadonlyArray<Command<any, any, any, any>>
+  ContextInput,
+  const Subcommands extends ReadonlyArray<Command.SubcommandEntry>
 >(
-  self: Command<Name, Input, E, R>,
+  self: Command<Name, Input, ContextInput, E, R>,
   subcommands: Subcommands
 ): Command<
   Name,
-  Input,
+  Simplify<Input | ContextInput>,
+  ContextInput,
   E | ExtractSubcommandErrors<Subcommands>,
   R | Exclude<ExtractSubcommandContext<Subcommands>, CommandContext<Name>>
 > => {
-  checkForDuplicateFlags(self, subcommands)
+  const normalized = normalizeSubcommandEntries(subcommands)
+  checkForDuplicateFlags(self, normalized.flat)
 
   const impl = toImpl(self)
-  const byName = new Map(subcommands.map((s) => [s.name, toImpl(s)] as const))
+  const byName = new Map(normalized.flat.map((s) => [s.name, toImpl(s)] as const))
 
-  // Internal type for routing - not exposed in public type
-  type SubcommandInfo = { readonly name: string; readonly result: unknown }
-  type InternalInput = Input & { readonly _subcommand?: SubcommandInfo }
+  type NextInput = Simplify<Input | ContextInput>
+  const SubcommandStateSymbol = Symbol("effect/cli/SubcommandState")
+  type SubcommandState = { readonly name: string; readonly result: unknown }
+  type InternalInput = NextInput & { readonly [SubcommandStateSymbol]?: SubcommandState }
 
   const parse = Effect.fnUntraced(function*(raw: ParsedTokens) {
-    const parent = yield* impl.parse(raw)
-
-    if (!raw.subcommand) {
-      return parent
+    if (Option.isNone(raw.subcommand)) {
+      return (yield* impl.parse(raw)) as NextInput
     }
 
-    const sub = byName.get(raw.subcommand.name)
+    const sub = byName.get(raw.subcommand.value.name)
     if (!sub) {
-      return parent
+      return (yield* impl.parse(raw)) as NextInput
     }
 
-    const result = yield* sub.parse(raw.subcommand.parsedInput)
-    // Attach subcommand info internally for routing
-    return Object.assign({}, parent, { _subcommand: { name: sub.name, result } }) as InternalInput
+    const context = yield* impl.parseContext(raw)
+    const result = yield* sub.parse(raw.subcommand.value.parsedInput)
+    return Object.assign({}, context, { [SubcommandStateSymbol]: { name: sub.name, result } }) as NextInput
   })
 
-  const handle = Effect.fnUntraced(function*(input: Input, path: ReadonlyArray<string>) {
+  const handle = Effect.fnUntraced(function*(input: NextInput, path: ReadonlyArray<string>) {
     const internal = input as InternalInput
-    if (internal._subcommand) {
-      const child = byName.get(internal._subcommand.name)
+    const selectedSubcommand = internal[SubcommandStateSymbol]
+
+    if (selectedSubcommand) {
+      const child = byName.get(selectedSubcommand.name)
       if (!child) {
-        return yield* new CliError.ShowHelp({ commandPath: path })
+        return yield* new CliError.ShowHelp({ commandPath: path, errors: [] })
       }
       return yield* child
-        .handle(internal._subcommand.result, [...path, child.name])
-        .pipe(Effect.provideService(impl.service, input))
+        .handle(selectedSubcommand.result, [...path, child.name])
+        .pipe(Effect.provideService(impl.service, input as unknown as ContextInput))
     }
-    return yield* impl.handle(input, path)
+    return yield* impl.handle(input as Input, path)
   })
 
   return makeCommand({
     name: impl.name,
     config: impl.config,
+    contextConfig: impl.contextConfig,
     description: impl.description,
+    shortDescription: impl.shortDescription,
+    alias: impl.alias,
+    annotations: impl.annotations,
+    globalFlags: impl.globalFlags,
+    examples: impl.examples,
     service: impl.service,
-    subcommands,
+    subcommands: normalized.groups,
     parse,
+    parseContext: impl.parseContext,
     handle
   })
 })
 
+/**
+ * Adds flags that are inherited by subcommands.
+ *
+ * Shared flags are available to this command's handler and to descendant
+ * handlers via `yield* parentCommand`. Shared flags are accepted both before
+ * and after a selected subcommand name (npm-style).
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withSharedFlags: {
+  /**
+   * Adds flags that are inherited by subcommands.
+   *
+   * Shared flags are available to this command's handler and to descendant
+   * handlers via `yield* parentCommand`. Shared flags are accepted both before
+   * and after a selected subcommand name (npm-style).
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <const SharedFlags extends Command.FlagConfig>(sharedFlags: SharedFlags): <Name extends string, Input, E, R, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<
+    Name,
+    Simplify<Input & Command.Config.Infer<SharedFlags>>,
+    Simplify<ContextInput & Command.Config.Infer<SharedFlags>>,
+    E,
+    R
+  >
+  /**
+   * Adds flags that are inherited by subcommands.
+   *
+   * Shared flags are available to this command's handler and to descendant
+   * handlers via `yield* parentCommand`. Shared flags are accepted both before
+   * and after a selected subcommand name (npm-style).
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <Name extends string, Input, E, R, ContextInput, const SharedFlags extends Command.FlagConfig>(self: Command<Name, Input, ContextInput, E, R>, sharedFlags: SharedFlags): Command<
+    Name,
+    Simplify<Input & Command.Config.Infer<SharedFlags>>,
+    Simplify<ContextInput & Command.Config.Infer<SharedFlags>>,
+    E,
+    R
+  >
+} = dual(
+  2,
+  <Name extends string, Input, E, R, ContextInput, const SharedFlags extends Command.FlagConfig>(
+    self: Command<Name, Input, ContextInput, E, R>,
+    sharedFlags: SharedFlags
+  ): Command<
+    Name,
+    Simplify<Input & Command.Config.Infer<SharedFlags>>,
+    Simplify<ContextInput & Command.Config.Infer<SharedFlags>>,
+    E,
+    R
+  > => {
+    const impl = toImpl(self)
+    const sharedConfig = parseConfig(sharedFlags)
+    const mergedConfig = mergeConfig(impl.config, sharedConfig)
+    const mergedContextConfig = mergeConfig(impl.contextConfig, sharedConfig)
+
+    if (impl.subcommands.length > 0) {
+      const flatSubcommands = impl.subcommands.flatMap((group) => group.commands)
+      checkForDuplicateFlags(self, flatSubcommands, { contextConfig: mergedContextConfig })
+    }
+
+    type SharedInput = Command.Config.Infer<SharedFlags>
+    type NextInput = Simplify<Input & SharedInput>
+    type NextContextInput = Simplify<ContextInput & SharedInput>
+
+    const parseShared = makeParser(sharedConfig) as (
+      input: ParsedTokens
+    ) => Effect.Effect<SharedInput, CliError.CliError, Environment>
+
+    const parse = Effect.fnUntraced(function*(raw: ParsedTokens) {
+      const base = yield* impl.parse(raw)
+      const shared = yield* parseShared(raw)
+      return Object.assign({}, base, shared) as NextInput
+    })
+
+    const parseContext = Effect.fnUntraced(function*(raw: ParsedTokens) {
+      const base = yield* impl.parseContext(raw)
+      const shared = yield* parseShared(raw)
+      return Object.assign({}, base, shared) as NextContextInput
+    })
+
+    const handle = (
+      input: NextInput,
+      commandPath: ReadonlyArray<string>
+    ) => impl.handle(input as Input, commandPath)
+
+    return makeCommand({
+      name: impl.name,
+      config: mergedConfig,
+      contextConfig: mergedContextConfig,
+      description: impl.description,
+      shortDescription: impl.shortDescription,
+      alias: impl.alias,
+      annotations: impl.annotations,
+      globalFlags: impl.globalFlags,
+      examples: impl.examples,
+      service: impl.service as Context.Key<CommandContext<Name>, NextContextInput>,
+      subcommands: impl.subcommands,
+      parse,
+      parseContext,
+      handle
+    })
+  }
+)
+
+/**
+ * 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, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<Name, Input, ContextInput, 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,
+    ContextInput,
+    const GlobalFlags extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>
+  >(self: Command<Name, Input, ContextInput, E, R>, globalFlags: GlobalFlags): Command<Name, Input, ContextInput, E, Exclude<R, ExtractGlobalFlagContext<GlobalFlags>>>
+} = dual(
+  2,
+  <
+    Name extends string,
+    Input,
+    E,
+    R,
+    ContextInput,
+    const GlobalFlags extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>
+  >(
+    self: Command<Name, Input, ContextInput, E, R>,
+    globalFlags: GlobalFlags
+  ): Command<Name, Input, ContextInput, 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 ExtractSubcommandErrors<T extends ReadonlyArray<Command<any, any, any, any>>> = Error<T[number]>
-type ExtractSubcommandContext<T extends ReadonlyArray<Command<any, any, any, any>>> = T[number] extends
-  Command<any, any, any, infer R> ? R : never
+type ExtractGlobalFlagContext<T extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>> = T[number] extends infer F
+  ? F extends GlobalFlag.Setting<infer Id, infer _A> ? GlobalFlag.Setting.Identifier<Id>
+  : never
+  : never
+type ExtractSubcommand<T> = T extends Command<infer _Name, infer _Input, infer _CI, infer _E, infer _R> ? T
+  : T extends Command.SubcommandGroup<infer Commands> ? Commands[number]
+  : never
+type ExtractSubcommandErrors<T extends ReadonlyArray<Command.SubcommandEntry>> = Error<ExtractSubcommand<T[number]>>
+type ExtractSubcommandContext<T extends ReadonlyArray<Command.SubcommandEntry>> = ExtractSubcommand<T[number]> extends
+  Command<infer _Name, infer _Input, infer _CI, infer _E, infer _R> ? _R : never
 
 /**
  * Sets the description for a command.
@@ -893,9 +1216,9 @@ export const withDescription: {
    * @since 4.0.0
    * @category combinators
    */
-  (description: string): <const Name extends string, Input, E, R>(
-    self: Command<Name, Input, E, R>
-  ) => Command<Name, Input, E, R>
+  (description: string): <const Name extends string, Input, E, R, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<Name, Input, ContextInput, E, R>
   /**
    * Sets the description for a command.
    *
@@ -920,21 +1243,244 @@ export const withDescription: {
    * @since 4.0.0
    * @category combinators
    */
-  <const Name extends string, Input, E, R>(self: Command<Name, Input, E, R>, description: string): Command<Name, Input, E, R>
-} = dual(2, <const Name extends string, Input, E, R>(
-  self: Command<Name, Input, E, R>,
+  <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>, description: string): Command<Name, Input, ContextInput, E, R>
+} = dual(2, <const Name extends string, Input, E, R, ContextInput>(
+  self: Command<Name, Input, ContextInput, E, R>,
   description: string
 ) => makeCommand({ ...toImpl(self), description }))
 
+/**
+ * Sets a short description for a command.
+ *
+ * Short descriptions are used when listing subcommands in help output and
+ * shell completions. If no short description is provided, the full
+ * `description` is used as a fallback.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withShortDescription: {
+  /**
+   * Sets a short description for a command.
+   *
+   * Short descriptions are used when listing subcommands in help output and
+   * shell completions. If no short description is provided, the full
+   * `description` is used as a fallback.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  (shortDescription: string): <const Name extends string, Input, E, R, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<Name, Input, ContextInput, E, R>
+  /**
+   * Sets a short description for a command.
+   *
+   * Short descriptions are used when listing subcommands in help output and
+   * shell completions. If no short description is provided, the full
+   * `description` is used as a fallback.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>, shortDescription: string): Command<Name, Input, ContextInput, E, R>
+} = dual(2, <const Name extends string, Input, E, R, ContextInput>(
+  self: Command<Name, Input, ContextInput, E, R>,
+  shortDescription: string
+) => makeCommand({ ...toImpl(self), shortDescription }))
+
+/**
+ * Sets an alias for a command.
+ *
+ * Aliases are accepted as alternate subcommand names during parsing and are
+ * shown in help output as `name, alias`.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withAlias: {
+  /**
+   * Sets an alias for a command.
+   *
+   * Aliases are accepted as alternate subcommand names during parsing and are
+   * shown in help output as `name, alias`.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  (alias: string): <const Name extends string, Input, E, R, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<Name, Input, ContextInput, E, R>
+  /**
+   * Sets an alias for a command.
+   *
+   * Aliases are accepted as alternate subcommand names during parsing and are
+   * shown in help output as `name, alias`.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>, alias: string): Command<Name, Input, ContextInput, E, R>
+} = dual(2, <const Name extends string, Input, E, R, ContextInput>(
+  self: Command<Name, Input, ContextInput, E, R>,
+  alias: string
+) => makeCommand({ ...toImpl(self), alias }))
+
+/**
+ * Adds a custom annotation to a command.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const annotate: {
+  /**
+   * Adds a custom annotation to a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <I, S>(service: Context.Key<I, S>, value: NoInfer<S>): <Name extends string, Input, E, R, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<Name, Input, ContextInput, E, R>
+  /**
+   * Adds a custom annotation to a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <Name extends string, Input, E, R, ContextInput, I, S>(
+    self: Command<Name, Input, ContextInput, E, R>,
+    service: Context.Key<I, S>,
+    value: NoInfer<S>
+  ): Command<Name, Input, ContextInput, E, R>
+} = dual(3, <Name extends string, Input, E, R, ContextInput, I, S>(
+  self: Command<Name, Input, ContextInput, E, R>,
+  service: Context.Key<I, S>,
+  value: NoInfer<S>
+) => {
+  const impl = toImpl(self)
+  return makeCommand({ ...impl, annotations: Context.add(impl.annotations, service, value) })
+})
+
+/**
+ * Merges a Context of annotations into a command.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const annotateMerge: {
+  /**
+   * Merges a Context of annotations into a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <I>(annotations: Context.Context<I>): <Name extends string, Input, E, R, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<Name, Input, ContextInput, E, R>
+  /**
+   * Merges a Context of annotations into a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <Name extends string, Input, E, R, ContextInput, I>(
+    self: Command<Name, Input, ContextInput, E, R>,
+    annotations: Context.Context<I>
+  ): Command<Name, Input, ContextInput, E, R>
+} = dual(2, <Name extends string, Input, E, R, ContextInput, I>(
+  self: Command<Name, Input, ContextInput, E, R>,
+  annotations: Context.Context<I>
+) => {
+  const impl = toImpl(self)
+  return makeCommand({ ...impl, annotations: Context.merge(impl.annotations, annotations) })
+})
+
+/**
+ * Sets usage examples for a command.
+ *
+ * Examples are exposed in structured `HelpDoc` data and rendered by the
+ * default formatter in an `EXAMPLES` section.
+ *
+ * @example
+ * ```ts
+ * import { Command } from "effect/unstable/cli"
+ *
+ * const login = Command.make("login").pipe(
+ *   Command.withExamples([
+ *     { command: "myapp login", description: "Log in with browser OAuth" },
+ *     { command: "myapp login --token sbp_abc123", description: "Log in with a token" }
+ *   ])
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withExamples: {
+  /**
+   * Sets usage examples for a command.
+   *
+   * Examples are exposed in structured `HelpDoc` data and rendered by the
+   * default formatter in an `EXAMPLES` section.
+   *
+   * @example
+   * ```ts
+   * import { Command } from "effect/unstable/cli"
+   *
+   * const login = Command.make("login").pipe(
+   *   Command.withExamples([
+   *     { command: "myapp login", description: "Log in with browser OAuth" },
+   *     { command: "myapp login --token sbp_abc123", description: "Log in with a token" }
+   *   ])
+   * )
+   * ```
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  (examples: ReadonlyArray<Command.Example>): <const Name extends string, Input, E, R, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<Name, Input, ContextInput, E, R>
+  /**
+   * Sets usage examples for a command.
+   *
+   * Examples are exposed in structured `HelpDoc` data and rendered by the
+   * default formatter in an `EXAMPLES` section.
+   *
+   * @example
+   * ```ts
+   * import { Command } from "effect/unstable/cli"
+   *
+   * const login = Command.make("login").pipe(
+   *   Command.withExamples([
+   *     { command: "myapp login", description: "Log in with browser OAuth" },
+   *     { command: "myapp login --token sbp_abc123", description: "Log in with a token" }
+   *   ])
+   * )
+   * ```
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <const Name extends string, Input, E, R, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>,
+    examples: ReadonlyArray<Command.Example>
+  ): Command<Name, Input, ContextInput, E, R>
+} = dual(2, <const Name extends string, Input, E, R, ContextInput>(
+  self: Command<Name, Input, ContextInput, E, R>,
+  examples: ReadonlyArray<Command.Example>
+) => makeCommand({ ...toImpl(self), examples }))
+
 /* ========================================================================== */
 /* Providing Services                                                         */
 /* ========================================================================== */
 
 // Internal helper: transforms a command's handler while preserving other properties
-const mapHandler = <Name extends string, Input, E, R, E2, R2>(
-  self: Command<Name, Input, E, R>,
+const mapHandler = <Name extends string, Input, E, R, ContextInput, E2, R2>(
+  self: Command<Name, Input, ContextInput, E, R>,
   f: (handler: Effect.Effect<void, E | CliError.CliError, R | Environment>, input: Input) => Effect.Effect<void, E2, R2>
-) => {
+): Command<Name, Input, ContextInput, E2, R2> => {
   const impl = toImpl(self)
   return makeCommand({ ...impl, handle: (input, path) => f(impl.handle(input, path), input) })
 }
@@ -1017,9 +1563,9 @@ export const provide: {
     options?: {
       readonly local?: boolean | undefined
     } | undefined
-  ): <const Name extends string, E, R>(
-    self: Command<Name, Input, E, R>
-  ) => Command<Name, Input, E | LE, Exclude<R, LA> | LR>
+  ): <const Name extends string, E, R, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<Name, Input, ContextInput, E | LE, Exclude<R, LA> | LR>
   /**
    * Provides the handler of a command with the services produced by a layer
    * that optionally depends on the command-line input to be created.
@@ -1056,15 +1602,15 @@ export const provide: {
    * @since 4.0.0
    * @category providing services
    */
-  <const Name extends string, Input, E, R, LA, LE, LR>(
-    self: Command<Name, Input, E, R>,
+  <const Name extends string, Input, E, R, ContextInput, LA, LE, LR>(
+    self: Command<Name, Input, ContextInput, E, R>,
     layer: Layer.Layer<LA, LE, LR> | ((input: Input) => Layer.Layer<LA, LE, LR>),
     options?: {
       readonly local?: boolean | undefined
     } | undefined
-  ): Command<Name, Input, E | LE, Exclude<R, LA> | LR>
-} = dual((args) => isCommand(args[0]), <const Name extends string, Input, E, R, LA, LE, LR>(
-  self: Command<Name, Input, E, R>,
+  ): Command<Name, Input, ContextInput, E | LE, Exclude<R, LA> | LR>
+} = dual((args) => isCommand(args[0]), <const Name extends string, Input, E, R, ContextInput, LA, LE, LR>(
+  self: Command<Name, Input, ContextInput, E, R>,
   layer: Layer.Layer<LA, LE, LR> | ((input: Input) => Layer.Layer<LA, LE, LR>),
   options?: { readonly local?: boolean | undefined } | undefined
 ) =>
@@ -1088,12 +1634,9 @@ export const provideSync: {
    * @since 4.0.0
    * @category providing services
    */
-  <I, S, Input>(
-    service: ServiceMap.Service<I, S>,
-    implementation: S | ((input: Input) => S)
-  ): <const Name extends string, E, R>(
-    self: Command<Name, Input, E, R>
-  ) => Command<Name, Input, E, Exclude<R, I>>
+  <I, S, Input>(service: Context.Key<I, S>, implementation: S | ((input: Input) => S)): <const Name extends string, E, R, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<Name, Input, ContextInput, E, Exclude<R, I>>
   /**
    * Provides the handler of a command with the implementation of a service that
    * optionally depends on the command-line input to be constructed.
@@ -1101,14 +1644,14 @@ export const provideSync: {
    * @since 4.0.0
    * @category providing services
    */
-  <const Name extends string, Input, E, R, I, S>(
-    self: Command<Name, Input, E, R>,
-    service: ServiceMap.Service<I, S>,
+  <const Name extends string, Input, E, R, ContextInput, I, S>(
+    self: Command<Name, Input, ContextInput, E, R>,
+    service: Context.Key<I, S>,
     implementation: S | ((input: Input) => S)
-  ): Command<Name, Input, E, Exclude<R, I>>
-} = dual(3, <const Name extends string, Input, E, R, I, S>(
-  self: Command<Name, Input, E, R>,
-  service: ServiceMap.Service<I, S>,
+  ): Command<Name, Input, ContextInput, E, Exclude<R, I>>
+} = dual(3, <const Name extends string, Input, E, R, ContextInput, I, S>(
+  self: Command<Name, Input, ContextInput, E, R>,
+  service: Context.Key<I, S>,
   implementation: S | ((input: Input) => S)
 ) =>
   mapHandler(self, (handler, input) =>
@@ -1134,11 +1677,11 @@ export const provideEffect: {
    * @category providing services
    */
   <I, S, Input, R2, E2>(
-    service: ServiceMap.Service<I, S>,
+    service: Context.Key<I, S>,
     effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, R2>)
-  ): <const Name extends string, E, R>(
-    self: Command<Name, Input, E, R>
-  ) => Command<Name, Input, E | E2, Exclude<R, I> | R2>
+  ): <const Name extends string, E, R, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<Name, Input, ContextInput, E | E2, Exclude<R, I> | R2>
   /**
    * Provides the handler of a command with the service produced by an effect
    * that optionally depends on the command-line input to be created.
@@ -1146,14 +1689,14 @@ export const provideEffect: {
    * @since 4.0.0
    * @category providing services
    */
-  <const Name extends string, Input, E, R, I, S, R2, E2>(
-    self: Command<Name, Input, E, R>,
-    service: ServiceMap.Service<I, S>,
+  <const Name extends string, Input, E, R, ContextInput, I, S, R2, E2>(
+    self: Command<Name, Input, ContextInput, E, R>,
+    service: Context.Key<I, S>,
     effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, R2>)
-  ): Command<Name, Input, E | E2, Exclude<R, I> | R2>
-} = dual(3, <const Name extends string, Input, E, R, I, S, R2, E2>(
-  self: Command<Name, Input, E, R>,
-  service: ServiceMap.Service<I, S>,
+  ): Command<Name, Input, ContextInput, E | E2, Exclude<R, I> | R2>
+} = dual(3, <const Name extends string, Input, E, R, ContextInput, I, S, R2, E2>(
+  self: Command<Name, Input, ContextInput, E, R>,
+  service: Context.Key<I, S>,
   effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, R2>)
 ) =>
   mapHandler(
@@ -1179,9 +1722,9 @@ export const provideEffectDiscard: {
    */
   <_, Input, E2, R2>(
     effect: Effect.Effect<_, E2, R2> | ((input: Input) => Effect.Effect<_, E2, R2>)
-  ): <const Name extends string, E, R>(
-    self: Command<Name, Input, E, R>
-  ) => Command<Name, Input, E | E2, R | R2>
+  ): <const Name extends string, E, R, ContextInput>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<Name, Input, ContextInput, E | E2, R | R2>
   /**
    * Allows for execution of an effect, which optionally depends on command-line
    * input to be created, prior to executing the handler of a command.
@@ -1189,12 +1732,12 @@ export const provideEffectDiscard: {
    * @since 4.0.0
    * @category providing services
    */
-  <const Name extends string, Input, E, R, _, E2, R2>(
-    self: Command<Name, Input, E, R>,
+  <const Name extends string, Input, E, R, ContextInput, _, E2, R2>(
+    self: Command<Name, Input, ContextInput, E, R>,
     effect: Effect.Effect<_, E2, R2> | ((input: Input) => Effect.Effect<_, E2, R2>)
-  ): Command<Name, Input, E | E2, R | R2>
-} = dual(2, <const Name extends string, Input, E, R, _, E2, R2>(
-  self: Command<Name, Input, E, R>,
+  ): Command<Name, Input, ContextInput, E | E2, R | R2>
+} = dual(2, <const Name extends string, Input, E, R, ContextInput, _, E2, R2>(
+  self: Command<Name, Input, ContextInput, E, R>,
   effect: Effect.Effect<_, E2, R2> | ((input: Input) => Effect.Effect<_, E2, R2>)
 ) =>
   mapHandler(self, (handler, input) => Effect.andThen(typeof effect === "function" ? effect(input) : effect, handler)))
@@ -1203,17 +1746,55 @@ export const provideEffectDiscard: {
 /* Execution                                                                  */
 /* ========================================================================== */
 
-const showHelp = <Name extends string, Input, E, R>(
-  command: Command<Name, Input, E, R>,
-  commandPath: ReadonlyArray<string>,
-  errors?: ReadonlyArray<CliError.CliError>
-): Effect.Effect<void, never, Environment> =>
+const getOutOfScopeGlobalFlagErrors = (
+  allFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>,
+  activeFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>,
+  flagMap: Record<string, ReadonlyArray<string>>,
+  commandPath: ReadonlyArray<string>
+): ReadonlyArray<CliError.UnrecognizedOption> => {
+  const activeSet = new Set(activeFlags)
+  const errors: Array<CliError.UnrecognizedOption> = []
+  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, 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 = getHelpForCommandPath(command, commandPath)
+    const helpDoc = yield* getHelpForCommandPath(command, error.commandPath, GlobalFlag.BuiltIns)
     yield* Console.log(formatter.formatHelpDoc(helpDoc))
-    if (errors && errors.length > 0) {
-      yield* Console.error(formatter.formatErrors(errors))
+    if (error.errors.length > 0) {
+      yield* Console.error(formatter.formatErrors(error.errors as any))
     }
   })
 
@@ -1232,7 +1813,7 @@ const showHelp = <Name extends string, Input, E, R>(
  *     yield* Console.log(`Hello, ${config.name}!`)
  *   }))
  *
- * // Automatically gets args from process.argv
+ * // Automatically gets args from the Stdio service
  * const program = Command.run(greetCommand, {
  *   version: "1.0.0"
  * })
@@ -1257,7 +1838,7 @@ export const run: {
    *     yield* Console.log(`Hello, ${config.name}!`)
    *   }))
    *
-   * // Automatically gets args from process.argv
+   * // Automatically gets args from the Stdio service
    * const program = Command.run(greetCommand, {
    *   version: "1.0.0"
    * })
@@ -1266,12 +1847,13 @@ export const run: {
    * @since 4.0.0
    * @category command execution
    */
-  <Name extends string, Input, E, R>(
-    command: Command<Name, Input, E, R>,
+  (
     config: {
       readonly version: string
     }
-  ): Effect.Effect<void, E | CliError.CliError, R | Environment>
+  ): <Name extends string, Input, E, R, ContextInput>(
+    command: Command<Name, Input, ContextInput, E, R>
+  ) => Effect.Effect<void, E | CliError.CliError, R | Environment>
   /**
    * Runs a command with the provided input arguments.
    *
@@ -1287,7 +1869,7 @@ export const run: {
    *     yield* Console.log(`Hello, ${config.name}!`)
    *   }))
    *
-   * // Automatically gets args from process.argv
+   * // Automatically gets args from the Stdio service
    * const program = Command.run(greetCommand, {
    *   version: "1.0.0"
    * })
@@ -1296,24 +1878,24 @@ export const run: {
    * @since 4.0.0
    * @category command execution
    */
-  (
+  <Name extends string, Input, E, R, ContextInput>(
+    command: Command<Name, Input, ContextInput, E, R>,
     config: {
       readonly version: string
     }
-  ): <Name extends string, Input, E, R>(
-    command: Command<Name, Input, E, R>
-  ) => Effect.Effect<void, E | CliError.CliError, R | Environment>
-} = dual(2, <Name extends string, Input, E, R>(
-  command: Command<Name, Input, E, R>,
+  ): Effect.Effect<void, E | CliError.CliError, R | Environment>
+} = dual(2, <Name extends string, Input, E, R, ContextInput>(
+  command: Command<Name, Input, ContextInput, E, R>,
   config: {
     readonly version: string
   }
-) => {
-  // TODO: process.argv is a Node.js global. For browser/edge runtime support,
-  // consider accepting an optional args parameter or using a platform service.
-  const input = process.argv.slice(2)
-  return runWith(command, config)(input)
-})
+) =>
+  Stdio.Stdio.use(({ args }) =>
+    Effect.flatMap(
+      args,
+      (args) => runWith(command, config)(args)
+    )
+  ))
 
 /**
  * Runs a command with explicitly provided arguments instead of using process.argv.
@@ -1354,8 +1936,8 @@ export const run: {
  * @since 4.0.0
  * @category command execution
  */
-export const runWith = <const Name extends string, Input, E, R>(
-  command: Command<Name, Input, E, R>,
+export const runWith = <const Name extends string, Input, E, R, ContextInput>(
+  command: Command<Name, Input, ContextInput, E, R>,
   config: {
     readonly version: string
   }
@@ -1365,54 +1947,87 @@ export const runWith = <const Name extends string, Input, E, R>(
   const commandImpl = toImpl(command)
   return Effect.fnUntraced(
     function*(args: ReadonlyArray<string>) {
-      // Lex and extract built-in flags
       const { tokens, trailingOperands } = Lexer.lex(args)
-      const { completions, help, logLevel, remainder, version } = yield* Parser.extractBuiltInOptions(tokens)
+
+      // 1. Collect known global flags from the command tree
+      const allFlags = getGlobalFlagsForCommandTree(command, GlobalFlag.BuiltIns)
+
+      // 2. Extract global flag tokens
+      const allFlagParams = allFlags.flatMap((f) => Param.extractSingleParams(f.flag))
+      const globalRegistry = Parser.createFlagRegistry(allFlagParams.filter(Param.isFlagParam))
+      const { flagMap, remainder, errors: globalFlagErrors } = Parser.consumeKnownFlags(tokens, globalRegistry)
+      const emptyArgs: Param.ParsedArgs = { flags: flagMap, arguments: [] }
+
+      // 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 formatter = yield* CliOutput.Formatter
+      const handlerCtx: GlobalFlag.HandlerContext = { command, commandPath, version: config.version }
+      const activeFlags = getGlobalFlagsForCommandPath(command, commandPath, GlobalFlag.BuiltIns)
 
-      // Handle built-in flags (early exits)
-      if (help) {
-        yield* Console.log(formatter.formatHelpDoc(getHelpForCommandPath(command, commandPath)))
-        return
-      }
-      if (completions !== undefined) {
-        const descriptor = CommandDescriptor.fromCommand(command)
-        yield* Console.log(Completions.generate(command.name, completions, descriptor))
-        return
+      // 4. Reject globals that were passed outside the active command scope
+      const outOfScopeErrors = getOutOfScopeGlobalFlagErrors(allFlags, activeFlags, flagMap, commandPath)
+      if (outOfScopeErrors.length > 0 || globalFlagErrors.length > 0) {
+        const parseErrors = parsedArgs.errors ?? []
+        return yield* new CliError.ShowHelp({
+          commandPath,
+          errors: [...globalFlagErrors, ...outOfScopeErrors, ...parseErrors]
+        })
       }
-      if (version) {
-        yield* Console.log(formatter.formatVersion(command.name, config.version))
+
+      // 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) => {
+          const entries = flagMap[s.name]
+          return entries !== undefined && entries.length > 0
+        })
+        if (!hasEntry) continue
+        const [, value] = yield* flag.flag.parse(emptyArgs)
+        yield* flag.run(value, handlerCtx)
         return
       }
 
-      // Handle parsing errors
+      // 6. Handle parsing errors
       if (parsedArgs.errors && parsedArgs.errors.length > 0) {
-        return yield* showHelp(command, commandPath, parsedArgs.errors)
+        return yield* new CliError.ShowHelp({ commandPath, errors: parsedArgs.errors })
       }
       const parseResult = yield* Effect.result(commandImpl.parse(parsedArgs))
       if (parseResult._tag === "Failure") {
-        return yield* showHelp(command, commandPath, [parseResult.failure])
+        return yield* new CliError.ShowHelp({
+          commandPath,
+          errors: [parseResult.failure as CliError.NonShowHelpErrors]
+        })
+      }
+
+      // 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)
+        program = Effect.provideService(program, flag, value)
       }
-      const parsed = parseResult.success
 
-      // Create and run the execution program
-      const program = commandImpl.handle(parsed, [command.name])
-      const withLogLevel = logLevel !== undefined
-        ? Effect.provideService(program, References.MinimumLogLevel, logLevel)
-        : program
+      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: () => Context.empty(),
+        onSome: (level) => Context.make(References.MinimumLogLevel, level)
+      })
 
-      yield* withLogLevel
+      // 9. Run command handler with composed context
+      yield* Effect.provideContext(program, services)
     },
-    Effect.catchIf(
-      ((error: any) =>
+    Effect.catchFilter(
+      (error) =>
         CliError.isCliError(error) && error._tag === "ShowHelp"
           ? Result.succeed(error)
-          : Result.fail(error)) as any,
-      (error: any) => showHelp(command, error.commandPath)
+          : Result.fail(error),
+      (error) => Effect.andThen(showHelp(command, error), Effect.fail(error))
     ),
-    Effect.catchIf(
+    Effect.catchFilter(
       (e) =>
         Terminal.isQuitError(e)
           ? Result.succeed(e)