effect 4.0.0-beta.3 → 4.0.0-beta.30

package/dist/unstable/cli/Command.d.ts

@@ -1,15 +1,21 @@
+/**
+ * @since 4.0.0
+ */
+import type { NonEmptyReadonlyArray } from "../../Array.ts";
 import * as Effect from "../../Effect.ts";
 import type * as FileSystem from "../../FileSystem.ts";
 import type * as Layer from "../../Layer.ts";
 import type * as Path from "../../Path.ts";
 import type { Pipeable } from "../../Pipeable.ts";
-import type * as ServiceMap from "../../ServiceMap.ts";
+import * 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 GlobalFlag from "./GlobalFlag.ts";
 import { TypeId } from "./internal/command.ts";
-import type * as Param from "./Param.ts";
+import * as Param from "./Param.ts";
 /**
  * Represents a CLI command with its configuration, handler, and metadata.
  *
@@ -25,7 +31,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"
  * )
  *
@@ -37,6 +43,7 @@ import type * as Param from "./Param.ts";
  *     readonly force: boolean
  *     readonly files: ReadonlyArray<string>
  *   },
+ *   {},
  *   never,
  *   never
  * > = Command.make("deploy", {
@@ -54,7 +61,7 @@ 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;
     /**
      * The name of the command.
@@ -64,15 +71,44 @@ export interface Command<Name extends string, Input, E = never, R = never> exten
      * An optional description of the command.
      */
     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: ServiceMap.ServiceMap<never>;
 }
 /**
  * @since 4.0.0
  */
 export declare namespace Command {
+    /**
+     * Represents a concrete usage example for a command.
+     *
+     * @since 4.0.0
+     * @category models
+     */
+    interface Example {
+        readonly command: string;
+        readonly description?: string | undefined;
+    }
     /**
      * Configuration object for defining command flags, arguments, and nested structures.
      *
@@ -112,6 +148,17 @@ export declare namespace Command {
     interface Config {
         readonly [key: string]: Param.Param<Param.ParamKind, any> | ReadonlyArray<Param.Param<Param.ParamKind, any> | Config> | Config;
     }
+    /**
+     * Configuration shape accepted by `Command.withSharedFlags`.
+     *
+     * Only flags are allowed here; arguments are intentionally excluded.
+     *
+     * @since 4.0.0
+     * @category models
+     */
+    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.
      *
@@ -170,7 +217,24 @@ export declare namespace Command {
      * @since 4.0.0
      * @category models
      */
-    type Any = Command<string, unknown, unknown, unknown>;
+    type Any = Command<string, unknown, unknown, unknown, unknown>;
+    /**
+     * A grouped set of subcommands used by `Command.withSubcommands`.
+     *
+     * @since 4.0.0
+     * @category models
+     */
+    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
+     */
+    type SubcommandEntry = Any | SubcommandGroup<ReadonlyArray<Any>>;
 }
 /**
  * The environment required by CLI commands, including file system and path operations.
@@ -178,14 +242,14 @@ 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`.
  *
  * @since 4.0.0
  * @category utility types
  */
-export type Error<C> = C extends Command<infer _Name, infer _Input, infer _Error, infer _Requirements> ? _Error : never;
+export type Error<C> = C extends Command<infer _Name, infer _Input, infer _ContextInput, infer _Error, infer _Requirements> ? _Error : never;
 /**
  * Service context for a specific command, enabling subcommands to access their parent's parsed configuration.
  *
@@ -199,10 +263,12 @@ export type Error<C> = C extends Command<infer _Name, infer _Input, infer _Error
  * 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")
@@ -353,7 +419,7 @@ export declare 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>;
     /**
      * Creates a Command from a name, optional config, optional handler function, and optional description.
      *
@@ -407,7 +473,7 @@ export declare 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>;
     /**
      * Creates a Command from a name, optional config, optional handler function, and optional description.
      *
@@ -461,7 +527,7 @@ export declare const make: {
      * @since 4.0.0
      * @category constructors
      */
-    <Name extends string, const Config extends Command.Config, R, E>(name: Name, config: Config, handler: (config: Command.Config.Infer<Config>) => Effect.Effect<void, E, R>): Command<Name, Command.Config.Infer<Config>, E, R>;
+    <Name extends string, const Config extends Command.Config, R, E>(name: Name, config: Config, handler: (config: Command.Config.Infer<Config>) => Effect.Effect<void, E, R>): Command<Name, Command.Config.Infer<Config>, {}, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>;
 };
 /**
  * Adds or replaces the handler for a command.
@@ -512,7 +578,7 @@ export declare 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>>;
     /**
      * Adds or replaces the handler for a command.
      *
@@ -537,13 +603,13 @@ export declare const withHandler: {
      * @since 4.0.0
      * @category combinators
      */
