Allow selecting a specific shell (#11851)

* Allow selecting a specific shell

Add --terminal-shell CLI flag to specify which shell ExecaTerminalProcess
uses for inline command execution. The shell path is validated at the CLI
layer and passed through the standard settings mechanism (BaseTerminal
static getter/setter), matching how all other CLI terminal settings flow
through the system.

* test(cli): make shell path access test cross-platform

Author: jr

apps/cli/README.md

@@ -184,6 +184,7 @@ Tokens are valid for 90 days. The CLI will prompt you to re-authenticate when yo
 | `--provider <provider>`           | API provider (roo, anthropic, openai, openrouter, etc.)                                 | `openrouter` (or `roo` if authenticated) |
 | `-m, --model <model>`             | Model to use                                                                            | `anthropic/claude-opus-4.6`              |
 | `--mode <mode>`                   | Mode to start in (code, architect, ask, debug, etc.)                                    | `code`                                   |
+| `--terminal-shell <path>`         | Absolute shell path for inline terminal command execution                               | Auto-detected shell                      |
 | `-r, --reasoning-effort <effort>` | Reasoning effort level (unspecified, disabled, none, minimal, low, medium, high, xhigh) | `medium`                                 |
 | `--consecutive-mistake-limit <n>` | Consecutive error/repetition limit before guidance prompt (`0` disables the limit)      | `10`                                     |
 | `--ephemeral`                     | Run without persisting state (uses temporary storage)                                   | `false`                                  |

apps/cli/src/agent/__tests__/extension-host.test.ts

@@ -158,6 +158,22 @@ describe("ExtensionHost", () => {
 			createTestHost()
 			expect(process.env.ROO_CLI_RUNTIME).toBe("1")
 		})
+
+		it("should set execaShellPath in initialSettings when terminalShell is provided", () => {
+			const host = createTestHost({ terminalShell: "/bin/bash" })
+			const emitSpy = vi.spyOn(host, "emit")
+			host.markWebviewReady()
+			const updateSettingsCall = emitSpy.mock.calls.find(
+				(call) =>
+					call[0] === "webviewMessage" &&
+					typeof call[1] === "object" &&
+					call[1] !== null &&
+					(call[1] as WebviewMessage).type === "updateSettings",
+			)
+			expect(updateSettingsCall).toBeDefined()
+			const payload = updateSettingsCall?.[1] as WebviewMessage
+			expect(payload.updatedSettings?.execaShellPath).toBe("/bin/bash")
+		})
 	})
 
 	describe("webview provider registration", () => {
@@ -238,6 +254,26 @@ describe("ExtensionHost", () => {
 				)
 				expect(updateSettingsCall).toBeDefined()
 			})
+
+			it("should force terminalShellIntegrationDisabled when terminalShell is provided", () => {
+				const host = createTestHost({ terminalShell: "/bin/bash" })
+				const emitSpy = vi.spyOn(host, "emit")
+
+				host.markWebviewReady()
+
+				const updateSettingsCall = emitSpy.mock.calls.find(
+					(call) =>
+						call[0] === "webviewMessage" &&
+						typeof call[1] === "object" &&
+						call[1] !== null &&
+						(call[1] as WebviewMessage).type === "updateSettings",
+				)
+
+				expect(updateSettingsCall).toBeDefined()
+				const payload = updateSettingsCall?.[1] as WebviewMessage
+				expect(payload.type).toBe("updateSettings")
+				expect(payload.updatedSettings?.terminalShellIntegrationDisabled).toBe(true)
+			})
 		})
 	})
 

apps/cli/src/agent/extension-host.ts

@@ -80,6 +80,7 @@ export interface ExtensionHostOptions {
 	ephemeral: boolean
 	debug: boolean
 	exitOnComplete: boolean
+	terminalShell?: string
 	/**
 	 * When true, exit the process on API request errors instead of retrying.
 	 */
@@ -257,6 +258,11 @@ export class ExtensionHost extends EventEmitter implements ExtensionHostInterfac
 				this.initialSettings.reasoningEffort = this.options.reasoningEffort
 			}
 		}
+
+		if (this.options.terminalShell) {
+			this.initialSettings.terminalShellIntegrationDisabled = true
+			this.initialSettings.execaShellPath = this.options.terminalShell
+		}
 	}
 
 	// ==========================================================================

apps/cli/src/commands/cli/run.ts

@@ -26,6 +26,7 @@ import { readWorkspaceTaskSessions, resolveWorkspaceResumeSessionId } from "@/li
 import { isRecord } from "@/lib/utils/guards.js"
 import { getEnvVarName, getApiKeyFromEnv } from "@/lib/utils/provider.js"
 import { runOnboarding } from "@/lib/utils/onboarding.js"
+import { validateTerminalShellPath } from "@/lib/utils/shell.js"
 import { getDefaultExtensionPath } from "@/lib/utils/extension.js"
 import { VERSION } from "@/lib/utils/version.js"
 
@@ -176,6 +177,19 @@ export async function run(promptArg: string | undefined, flagOptions: FlagOption
 		process.exit(1)
 	}
 
