effect 4.0.0-beta.103 → 4.0.0-beta.105

package/src/unstable/cli/CliError.ts

@@ -115,7 +115,7 @@ export type CliError =
  * @category errors
  * @since 4.0.0
  */
-export class UnrecognizedOption extends Schema.TaggedErrorClass<UnrecognizedOption>(
+export class UnrecognizedOption extends Schema.TaggedError<UnrecognizedOption>(
   `${TypeId}/UnrecognizedOption`
 )("UnrecognizedOption", {
   option: Schema.String,
@@ -168,7 +168,7 @@ export class UnrecognizedOption extends Schema.TaggedErrorClass<UnrecognizedOpti
  * @category errors
  * @since 4.0.0
  */
-export class DuplicateOption extends Schema.TaggedErrorClass<DuplicateOption>(
+export class DuplicateOption extends Schema.TaggedError<DuplicateOption>(
   `${TypeId}/DuplicateOption`
 )("DuplicateOption", {
   option: Schema.String,
@@ -225,7 +225,7 @@ export class DuplicateOption extends Schema.TaggedErrorClass<DuplicateOption>(
  * @category errors
  * @since 4.0.0
  */
-export class MissingOption extends Schema.TaggedErrorClass<MissingOption>(
+export class MissingOption extends Schema.TaggedError<MissingOption>(
   `${TypeId}/MissingOption`
 )("MissingOption", {
   option: Schema.String
@@ -278,7 +278,7 @@ export class MissingOption extends Schema.TaggedErrorClass<MissingOption>(
  * @category errors
  * @since 4.0.0
  */
-export class MissingArgument extends Schema.TaggedErrorClass<MissingArgument>(
+export class MissingArgument extends Schema.TaggedError<MissingArgument>(
   `${TypeId}/MissingArgument`
 )("MissingArgument", {
   argument: Schema.String
@@ -319,7 +319,7 @@ export class MissingArgument extends Schema.TaggedErrorClass<MissingArgument>(
  * @category errors
  * @since 4.0.0
  */
-export class UnexpectedArgument extends Schema.TaggedErrorClass<UnexpectedArgument>(
+export class UnexpectedArgument extends Schema.TaggedError<UnexpectedArgument>(
   `${TypeId}/UnexpectedArgument`
 )("UnexpectedArgument", {
   arguments: Schema.Array(Schema.String)
@@ -376,7 +376,7 @@ export class UnexpectedArgument extends Schema.TaggedErrorClass<UnexpectedArgume
  * @category errors
  * @since 4.0.0
  */
-export class InvalidValue extends Schema.TaggedErrorClass<InvalidValue>(
+export class InvalidValue extends Schema.TaggedError<InvalidValue>(
   `${TypeId}/InvalidValue`
 )("InvalidValue", {
   option: Schema.String,
@@ -425,7 +425,7 @@ export class InvalidValue extends Schema.TaggedErrorClass<InvalidValue>(
  *   suggestions: ["deploy", "destroy"]
  * })
  *
- * unknownSubcommandError._tag // => "UnknownSubcomand"
+ * unknownSubcommandError._tag // => "UnknownSubcommand"
  * unknownSubcommandError.subcommand // => "deplyo"
  * unknownSubcommandError.parent // => ["myapp"]
  *
@@ -440,15 +440,15 @@ export class InvalidValue extends Schema.TaggedErrorClass<InvalidValue>(
  *   })
  *
  * const parseError = await Effect.runPromise(Effect.flip(parseSubcommand("deplyo")))
- * parseError._tag // => "UnknownSubcomand"
+ * parseError._tag // => "UnknownSubcommand"
  * ```
  *
  * @category errors
  * @since 4.0.0
  */
-export class UnknownSubcommand extends Schema.TaggedErrorClass<UnknownSubcommand>(
+export class UnknownSubcommand extends Schema.TaggedError<UnknownSubcommand>(
   `${TypeId}/UnknownSubcommand`
-)("UnknownSubcomand", {
+)("UnknownSubcommand", {
   subcommand: Schema.String,
   parent: Schema.optional(Schema.Array(Schema.String)),
   suggestions: Schema.Array(Schema.String)
@@ -513,7 +513,7 @@ export class UnknownSubcommand extends Schema.TaggedErrorClass<UnknownSubcommand
  * @category errors
  * @since 4.0.0
  */
-export class UserError extends Schema.TaggedErrorClass<UserError>(
+export class UserError extends Schema.TaggedError<UserError>(
   `${TypeId}/UserError`
 )("UserError", {
   cause: Schema.Defect()
@@ -585,7 +585,7 @@ export type NonShowHelpErrors = typeof NonShowHelpErrors.Type
  * @category errors
  * @since 4.0.0
  */
-export class ShowHelp extends Schema.TaggedErrorClass<ShowHelp>(
+export class ShowHelp extends Schema.TaggedError<ShowHelp>(
   `${TypeId}/ShowHelp`
 )("ShowHelp", {
   commandPath: Schema.Array(Schema.String),

package/src/unstable/cli/Command.ts

@@ -165,11 +165,11 @@ export interface Command<in out Name extends string, in Input, out ContextInput
   readonly annotations: Context.Context<never>
 
   /**
-   * Whether this command is hidden from parent help output, shell
-   * completions, and unknown-subcommand suggestions. Hidden commands still
+   * Whether this command is omitted from parent help output, shell
+   * completions, and unknown-subcommand suggestions. Unlisted commands still
    * parse and execute normally when invoked by exact name.
    */
-  readonly hidden: boolean
+  readonly unlisted: boolean
 }
 
 /**
@@ -352,7 +352,7 @@ export declare namespace Command {
       readonly commands: NonEmptyReadonlyArray<Command.Any>
     }>
     readonly annotations: Context.Context<never>
-    readonly hidden: boolean
+    readonly unlisted: boolean
   }
 
   /**
@@ -1430,6 +1430,7 @@ export const withSubcommands: {
     description: impl.description,
     shortDescription: impl.shortDescription,
     alias: impl.alias,
+    unlisted: impl.unlisted,
     annotations: impl.annotations,
     globalFlags: impl.globalFlags,
     examples: impl.examples,
@@ -1548,6 +1549,7 @@ export const withSharedFlags: {
       description: impl.description,
       shortDescription: impl.shortDescription,
       alias: impl.alias,
+      unlisted: impl.unlisted,
       annotations: impl.annotations,
       globalFlags: impl.globalFlags,
       examples: impl.examples,
@@ -1886,7 +1888,7 @@ export const withAlias: {
 ) => makeCommand({ ...toImpl(self), alias }))
 
 /**
- * Hides a subcommand from parent help output, shell completions, and
+ * Omits a subcommand from parent help output, shell completions, and
  * "did you mean?" suggestions while keeping it fully invocable by exact name.
  *
  * **When to use**
@@ -1894,7 +1896,7 @@ export const withAlias: {
  * Use when experimental or internal subcommands should be accepted but not advertised on
  * the public CLI surface.
  *
- * **Example** (Hiding a subcommand)
+ * **Example** (Unlisting a subcommand)
  *
  * ```ts import.meta.vitest
  * import { Command } from "effect/unstable/cli"
@@ -1902,23 +1904,23 @@ export const withAlias: {
  * // `experimental` still runs when invoked as `mycli experimental`,
  * // but it does not appear under SUBCOMMANDS in `mycli --help`.
  * const experimental = Command.make("experimental").pipe(
- *   Command.withHidden
+ *   Command.unlisted
  * )
  *
  * const root = Command.make("mycli").pipe(
  *   Command.withSubcommands([experimental])
  * )
  *
- * root.subcommands[0].commands[0].hidden // => true
+ * root.subcommands[0].commands[0].unlisted // => true
  * ```
  *
  * @category combinators
  * @since 4.0.0
  */
-export const withHidden = <const Name extends string, Input, E, R, ContextInput>(
+export const unlisted = <const Name extends string, Input, E, R, ContextInput>(
   self: Command<Name, Input, ContextInput, E, R>
 ): Command<Name, Input, ContextInput, E, R> =>
-  makeCommand({ ...toImpl(self), hidden: true }) as Command<Name, Input, ContextInput, E, R>
+  makeCommand({ ...toImpl(self), unlisted: true }) as Command<Name, Input, ContextInput, E, R>
 
 /**
  * Adds a custom annotation to a command.

package/src/unstable/cli/Param.ts

@@ -12,7 +12,7 @@
  */
 import * as Config from "../../Config.ts"
 import * as Effect from "../../Effect.ts"
-import { dual, identity } from "../../Function.ts"
+import { dual, identity, type LazyArg } from "../../Function.ts"
 import * as Option from "../../Option.ts"
 import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
@@ -226,7 +226,11 @@ export interface Transform<Kind extends ParamKind, in out A, out B> extends Para
   readonly _tag: "Transform"
   readonly kind: Kind
   readonly param: Param<Kind, A>
-  readonly f: (parse: Parse<A>) => Parse<B>
+  readonly alternatives: ReadonlyArray<LazyArg<Param<Kind, unknown>>>
+  readonly f: (
+    parse: Parse<A>,
+    alternatives: ReadonlyArray<LazyArg<Parse<unknown>>>
+  ) => Parse<B>
 }
 
 /**
@@ -1209,15 +1213,22 @@ export const map: {
 
 const transform = <Kind extends ParamKind, A, B>(
   self: Param<Kind, A>,
-  f: (parse: Parse<A>) => Parse<B>
-) =>
-  Object.assign(Object.create(Proto), {
+  f: (
+    parse: Parse<A>,
+    alternatives: ReadonlyArray<LazyArg<Parse<unknown>>>
+  ) => Parse<B>,
+  alternatives: ReadonlyArray<LazyArg<Param<Kind, unknown>>> = []
+): Transform<Kind, A, B> => {
+  const alternativeParsers = alternatives.map((alternative) => () => alternative().parse)
+  return Object.assign(Object.create(Proto), {
     _tag: "Transform",
     kind: self.kind,
     param: self,
+    alternatives,
     f,
-    parse: f(self.parse)
+    parse: f(self.parse, alternativeParsers)
   })
+}
 
 /**
  * Transforms the parsed value of an option using an effectful mapping function.
@@ -2719,7 +2730,7 @@ export const orElse: {
    * @category combinators
    * @since 4.0.0
    */
-  <B, Kind extends ParamKind>(orElse: (error: CliError.CliError) => Param<Kind, B>): <A>(self: Param<Kind, A>) => Param<Kind, A | B>
+  <B, Kind extends ParamKind>(orElse: LazyArg<Param<Kind, B>>): <A>(self: Param<Kind, A>) => Param<Kind, A | B>
   /**
    * Provides a fallback param to use if this param fails to parse.
    *
@@ -2737,14 +2748,16 @@ export const orElse: {
    * @category combinators
    * @since 4.0.0
    */
-  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: (error: CliError.CliError) => Param<Kind, B>): Param<Kind, A | B>
+  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: LazyArg<Param<Kind, B>>): Param<Kind, A | B>
 } = dual(2, <Kind extends ParamKind, A, B>(
   self: Param<Kind, A>,
-  orElse: (error: CliError.CliError) => Param<Kind, B>
+  orElse: LazyArg<Param<Kind, B>>
 ) =>
   transform(
     self,
-    (parse: Parse<A>): Parse<A | B> => (args: ParsedArgs) => Effect.catch(parse(args), (err) => orElse(err).parse(args))
+    (parse: Parse<A>, alternatives): Parse<A | B> => (args: ParsedArgs) =>
+      Effect.catch(parse(args), () => (alternatives[0]!() as Parse<B>)(args)),
+    [orElse]
   ))
 
 /**
@@ -2796,7 +2809,7 @@ export const orElseResult: {
    * @category combinators
    * @since 4.0.0
    */
-  <Kind extends ParamKind, B>(orElse: (error: CliError.CliError) => Param<Kind, B>): <A>(self: Param<Kind, A>) => Param<Kind, Result.Result<A, B>>
+  <Kind extends ParamKind, B>(orElse: LazyArg<Param<Kind, B>>): <A>(self: Param<Kind, A>) => Param<Kind, Result.Result<A, B>>
   /**
    * Provides a fallback param and returns a `Result` indicating which param
    * succeeded.
@@ -2821,22 +2834,23 @@ export const orElseResult: {
    * @category combinators
    * @since 4.0.0
    */
-  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: (error: CliError.CliError) => Param<Kind, B>): Param<Kind, Result.Result<A, B>>
+  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: LazyArg<Param<Kind, B>>): Param<Kind, Result.Result<A, B>>
 } = dual(2, <Kind extends ParamKind, A, B>(
   self: Param<Kind, A>,
-  orElse: (error: CliError.CliError) => Param<Kind, B>
+  orElse: LazyArg<Param<Kind, B>>
 ) => {
   return transform(
     self,
-    (parse: Parse<A>): Parse<Result.Result<A, B>> => (args: ParsedArgs) =>
+    (parse: Parse<A>, alternatives): Parse<Result.Result<A, B>> => (args: ParsedArgs) =>
       Effect.catch(
         Effect.map(parse(args), ([leftover, value]) => [leftover, Result.succeed(value)] as const),
-        (err) =>
+        () =>
           Effect.map(
-            orElse(err).parse(args),
+            (alternatives[0]!() as Parse<B>)(args),
             ([leftover, value]) => [leftover, Result.fail(value)] as const
           )
-      )
+      ),
+    [orElse]
   )
 })
 
@@ -3053,7 +3067,12 @@ const transformSingle = <Kind extends ParamKind, A>(
   return matchParam(param, {
     Single: (single) => f(single),
     Map: (mapped) => map(transformSingle(mapped.param, f), mapped.f),
-    Transform: (mapped) => transform(transformSingle(mapped.param, f), mapped.f),
+    Transform: (mapped) =>
+      transform(
+        transformSingle(mapped.param, f),
+        mapped.f,
+        mapped.alternatives.map((alternative) => () => transformSingle(alternative(), f))
+      ),
     Optional: (p) => optional(transformSingle(p.param, f)) as Param<Kind, A>,
     Variadic: (p) =>
       variadic(transformSingle(p.param, f), {
@@ -3075,7 +3094,10 @@ export const extractSingleParams = <Kind extends ParamKind, A>(
   return matchParam(param, {
     Single: (single) => [single as Single<Kind, unknown>],
     Map: (mapped) => extractSingleParams(mapped.param),
-    Transform: (mapped) => extractSingleParams(mapped.param),
+    Transform: (mapped) => [
+      ...extractSingleParams(mapped.param),
+      ...mapped.alternatives.flatMap((alternative) => extractSingleParams(alternative()))
+    ],
     Optional: (optional) => extractSingleParams(optional.param),
     Variadic: (variadic) => extractSingleParams(variadic.param)
   })

package/src/unstable/cli/Primitive.ts

@@ -10,9 +10,6 @@
  *
  * @since 4.0.0
  */
-import * as Ini from "ini"
-import * as Toml from "toml"
-import * as Yaml from "yaml"
 import * as Config from "../../Config.ts"
 import * as Effect from "../../Effect.ts"
 import * as FileSystem from "../../FileSystem.ts"
@@ -24,6 +21,9 @@ import * as Schema from "../../Schema.ts"
 import type { Formatter } from "../../SchemaIssue.ts"
 import type * as Struct from "../../Struct.ts"
 import type { Covariant } from "../../Types.ts"
+import * as Ini from "../encoding/Ini.ts"
+import * as Toml from "../encoding/Toml.ts"
+import * as Yaml from "../encoding/Yaml.ts"
 import type { Environment } from "./Command.ts"
 
 const TypeId = "~effect/cli/Primitive"
@@ -479,8 +479,8 @@ export type PathType = "file" | "directory" | "either"
 export const path = (
   pathType: PathType,
   mustExist?: boolean
-): Primitive<string> =>
-  makePrimitive(
+): Primitive<string> => {
+  const primitive = makePrimitive(
     "Path",
     Effect.fnUntraced(function*(value) {
       const fs = yield* FileSystem.FileSystem
@@ -518,6 +518,8 @@ export const path = (
       return absolutePath
     })
   )
+  return Object.assign(primitive, { pathType })
+}
 
 /**
  * Creates a primitive that wraps string input in `Redacted`.
@@ -984,3 +986,7 @@ export const getTypeName = <A>(primitive: Primitive<A>): string => {
 /** @internal */
 export const getChoiceKeys = (primitive: Primitive<unknown>): ReadonlyArray<string> | undefined =>
   primitive._tag === "Choice" ? (primitive as any).choiceKeys : undefined
+
+/** @internal */
+export const getPathType = (primitive: Primitive<unknown>): PathType | undefined =>
+  primitive._tag === "Path" ? (primitive as any).pathType : undefined

package/src/unstable/cli/Prompt.ts

@@ -693,10 +693,13 @@ export const all: <
   if (arguments.length === 1) {
     if (isPrompt(arguments[0])) {
       return map(arguments[0], (x) => [x]) as any
-    } else if (Array.isArray(arguments[0])) {
-      return allTupled(arguments[0]) as any
+    } else if (Predicate.isIterable(arguments[0])) {
+      return allTupled(Arr.fromIterable(arguments[0] as Iterable<Prompt<any>>)) as any
     } else {
       const entries = Object.entries(arguments[0] as Readonly<{ [K: string]: Prompt<any> }>)
+      if (entries.length === 0) {
+        return succeed({}) as any
+      }
       let result = map(entries[0][1], (value) => ({ [entries[0][0]]: value }))
       if (entries.length === 1) {
         return result as any
@@ -1274,7 +1277,7 @@ export const multiSelect = <const A>(
   const initialSelected = new Set<number>()
   for (let i = 0; i < opts.choices.length; i++) {
     const choice = opts.choices[i] as SelectChoice<A>
-    if (choice.selected === true) {
+    if (choice.selected === true && !choice.disabled) {
       initialSelected.add(i)
     }
   }
@@ -2057,6 +2060,9 @@ class Day extends DatePart {
   }
 
   private ordinalIndicator(day: number): string {
+    if (day >= 11 && day <= 13) {
+      return "th"
+    }
     switch (day % 10) {
       case 1:
         return "st"
@@ -2115,7 +2121,7 @@ class Year extends DatePart {
   override toString() {
     const year = `${this.date.getFullYear()}`.padStart(4, "0")
     return this.token.length === 2
-      ? year.substring(-2)
+      ? year.slice(-2)
       : year
   }
 }
@@ -2132,7 +2138,7 @@ class Meridiem extends DatePart {
   setValue(_value: string): void {}
 
   override toString() {
-    const meridiem = this.date.getHours() > 12 ? "pm" : "am"
+    const meridiem = this.date.getHours() >= 12 ? "pm" : "am"
     return /A/.test(this.token)
       ? meridiem.toUpperCase()
       : meridiem;
@@ -2619,9 +2625,9 @@ const renderMultiSelectChoices = <A>(
   renderOptions?: RenderOptions | undefined
 ) => {
   const choices = options.choices
-  const totalChoices = choices.length
-  const selectedCount = state.selectedIndices.size
-  const allSelected = selectedCount === totalChoices
+  const selectableCount = choices.filter((choice) => !choice.disabled).length
+  const selectedCount = Array.from(state.selectedIndices).filter((index) => !choices[index].disabled).length
+  const allSelected = selectedCount === selectableCount
 
   const selectAllText = allSelected
     ? options?.selectNone ?? "Select None"
@@ -2657,8 +2663,9 @@ const renderMultiSelectChoices = <A>(
       const annotatedCheckbox = isHighlighted && renderOptions?.plain !== true
         ? Ansi.annotate(checkbox, Ansi.cyanBright)
         : checkbox
-      const title = renderMultiSelectTitle(choice.title, isHighlighted, renderOptions)
-      const description = renderChoiceDescription(choice as SelectChoice<A>, isHighlighted, renderOptions)
+      const selectChoice = choice as SelectChoice<A>
+      const title = renderChoiceTitle(selectChoice, isHighlighted, renderOptions)
+      const description = renderChoiceDescription(selectChoice, isHighlighted, renderOptions)
       documents.push(prefix + " " + annotatedCheckbox + " " + title + " " + description)
     }
   }
@@ -2707,16 +2714,20 @@ const processSpace = <A>(
 ) => {
   const selectedIndices = new Set(state.selectedIndices)
   if (state.index === 0) {
-    if (state.selectedIndices.size === options.choices.length) {
+    const selectableCount = options.choices.filter((choice) => !choice.disabled).length
+    const selectedCount = Array.from(state.selectedIndices).filter((index) => !options.choices[index].disabled).length
+    if (selectedCount === selectableCount) {
       selectedIndices.clear()
     } else {
       for (let i = 0; i < options.choices.length; i++) {
-        selectedIndices.add(i)
+        if (!options.choices[i].disabled) {
+          selectedIndices.add(i)
+        }
       }
     }
   } else if (state.index === 1) {
     for (let i = 0; i < options.choices.length; i++) {
-      if (state.selectedIndices.has(i)) {
+      if (options.choices[i].disabled || state.selectedIndices.has(i)) {
         selectedIndices.delete(i)
       } else {
         selectedIndices.add(i)
@@ -2724,7 +2735,9 @@ const processSpace = <A>(
     }
   } else {
     const choiceIndex = state.index - metaOptionsCount
-    if (selectedIndices.has(choiceIndex)) {
+    if (options.choices[choiceIndex].disabled) {
+      return Effect.succeed(Action.Beep())
+    } else if (selectedIndices.has(choiceIndex)) {
       selectedIndices.delete(choiceIndex)
     } else {
       selectedIndices.add(choiceIndex)
@@ -2764,7 +2777,8 @@ const handleMultiSelectProcess = <A>(options: SelectOptionsReq<A> & MultiSelectO
       }
       case "enter":
       case "return": {
-        const selectedCount = state.selectedIndices.size
+        const selectedIndices = Array.from(state.selectedIndices).filter((index) => !options.choices[index].disabled)
+        const selectedCount = selectedIndices.length
         if (options.min !== undefined && selectedCount < options.min) {
           return Effect.succeed(
             Action.NextFrame({ state: { ...state, error: Option.some(`At least ${options.min} are required`) } })
@@ -2775,9 +2789,7 @@ const handleMultiSelectProcess = <A>(options: SelectOptionsReq<A> & MultiSelectO
             Action.NextFrame({ state: { ...state, error: Option.some(`At most ${options.max} choices are allowed`) } })
           )
         }
-        const selectedValues = Array.from(state.selectedIndices).sort(EffectNumber.Order).map((index) =>
-          options.choices[index].value
-        )
+        const selectedValues = selectedIndices.sort(EffectNumber.Order).map((index) => options.choices[index].value)
         return Effect.succeed(Action.Submit({ value: selectedValues }))
       }
       default: {
@@ -2933,10 +2945,14 @@ const defaultFloatProcessor = (input: string, state: NumberState) => {
     return Effect.succeed(Action.NextFrame({
       state: {
         ...state,
-        value: input === "." ? `${parsed}.` : `${parsed}`,
+        value: input === "."
+          ? `${parsed}.`
+          : state.value.includes(".") && /^\d$/.test(input)
+          ? state.value + input
+          : `${parsed}`,
         error: Option.none()
       }
-    }))
+    }));
   }
 }
 

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

@@ -79,9 +79,9 @@ export const combine = (...styles: Array<string>): Array<string> => styles
 /** @internal */
 export const cursorTo = (column: number, row?: number): string => {
   if (row === undefined) {
-    return `\x1b${Math.max(column + 1, 0)} G`
+    return `${ESC}${Math.max(column + 1, 0)}G`
   }
-  return `\x1b${row + 1}${SEP}${Math.max(column + 1, 0)} H`
+  return `${ESC}${row + 1}${SEP}${Math.max(column + 1, 0)}H`
 }
 
 /** @internal */

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

@@ -98,7 +98,7 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
   readonly description?: string | undefined
   readonly shortDescription?: string | undefined
   readonly alias?: string | undefined
-  readonly hidden?: boolean | undefined
+  readonly unlisted?: boolean | undefined
   readonly examples?: ReadonlyArray<Command.Example> | undefined
   readonly subcommands?: ReadonlyArray<SubcommandGroup> | undefined
   readonly parse?: ((input: ParsedTokens) => Effect.Effect<Input, CliError.CliError, Environment>) | undefined
@@ -139,7 +139,8 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
           name: single.name,
           type: single.typeName ?? Primitive.getTypeName(single.primitiveType),
           description: single.description,
-          required: !metadata.isOptional,
+          required: !metadata.isOptional &&
+            (!metadata.isVariadic || Option.exists(metadata.variadicMin, (min) => min > 0)),
           variadic: metadata.isVariadic
         })
       }
@@ -147,8 +148,8 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
 
     let usage = commandPath.length > 0 ? commandPath.join(" ") : options.name
     // Only render `<subcommand>` in usage when at least one visible subcommand
-    // exists; an all-hidden subcommand tree should look like a leaf command.
-    if (subcommands.some((group) => group.commands.some((c) => !c.hidden))) {
+    // exists; an all-unlisted subcommand tree should look like a leaf command.
+    if (subcommands.some((group) => group.commands.some((c) => !c.unlisted))) {
       usage += " <subcommand>"
     }
     usage += " [flags]"
@@ -159,21 +160,22 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
 
     for (const option of config.flags) {
       const singles = Param.extractSingleParams(option)
+      const metadata = Param.getParamMetadata(option)
       for (const single of singles) {
         // Hidden flags still parse on the command line but are omitted from
         // generated --help output.
         if (single.hidden) continue
-        flags.push(toFlagDoc(single))
+        flags.push(toFlagDoc(single, metadata))
       }
     }
 
     const subcommandDocs: Array<SubcommandGroupDoc> = []
 
     for (const group of subcommands) {
-      // Hidden subcommands still parse on the command line but are omitted
+      // Unlisted subcommands still parse on the command line but are omitted
       // from --help. Drop the whole group when nothing visible remains so we
       // don't render an empty heading.
-      const visible = group.commands.filter((c) => !c.hidden)
+      const visible = group.commands.filter((c) => !c.unlisted)
       if (visible.length === 0) continue
       subcommandDocs.push({
         group: group.group,
@@ -206,7 +208,7 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
     annotations,
     globalFlags,
     subcommands,
-    hidden: options.hidden ?? false,
+    unlisted: options.unlisted ?? false,
     config,
     contextConfig,
     service,
@@ -233,14 +235,17 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
 /**
  * Converts a single flag param into a FlagDoc for help display.
  */
-export const toFlagDoc = (single: Param.Single<typeof Param.flagKind, unknown>): FlagDoc => {
+export const toFlagDoc = (
+  single: Param.Single<typeof Param.flagKind, unknown>,
+  metadata: ReturnType<typeof Param.getParamMetadata>
+): FlagDoc => {
   const formattedAliases = single.aliases.map((alias) => alias.length === 1 ? `-${alias}` : `--${alias}`)
   return {
     name: single.name,
     aliases: formattedAliases,
     type: single.typeName ?? Primitive.getTypeName(single.primitiveType),
     description: appendChoiceKeys(single.description, Primitive.getChoiceKeys(single.primitiveType)),
-    required: single.primitiveType._tag !== "Boolean"
+    required: single.primitiveType._tag !== "Boolean" && !metadata.isOptional
   }
 }