effect 4.0.0-beta.1 → 4.0.0-beta.11

package/src/unstable/ai/Response.ts

@@ -453,9 +453,9 @@ export type ToolResultParts<Tools extends Record<string, Tool.Any>> = {
  * @since 1.0.0
  * @category schemas
  */
-export const ProviderMetadata: Schema.Record$<
+export const ProviderMetadata: Schema.$Record<
   Schema.String,
-  Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json>>
+  Schema.NullOr<Schema.Codec<Schema.Json>>
 > = Schema.Record(Schema.String, Schema.NullOr(Schema.Json))
 
 /**
@@ -629,7 +629,7 @@ export const TextPart: Schema.Struct<{
   readonly text: Schema.String
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -689,7 +689,7 @@ export const TextStartPart: Schema.Struct<{
   readonly id: Schema.String
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -757,7 +757,7 @@ export const TextDeltaPart: Schema.Struct<{
   readonly delta: Schema.String
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -818,7 +818,7 @@ export const TextEndPart: Schema.Struct<{
   readonly id: Schema.String
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -889,7 +889,7 @@ export const ReasoningPart: Schema.Struct<{
   readonly text: Schema.String
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -949,7 +949,7 @@ export const ReasoningStartPart: Schema.Struct<{
   readonly id: Schema.String
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -1017,7 +1017,7 @@ export const ReasoningDeltaPart: Schema.Struct<{
   readonly delta: Schema.String
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -1078,7 +1078,7 @@ export const ReasoningEndPart: Schema.Struct<{
   readonly id: Schema.String
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -1159,7 +1159,7 @@ export const ToolParamsStartPart: Schema.Struct<{
   readonly providerExecuted: Schema.withDecodingDefaultKey<Schema.Boolean>
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -1234,7 +1234,7 @@ export const ToolParamsDeltaPart: Schema.Struct<{
   readonly delta: Schema.String
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -1299,7 +1299,7 @@ export const ToolParamsEndPart: Schema.Struct<{
   readonly id: Schema.String
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -1414,7 +1414,7 @@ export const ToolCallPart: <const Name extends string, Params extends Schema.Top
     readonly providerExecuted: Schema.withDecodingDefaultKey<Schema.Boolean>
     readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
     readonly metadata: Schema.withDecodingDefault<
-      Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+      Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
     >
   }
 > = <const Name extends string, Params extends Schema.Top>(
@@ -1618,9 +1618,9 @@ export const ToolResultPart: <const Name extends string, Success extends Schema.
       readonly "~effect/ai/Content/Part": Schema.Literal<"~effect/ai/Content/Part">
       readonly result: Schema.Union<readonly [Success, Failure]>
       readonly providerExecuted: Schema.Boolean
-      readonly metadata: Schema.Record$<
+      readonly metadata: Schema.$Record<
         Schema.String,
-        Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>
+        Schema.NullOr<Schema.Codec<Schema.Json>>
       >
       readonly encodedResult: Schema.toEncoded<Schema.Union<readonly [Success, Failure]>>
       readonly preliminary: Schema.Boolean
@@ -1635,7 +1635,7 @@ export const ToolResultPart: <const Name extends string, Success extends Schema.
       readonly result: Schema.toEncoded<Schema.Union<readonly [Success, Failure]>>
       readonly providerExecuted: Schema.optional<Schema.Boolean>
       readonly metadata: Schema.optional<
-        Schema.Record$<Schema.String, Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>>
+        Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.Json>>>
       >
       readonly preliminary: Schema.optional<Schema.Boolean>
       readonly id: Schema.String
@@ -1795,7 +1795,7 @@ export const ToolApprovalRequestPart: Schema.Struct<{
   readonly toolCallId: Schema.String
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -1888,7 +1888,7 @@ export const FilePart: Schema.Struct<{
   readonly data: Schema.Uint8ArrayFromBase64
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -1985,7 +1985,7 @@ export const DocumentSourcePart: Schema.Struct<{
   readonly fileName: Schema.optionalKey<Schema.String>
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -2076,7 +2076,7 @@ export const UrlSourcePart: Schema.Struct<{
   readonly title: Schema.String
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -2115,7 +2115,7 @@ export const UrlSourcePart: Schema.Struct<{
  * @category schemas
  */
 export const HttpRequestDetails = Schema.Struct({
-  method: Schema.Literals(["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS"]),
+  method: Schema.Literals(["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]),
   url: Schema.String,
   urlParams: Schema.Array(Schema.Tuple([Schema.String, Schema.String])),
   hash: Schema.UndefinedOr(Schema.String),
@@ -2257,7 +2257,7 @@ export const ResponseMetadataPart: Schema.Struct<{
   readonly request: Schema.UndefinedOr<typeof HttpRequestDetails>
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -2464,7 +2464,7 @@ export const FinishPart: Schema.Struct<{
   readonly response: Schema.UndefinedOr<typeof HttpResponseDetails>
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,
@@ -2527,7 +2527,7 @@ export const ErrorPart: Schema.Struct<{
   readonly error: Schema.Unknown
   readonly "~effect/ai/Content/Part": Schema.withDecodingDefaultKey<Schema.tag<"~effect/ai/Content/Part">>
   readonly metadata: Schema.withDecodingDefault<
-    Schema.Record$<Schema.String, Schema.Codec<Schema.Json, Schema.Json>>
+    Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>
   >
 }> = Schema.Struct({
   ...BasePart.fields,

package/src/unstable/cli/CliOutput.ts

@@ -499,14 +499,53 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
 
   // Subcommands section
   if (doc.subcommands && doc.subcommands.length > 0) {
-    sections.push(colors.bold("SUBCOMMANDS"))
+    const ungrouped = doc.subcommands.find((group) => group.group === undefined)
+
+    if (ungrouped) {
+      sections.push(colors.bold("SUBCOMMANDS"))
+      sections.push(renderTable(
+        ungrouped.commands.map((sub) => ({
+          left: colors.cyan(sub.name),
+          right: sub.shortDescription ?? sub.description
+        })),
+        20
+      ))
+      if (doc.subcommands.length > 1) {
+        sections.push("")
+      }
+    }
 
-    const subcommandRows: Array<Row> = doc.subcommands.map((sub) => ({
-      left: colors.cyan(sub.name),
-      right: sub.description
-    }))
+    for (const group of doc.subcommands) {
+      if (group.group === undefined) continue
+      sections.push(colors.bold(`${group.group}:`))
+      sections.push(renderTable(
+        group.commands.map((sub) => ({
+          left: colors.cyan(sub.name),
+          right: sub.shortDescription ?? sub.description
+        })),
+        20
+      ))
+      sections.push("")
+    }
+  }
 
-    sections.push(renderTable(subcommandRows, 20))
+  // Examples section
+  if (doc.examples && doc.examples.length > 0) {
+    sections.push(colors.bold("EXAMPLES"))
+
+    let first = true
+    let previousHadDescription = false
+    for (const example of doc.examples) {
+      if (example.description) {
+        if (!first) sections.push("")
+        sections.push(`  ${colors.dim(`# ${example.description}`)}`)
+      } else if (previousHadDescription) {
+        sections.push("")
+      }
+      sections.push(`  ${colors.cyan(example.command)}`)
+      first = false
+      previousHadDescription = !!example.description
+    }
     sections.push("")
   }
 

package/src/unstable/cli/Command.ts

@@ -1,6 +1,7 @@
 /**
  * @since 4.0.0
  */
+import type { NonEmptyArray, NonEmptyReadonlyArray } from "../../Array.ts"
 import * as Console from "../../Console.ts"
 import * as Effect from "../../Effect.ts"
 import type * as FileSystem from "../../FileSystem.ts"
@@ -11,9 +12,9 @@ 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 ServiceMap from "../../ServiceMap.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"
@@ -94,16 +95,45 @@ 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
+
+  /**
+   * 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
+   */
+  export interface Example {
+    readonly command: string
+    readonly description?: string | undefined
+  }
+
   /**
    * Configuration object for defining command flags, arguments, and nested structures.
    *
@@ -209,6 +239,25 @@ export declare namespace Command {
    * @category models
    */
   export type Any = Command<string, 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>>
 }
 
 /**
@@ -644,6 +693,57 @@ export const withHandler: {
   handler: (value: A) => Effect.Effect<void, E, R>
 ): Command<Name, A, E, R> => 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.
  *
@@ -717,7 +817,7 @@ 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>(
+  <const Subcommands extends ReadonlyArray<Command.SubcommandEntry>>(subcommands: Subcommands): <Name extends string, Input, E, R>(
     self: Command<Name, Input, E, R>
   ) => Command<
     Name,
@@ -766,7 +866,7 @@ export const withSubcommands: {
     Input,
     E,
     R,
-    const Subcommands extends ReadonlyArray<Command<any, any, any, any>>
+    const Subcommands extends ReadonlyArray<Command.SubcommandEntry>
   >(self: Command<Name, Input, E, R>, subcommands: Subcommands): Command<
     Name,
     Input,
@@ -778,7 +878,7 @@ export const withSubcommands: {
   Input,
   E,
   R,
-  const Subcommands extends ReadonlyArray<Command<any, any, any, any>>
+  const Subcommands extends ReadonlyArray<Command.SubcommandEntry>
 >(
   self: Command<Name, Input, E, R>,
   subcommands: Subcommands
@@ -788,10 +888,11 @@ export const withSubcommands: {
   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 }
@@ -832,16 +933,22 @@ export const withSubcommands: {
     name: impl.name,
     config: impl.config,
     description: impl.description,
+    shortDescription: impl.shortDescription,
+    annotations: impl.annotations,
+    examples: impl.examples,
     service: impl.service,
-    subcommands,
+    subcommands: normalized.groups,
     parse,
     handle
   })
 })
 
 // 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
+type ExtractSubcommand<T> = T extends Command<any, any, any, any> ? 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<any, any, any, infer R> ? R : never
 
 /**
@@ -926,6 +1033,186 @@ export const withDescription: {
   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>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, 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>(self: Command<Name, Input, E, R>, shortDescription: string): Command<Name, Input, E, R>
+} = dual(2, <const Name extends string, Input, E, R>(
+  self: Command<Name, Input, E, R>,
+  shortDescription: string
+) => makeCommand({ ...toImpl(self), shortDescription }))
+
+/**
+ * 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: ServiceMap.Service<I, S>, value: NoInfer<S>): <Name extends string, Input, E, R>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, R>
+  /**
+   * Adds a custom annotation to a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <Name extends string, Input, E, R, I, S>(
+    self: Command<Name, Input, E, R>,
+    service: ServiceMap.Service<I, S>,
+    value: NoInfer<S>
+  ): Command<Name, Input, E, R>
+} = dual(3, <Name extends string, Input, E, R, I, S>(
+  self: Command<Name, Input, E, R>,
+  service: ServiceMap.Service<I, S>,
+  value: NoInfer<S>
+) => {
+  const impl = toImpl(self)
+  return makeCommand({ ...impl, annotations: ServiceMap.add(impl.annotations, service, value) })
+})
+
+/**
+ * Merges a ServiceMap of annotations into a command.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export 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>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, R>
+  /**
+   * Merges a ServiceMap of annotations into a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <Name extends string, Input, E, R, I>(self: Command<Name, Input, E, R>, annotations: ServiceMap.ServiceMap<I>): Command<Name, Input, E, R>
+} = dual(2, <Name extends string, Input, E, R, I>(
+  self: Command<Name, Input, E, R>,
+  annotations: ServiceMap.ServiceMap<I>
+) => {
+  const impl = toImpl(self)
+  return makeCommand({ ...impl, annotations: ServiceMap.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>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, 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>(self: Command<Name, Input, E, R>, examples: ReadonlyArray<Command.Example>): Command<Name, Input, E, R>
+} = dual(2, <const Name extends string, Input, E, R>(
+  self: Command<Name, Input, E, R>,
+  examples: ReadonlyArray<Command.Example>
+) => makeCommand({ ...toImpl(self), examples }))
+
 /* ========================================================================== */
 /* Providing Services                                                         */
 /* ========================================================================== */