-    <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>;
+    <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, ContextInput, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>;
 };
 /**
  * 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
@@ -551,10 +617,12 @@ export declare 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", {
@@ -580,7 +648,7 @@ export declare 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
@@ -588,10 +656,12 @@ export declare 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", {
@@ -612,12 +682,12 @@ export declare 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>) => Command<Name, Input, E | ExtractSubcommandErrors<Subcommands>, R | Exclude<ExtractSubcommandContext<Subcommands>, CommandContext<Name>>>;
+    <const Subcommands extends ReadonlyArray<Command.SubcommandEntry>>(subcommands: Subcommands): <Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Simplify<Input | ContextInput>, ContextInput, E | ExtractSubcommandErrors<Subcommands>, R | Exclude<ExtractSubcommandContext<Subcommands>, CommandContext<Name>>>;
     /**
      * 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
@@ -625,10 +695,12 @@ export declare 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", {
@@ -649,10 +721,74 @@ export declare const withSubcommands: {
      * @since 4.0.0
      * @category combinators
      */
-    <Name extends string, Input, E, R, const Subcommands extends ReadonlyArray<Command<any, any, any, any>>>(self: Command<Name, Input, E, R>, subcommands: Subcommands): Command<Name, Input, E | ExtractSubcommandErrors<Subcommands>, R | Exclude<ExtractSubcommandContext<Subcommands>, CommandContext<Name>>>;
+    <Name extends string, Input, E, R, ContextInput, const Subcommands extends ReadonlyArray<Command.SubcommandEntry>>(self: Command<Name, Input, ContextInput, E, R>, subcommands: Subcommands): Command<Name, Simplify<Input | ContextInput>, ContextInput, E | ExtractSubcommandErrors<Subcommands>, R | Exclude<ExtractSubcommandContext<Subcommands>, CommandContext<Name>>>;
+};
+/**
+ * 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 declare 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>;
+};
+/**
+ * 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 declare 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>>>;
 };
-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.
  *
@@ -702,7 +838,7 @@ export declare 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.
      *
@@ -727,7 +863,183 @@ export declare 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>;
+    <const Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>, description: string): 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
+ */
+export declare 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>;
+};
+/**
+ * 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 declare 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>;
+};
+/**
+ * Adds a custom annotation to a command.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export declare const annotate: {
+    /**
+     * Adds a custom annotation to a command.
+     *
+     * @since 4.0.0
+     * @category combinators
+     */
+    <I, S>(service: ServiceMap.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: ServiceMap.Key<I, S>, value: NoInfer<S>): Command<Name, Input, ContextInput, E, R>;
+};
+/**
+ * Merges a ServiceMap of annotations into a command.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export declare const annotateMerge: {
+    /**
+     * Merges a ServiceMap of annotations into a command.
+     *
+     * @since 4.0.0
+     * @category combinators
+     */
+    <I>(annotations: ServiceMap.ServiceMap<I>): <Name extends string, Input, E, R, ContextInput>(self: Command<Name, Input, ContextInput, E, R>) => Command<Name, Input, ContextInput, E, R>;
+    /**
+     * Merges a ServiceMap 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: ServiceMap.ServiceMap<I>): 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
+ */
+export declare 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>;
 };
 /**
  * Provides the handler of a command with the services produced by a layer
@@ -804,7 +1116,7 @@ export declare const provide: {
      */
     <Input, LR, LE, LA>(layer: Layer.Layer<LA, LE, LR> | ((input: Input) => Layer.Layer<LA, LE, LR>), 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>;
+    } | undefined): <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.
@@ -841,9 +1153,9 @@ export declare 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>, layer: Layer.Layer<LA, LE, LR> | ((input: Input) => Layer.Layer<LA, LE, LR>), options?: {
+    <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>;
+    } | undefined): Command<Name, Input, ContextInput, E | LE, Exclude<R, LA> | LR>;
 };
 /**
  * Provides the handler of a command with the implementation of a service that
@@ -860,7 +1172,7 @@ export declare 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: ServiceMap.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.
@@ -868,7 +1180,7 @@ export declare 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>, implementation: S | ((input: Input) => S)): Command<Name, Input, E, Exclude<R, I>>;
+    <const Name extends string, Input, E, R, ContextInput, I, S>(self: Command<Name, Input, ContextInput, E, R>, service: ServiceMap.Key<I, S>, implementation: S | ((input: Input) => S)): Command<Name, Input, ContextInput, E, Exclude<R, I>>;
 };
 /**
  * Provides the handler of a command with the service produced by an effect
@@ -885,7 +1197,7 @@ export declare const provideEffect: {
      * @since 4.0.0
      * @category providing services
      */
