feat(cli): add Command.runWithWizard for programmatic wizard mode

Adds a new API to programmatically invoke wizard mode based on custom conditions.
This allows CLI authors to enable wizard mode in scenarios beyond just the --wizard flag.

Key features:
- Command.runWithWizard() accepts a shouldRunWizard predicate function
- When the predicate returns true, wizard mode is automatically invoked
- Common use case: run wizard when bare command is executed (no args)
- Fully backwards compatible with existing --wizard flag behavior
- Comprehensive test coverage

Example usage:
```typescript
const cli = Command.runWithWizard(command, {
  name: "MyApp",
  version: "1.0.0",
  shouldRunWizard: (args) => args.length <= 1
})
```

Fixes #5699

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: ryanbas21

.changeset/soft-oranges-arrive.md

@@ -0,0 +1,5 @@
+---
+"@effect/cli": minor
+---
+
+Add runWithWizard for a programmatic wizard mode

packages/cli/src/Command.ts

@@ -441,3 +441,51 @@ export const run: {
     config: Omit<CliApp.ConstructorArgs<never>, "command">
   ): (args: ReadonlyArray<string>) => Effect<void, E | ValidationError, R | CliApp.Environment>
 } = Internal.run
+
+/**
+ * Creates a CLI application from a `Command` with optional automatic wizard mode fallback.
+ * 
+ * This function is similar to `run`, but allows you to specify when wizard mode should
+ * be automatically invoked. This is useful when you want to provide an interactive
+ * experience for users who run your CLI without arguments or in specific scenarios.
+ *
+ * @example
+ * ```typescript
+ * import { Command, Options } from "@effect/cli"
+ * import { Effect } from "effect"
+ * 
+ * const command = Command.make("greet", {
+ *   name: Options.text("name")
+ * }, ({ name }) => 
+ *   Effect.log(`Hello, ${name}!`)
+ * )
+ * 
+ * // Run wizard mode when no arguments are provided (besides the command name)
+ * const cli = Command.runWithWizard(command, {
+ *   name: "MyApp",
+ *   version: "1.0.0",
+ *   shouldRunWizard: (args) => args.length <= 1
+ * })
+ * 
+ * // Running `mycli` (no args) will start wizard mode
+ * // Running `mycli --name John` will execute normally
+ * ```
+ *
+ * @since 1.0.0
+ * @category conversions
+ */
+export const runWithWizard: {
+  (
+    config: Omit<CliApp.ConstructorArgs<never>, "command"> & {
+      readonly shouldRunWizard?: (args: ReadonlyArray<string>) => boolean
+    }
+  ): <Name extends string, R, E, A>(
+    self: Command<Name, R, E, A>
+  ) => (args: ReadonlyArray<string>) => Effect<void, E | ValidationError | QuitException, R | CliApp.Environment>
+  <Name extends string, R, E, A>(
+    self: Command<Name, R, E, A>,
+    config: Omit<CliApp.ConstructorArgs<never>, "command"> & {
+      readonly shouldRunWizard?: (args: ReadonlyArray<string>) => boolean
+    }
+  ): (args: ReadonlyArray<string>) => Effect<void, E | ValidationError | QuitException, R | CliApp.Environment>
+} = Internal.runWithWizard

packages/cli/src/internal/command.ts

@@ -25,6 +25,7 @@ import type * as Usage from "../Usage.js"
 import * as ValidationError from "../ValidationError.js"
 import * as InternalArgs from "./args.js"
 import * as InternalCliApp from "./cliApp.js"
+import * as InternalCliConfig from "./cliConfig.js"
 import * as InternalDescriptor from "./commandDescriptor.js"
 import * as InternalOptions from "./options.js"
 
@@ -558,3 +559,45 @@ export const run = dual<
   const handler = (args: any) => self.transform(self.handler(args), args)
   return (args) => InternalCliApp.run(app, args, handler)
 })