+	let terminalShell: string | undefined
+	if (flagOptions.terminalShell !== undefined) {
+		const validatedTerminalShell = await validateTerminalShellPath(flagOptions.terminalShell)
+
+		if (!validatedTerminalShell.valid) {
+			console.error(
+				`[CLI] Warning: ignoring --terminal-shell "${flagOptions.terminalShell}" (${validatedTerminalShell.reason})`,
+			)
+		} else {
+			terminalShell = validatedTerminalShell.shellPath
+		}
+	}
+
 	const extensionHostOptions: ExtensionHostOptions = {
 		mode: effectiveMode,
 		reasoningEffort: effectiveReasoningEffort === "unspecified" ? undefined : effectiveReasoningEffort,
@@ -190,6 +204,7 @@ export async function run(promptArg: string | undefined, flagOptions: FlagOption
 		ephemeral: flagOptions.ephemeral,
 		debug: flagOptions.debug,
 		exitOnComplete: effectiveExitOnComplete,
+		terminalShell,
 	}
 
 	// Roo Code Cloud Authentication

apps/cli/src/index.ts

@@ -47,6 +47,7 @@ program
 	.option("--provider <provider>", "API provider (roo, anthropic, openai, openrouter, etc.)")
 	.option("-m, --model <model>", "Model to use", DEFAULT_FLAGS.model)
 	.option("--mode <mode>", "Mode to start in (code, architect, ask, debug, etc.)", DEFAULT_FLAGS.mode)
+	.option("--terminal-shell <path>", "Absolute path to shell executable for inline terminal commands")
 	.option(
 		"-r, --reasoning-effort <effort>",
 		"Reasoning effort level (unspecified, disabled, none, minimal, low, medium, high, xhigh)",

apps/cli/src/lib/utils/__tests__/shell.test.ts

@@ -0,0 +1,54 @@
+import fs from "fs/promises"
+
+import { validateTerminalShellPath } from "../shell.js"
+
+vi.mock("fs/promises", () => ({
+	default: {
+		access: vi.fn(),
+		stat: vi.fn(),
+	},
+}))
+
+describe("validateTerminalShellPath", () => {
+	beforeEach(() => {
+		vi.clearAllMocks()
+		vi.mocked(fs.access).mockResolvedValue(undefined)
+		vi.mocked(fs.stat).mockResolvedValue({
+			isFile: () => true,
+		} as unknown as Awaited<ReturnType<typeof fs.stat>>)
+	})
+
+	it("returns invalid for an empty path", async () => {
+		const result = await validateTerminalShellPath("   ")
+		expect(result).toEqual({ valid: false, reason: "shell path cannot be empty" })
+	})
+
+	it("returns invalid for a relative path", async () => {
+		const result = await validateTerminalShellPath("bin/bash")
+		expect(result).toEqual({ valid: false, reason: "shell path must be absolute" })
+	})
+
+	it("returns valid for an absolute executable path", async () => {
+		const result = await validateTerminalShellPath("/bin/bash")
+		expect(result).toEqual({ valid: true, shellPath: "/bin/bash" })
+	})
+
+	it("returns invalid when the shell path cannot be accessed", async () => {
+		vi.mocked(fs.stat).mockRejectedValueOnce(new Error("ENOENT"))
+		const result = await validateTerminalShellPath("/missing/shell")
+
+		expect(result.valid).toBe(false)
+		if (!result.valid) {
+			expect(result.reason).toContain("shell path")
+		}
+	})
+
+	it("returns invalid when the shell path points to a directory", async () => {
+		vi.mocked(fs.stat).mockResolvedValueOnce({
+			isFile: () => false,
+		} as unknown as Awaited<ReturnType<typeof fs.stat>>)
+		const result = await validateTerminalShellPath("/bin")
+
+		expect(result).toEqual({ valid: false, reason: "shell path must point to a file" })
+	})
+})

apps/cli/src/lib/utils/shell.ts

@@ -0,0 +1,47 @@
+import fs from "fs/promises"
+import { constants as fsConstants } from "fs"
+import path from "path"
+
+export type TerminalShellValidationResult =
+	| {
+			valid: true
+			shellPath: string
+	  }
+	| {
+			valid: false
+			reason: string
+	  }
+
+export async function validateTerminalShellPath(rawShellPath: string): Promise<TerminalShellValidationResult> {
+	const shellPath = rawShellPath.trim()
+
+	if (!shellPath) {
+		return { valid: false, reason: "shell path cannot be empty" }
+	}
+
+	if (!path.isAbsolute(shellPath)) {
+		return { valid: false, reason: "shell path must be absolute" }
+	}
+
+	try {
+		const stats = await fs.stat(shellPath)
+
+		if (!stats.isFile()) {
+			return { valid: false, reason: "shell path must point to a file" }
+		}
+
+		if (process.platform !== "win32") {
+			await fs.access(shellPath, fsConstants.X_OK)
+		}
+	} catch {
+		return {
+			valid: false,
+			reason:
+				process.platform === "win32"
+					? "shell path does not exist or is not a file"
+					: "shell path does not exist, is not a file, or is not executable",
+		}
+	}
+
+	return { valid: true, shellPath }
+}

apps/cli/src/types/types.ts

@@ -34,6 +34,7 @@ export type FlagOptions = {
 	provider?: SupportedProvider
 	model?: string
 	mode?: string
+	terminalShell?: string
 	reasoningEffort?: ReasoningEffortFlagOptions
 	consecutiveMistakeLimit?: number
 	ephemeral: boolean

packages/types/src/global-settings.ts

@@ -176,6 +176,7 @@ export const globalSettingsSchema = z.object({
 	terminalZshOhMy: z.boolean().optional(),
 	terminalZshP10k: z.boolean().optional(),
 	terminalZdotdir: z.boolean().optional(),
+	execaShellPath: z.string().optional(),
 
 	diagnosticsEnabled: z.boolean().optional(),
 

packages/types/src/vscode-extension-host.ts

@@ -282,6 +282,7 @@ export type ExtensionState = Pick<
 	| "terminalZshOhMy"
 	| "terminalZshP10k"
 	| "terminalZdotdir"
+	| "execaShellPath"
 	| "diagnosticsEnabled"
 	| "language"
 	| "modeApiConfigs"