-    <I, S, Input, R2, E2>(service: ServiceMap.Service<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>;
+    <I, S, Input, R2, E2>(service: ServiceMap.Key<I, S>, effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, 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.
@@ -893,7 +1205,7 @@ export declare 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>, effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, R2>)): Command<Name, Input, E | E2, Exclude<R, I> | R2>;
+    <const Name extends string, Input, E, R, ContextInput, I, S, R2, E2>(self: Command<Name, Input, ContextInput, E, R>, service: ServiceMap.Key<I, S>, effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, R2>)): Command<Name, Input, ContextInput, E | E2, Exclude<R, I> | R2>;
 };
 /**
  * Allows for execution of an effect, which optionally depends on command-line
@@ -910,7 +1222,7 @@ export declare const provideEffectDiscard: {
      * @since 4.0.0
      * @category providing services
      */
-    <_, 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>;
+    <_, Input, E2, R2>(effect: Effect.Effect<_, E2, R2> | ((input: Input) => Effect.Effect<_, E2, 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.
@@ -918,7 +1230,7 @@ export declare const provideEffectDiscard: {
      * @since 4.0.0
      * @category providing services
      */
-    <const Name extends string, Input, E, R, _, E2, R2>(self: Command<Name, Input, E, R>, effect: Effect.Effect<_, E2, R2> | ((input: Input) => Effect.Effect<_, E2, R2>)): Command<Name, Input, E | E2, R | R2>;
+    <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, ContextInput, E | E2, R | R2>;
 };
 /**
  * Runs a command with the provided input arguments.
@@ -935,7 +1247,7 @@ export declare const provideEffectDiscard: {
  *     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"
  * })
@@ -960,7 +1272,7 @@ export declare 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"
      * })
@@ -969,9 +1281,9 @@ export declare const run: {
      * @since 4.0.0
      * @category command execution
      */
-    <Name extends string, Input, E, R>(command: Command<Name, Input, E, R>, config: {
+    (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.
      *
@@ -987,7 +1299,7 @@ export declare 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"
      * })
@@ -996,9 +1308,9 @@ export declare const run: {
      * @since 4.0.0
      * @category command execution
      */
-    (config: {
+    <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>;
+    }): Effect.Effect<void, E | CliError.CliError, R | Environment>;
 };
 /**
  * Runs a command with explicitly provided arguments instead of using process.argv.
@@ -1039,7 +1351,7 @@ export declare const run: {
  * @since 4.0.0
  * @category command execution
  */
-export declare const runWith: <const Name extends string, Input, E, R>(command: Command<Name, Input, E, R>, config: {
+export declare const runWith: <const Name extends string, Input, E, R, ContextInput>(command: Command<Name, Input, ContextInput, E, R>, config: {
     readonly version: string;
 }) => (input: ReadonlyArray<string>) => Effect.Effect<void, Exclude<E, Terminal.QuitError> | CliError.CliError, R | Environment>;
 export {};