+
+/** @internal */
+export const runWithWizard = dual<
+  (
+    config: Omit<CliApp.CliApp.ConstructorArgs<never>, "command"> & {
+      readonly shouldRunWizard?: (args: ReadonlyArray<string>) => boolean
+    }
+  ) => <Name extends string, R, E, A>(
+    self: Command.Command<Name, R, E, A>
+  ) => (
+    args: ReadonlyArray<string>
+  ) => Effect.Effect<void, E | ValidationError.ValidationError | Terminal.QuitException, R | CliApp.CliApp.Environment>,
+  <Name extends string, R, E, A>(
+    self: Command.Command<Name, R, E, A>,
+    config: Omit<CliApp.CliApp.ConstructorArgs<never>, "command"> & {
+      readonly shouldRunWizard?: (args: ReadonlyArray<string>) => boolean
+    }
+  ) => (
+    args: ReadonlyArray<string>
+  ) => Effect.Effect<void, E | ValidationError.ValidationError | Terminal.QuitException, R | CliApp.CliApp.Environment>
+>(2, (self, config) => {
+  const { shouldRunWizard = () => false, ...restConfig } = config
+  const app = InternalCliApp.make({
+    ...restConfig,
+    command: self.descriptor
+  })
+  registeredDescriptors.set(self.tag, self.descriptor)
+  const handler = (args: any) => self.transform(self.handler(args), args)
+  const normalRun = (args: ReadonlyArray<string>) => InternalCliApp.run(app, args, handler)
+  
+  return (args) => {
+    // If shouldRunWizard returns true, run wizard mode first
+    if (shouldRunWizard(args)) {
+      const prefix = Arr.take(args, 1) // Get the command name from args
+      const cliConfig = InternalCliConfig.defaultConfig
+      return wizard(self, prefix, cliConfig).pipe(
+        Effect.flatMap((wizardArgs) => normalRun(wizardArgs))
+      )
+    }
+    return normalRun(args)
+  }
+})

packages/cli/test/Wizard.test.ts

@@ -1,4 +1,5 @@
 import type * as CliApp from "@effect/cli/CliApp"
+import * as Args from "@effect/cli/Args"
 import * as Command from "@effect/cli/Command"
 import * as Options from "@effect/cli/Options"
 import { NodeFileSystem, NodePath } from "@effect/platform-node"
@@ -41,4 +42,76 @@ describe("Wizard", () => {
       const result = Array.some(lines, (line) => line.includes("Quitting wizard mode..."))
       expect(result).toBe(true)
     }).pipe(runEffect))
+
+  describe("runWithWizard", () => {
+    it("should skip wizard mode when shouldRunWizard returns false", () =>
+      Effect.gen(function*() {
+        let executedWithName: string | undefined
+        const command = Command.make("greet", {
+          name: Options.text("name")
+        }, ({ name }) => Effect.sync(() => { executedWithName = name })).pipe(
+          Command.withDescription("Greet someone")
+        )
+
+        const cli = Command.runWithWizard(command, {
+          name: "Test",
+          version: "1.0.0",
+          shouldRunWizard: (args) => args.length <= 1
+        })
+
+        // Simulate running with args (should NOT trigger wizard)
+        const args = Array.make("node", "greet", "--name", "Bob")
+        yield* cli(args)
+
+        // Verify the command was executed with the provided value
+        expect(executedWithName).toBe("Bob")
+
+        const lines = yield* MockConsole.getLines({ stripAnsi: true })
+        const wizardStarted = Array.some(lines, (line) =>
+          line.includes("Wizard Mode") || line.includes("wizard")
+        )
+        // Wizard should NOT have been started
+        expect(wizardStarted).toBe(false)
+      }).pipe(runEffect))
+
+    it("should allow default shouldRunWizard behavior (always false)", () =>
+      Effect.gen(function*() {
+        let executedWithName: string | undefined
+        const command = Command.make("greet", {
+          name: Options.text("name")
+        }, ({ name }) => Effect.sync(() => { executedWithName = name }))
+
+        // Don't provide shouldRunWizard - should default to always false
+        const cli = Command.runWithWizard(command, {
+          name: "Test",
+          version: "1.0.0"
+        })
+
+        const args = Array.make("node", "greet", "--name", "Charlie")
+        yield* cli(args)
+
+        expect(executedWithName).toBe("Charlie")
+      }).pipe(runEffect))
+
+    it("should use standard wizard flag when shouldRunWizard is not triggered", () =>
+      Effect.gen(function*() {
+        const command = Command.make("foo", { message: Options.text("message") })
+
+        const cli = Command.runWithWizard(command, {
+          name: "Test",
+          version: "1.0.0",
+          shouldRunWizard: (args) => args.length <= 1
+        })
+
+        // Using --wizard flag explicitly (shouldRunWizard returns false because args.length > 1)
+        const args = Array.make("node", "test", "--wizard")
+        const fiber = yield* Effect.fork(cli(args))
+        yield* MockTerminal.inputKey("c", { ctrl: true })
+        yield* Fiber.join(fiber)
+
+        const lines = yield* MockConsole.getLines({ stripAnsi: true })
+        const result = Array.some(lines, (line) => line.includes("Quitting wizard mode..."))
+        expect(result).toBe(true)
+      }).pipe(runEffect))
+  })
 })