ralph-cli-sandboxed 0.1.5 → 0.2.0

package/README.md

@@ -29,8 +29,8 @@ ralph add
 # 3. Run a single iteration
 ralph once
 
-# 4. Or run multiple iterations
-ralph run 5
+# 4. Or run until all tasks complete (default)
+ralph run
 ```
 
 ## Commands
@@ -39,13 +39,13 @@ ralph run 5
 |---------|-------------|
 | `ralph init` | Initialize ralph in current project |
 | `ralph once` | Run a single automation iteration |
-| `ralph run <n>` | Run n automation iterations |
+| `ralph run [n]` | Run automation iterations (default: all tasks) |
 | `ralph add` | Add a new PRD entry (interactive) |
 | `ralph list` | List all PRD entries |
 | `ralph status` | Show PRD completion status |
 | `ralph toggle <n>` | Toggle passes status for entry n |
 | `ralph clean` | Remove all passing entries from PRD |
-| `ralph docker` | Generate Docker sandbox environment |
+| `ralph docker <sub>` | Manage Docker sandbox environment |
 | `ralph help` | Show help message |
 
 > **Note:** `ralph prd <subcommand>` still works for compatibility (e.g., `ralph prd add`).
@@ -116,13 +116,13 @@ Run ralph in an isolated Docker container:
 
 ```bash
 # Generate Docker files
-ralph docker
+ralph docker init
 
 # Build the image
-ralph docker --build
+ralph docker build
 
 # Run container
-ralph docker --run
+ralph docker run
 ```
 
 Features:

package/dist/commands/docker.js

@@ -3,7 +3,7 @@ import { join, basename } from "path";
 import { spawn } from "child_process";
 import { loadConfig, getRalphDir } from "../utils/config.js";
 import { promptConfirm } from "../utils/prompt.js";
-import { getLanguagesJson } from "../templates/prompts.js";
+import { getLanguagesJson, getCliProvidersJson } from "../templates/prompts.js";
 const DOCKER_DIR = "docker";
 // Get language Docker snippet from config, with version substitution
 function getLanguageSnippet(language, javaVersion) {
@@ -22,8 +22,20 @@ function getLanguageSnippet(language, javaVersion) {
     }
     return "\n" + snippet + "\n";
 }
-function generateDockerfile(language, javaVersion) {
+// Get CLI provider Docker snippet from config
+function getCliProviderSnippet(cliProvider) {
+    const cliProvidersJson = getCliProvidersJson();
+    const providerKey = cliProvider || "claude";
+    const provider = cliProvidersJson.providers[providerKey];
+    if (!provider || !provider.docker) {
+        // Default to Claude Code CLI if provider not found
+        return "# Install Claude Code CLI\nRUN curl -fsSL https://claude.ai/install.sh | bash";
+    }
+    return provider.docker.install;
+}
+function generateDockerfile(language, javaVersion, cliProvider) {
     const languageSnippet = getLanguageSnippet(language, javaVersion);
+    const cliSnippet = getCliProviderSnippet(cliProvider);
     return `# Ralph CLI Sandbox Environment
 # Based on Claude Code devcontainer
 # Generated by ralph-cli
@@ -32,7 +44,6 @@ FROM node:20-bookworm
 
 ARG DEBIAN_FRONTEND=noninteractive
 ARG TZ=UTC
-ARG CLAUDE_CODE_VERSION="latest"
 ARG ZSH_IN_DOCKER_VERSION="1.2.1"
 
 # Set timezone
@@ -92,11 +103,10 @@ RUN cp -r /root/.oh-my-zsh /home/node/.oh-my-zsh && chown -R node:node /home/nod
     echo '  echo ""' >> /home/node/.zshrc && \\
     echo 'fi' >> /home/node/.zshrc
 
-# Install Claude Code CLI
-RUN npm install -g @anthropic-ai/claude-code@\${CLAUDE_CODE_VERSION}
+${cliSnippet}
 
-# Install ralph-cli-claude from npm registry
-RUN npm install -g ralph-cli-claude
+# Install ralph-cli-sandboxed from npm registry
+RUN npm install -g ralph-cli-sandboxed
 ${languageSnippet}
 # Setup sudo only for firewall script (no general sudo for security)
 RUN echo "node ALL=(ALL) NOPASSWD: /usr/local/bin/init-firewall.sh" >> /etc/sudoers.d/node-firewall
@@ -245,7 +255,7 @@ dist
 .git
 *.log
 `;
-async function generateFiles(ralphDir, language, imageName, force = false, javaVersion) {
+async function generateFiles(ralphDir, language, imageName, force = false, javaVersion, cliProvider) {
     const dockerDir = join(ralphDir, DOCKER_DIR);
     // Create docker directory
     if (!existsSync(dockerDir)) {
@@ -253,7 +263,7 @@ async function generateFiles(ralphDir, language, imageName, force = false, javaV
         console.log(`Created ${DOCKER_DIR}/`);
     }
     const files = [
-        { name: "Dockerfile", content: generateDockerfile(language, javaVersion) },
+        { name: "Dockerfile", content: generateDockerfile(language, javaVersion, cliProvider) },
         { name: "init-firewall.sh", content: FIREWALL_SCRIPT },
         { name: "docker-compose.yml", content: generateDockerCompose(imageName) },
         { name: ".dockerignore", content: DOCKERIGNORE },
@@ -280,9 +290,9 @@ async function buildImage(ralphDir) {
         console.error("Dockerfile not found. Run 'ralph docker' first.");
         process.exit(1);
     }
-    console.log("Building Docker image (fetching latest Claude Code)...\n");
+    console.log("Building Docker image...\n");
     return new Promise((resolve, reject) => {
-        // Use --no-cache and --pull to ensure we always get the latest Claude Code version
+        // Use --no-cache and --pull to ensure we always get the latest CLI versions
         const proc = spawn("docker", ["compose", "build", "--no-cache", "--pull"], {
             cwd: dockerDir,
             stdio: "inherit",
@@ -319,7 +329,7 @@ async function imageExists(imageName) {
         });
     });
 }
-async function runContainer(ralphDir, imageName, language, javaVersion) {
+async function runContainer(ralphDir, imageName, language, javaVersion, cliProvider) {
     const dockerDir = join(ralphDir, DOCKER_DIR);
     const dockerfileExists = existsSync(join(dockerDir, "Dockerfile"));
     const hasImage = await imageExists(imageName);
@@ -327,7 +337,7 @@ async function runContainer(ralphDir, imageName, language, javaVersion) {
     if (!dockerfileExists || !hasImage) {
         if (!dockerfileExists) {
             console.log("Docker folder not found. Initializing docker setup...\n");
-            await generateFiles(ralphDir, language, imageName, true, javaVersion);
+            await generateFiles(ralphDir, language, imageName, true, javaVersion, cliProvider);
             console.log("");
         }
         if (!hasImage) {
@@ -514,23 +524,24 @@ async function cleanImage(imageName, ralphDir) {
         });
     });
     console.log("\nDocker image and associated resources cleaned.");
-    console.log("Run 'ralph docker --build' to rebuild the image.");
+    console.log("Run 'ralph docker build' to rebuild the image.");
 }
 export async function docker(args) {
-    const hasFlag = (flag) => args.includes(flag);
-    const flag = args[0];
+    const subcommand = args[0];
+    const subArgs = args.slice(1);
     // Show help without requiring init
-    if (flag === "--help" || flag === "-h") {
+    if (subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
         console.log(`
 ralph docker - Generate and manage Docker sandbox environment
 
 USAGE:
-  ralph docker              Generate Dockerfile and scripts
-  ralph docker -y           Generate files, overwrite without prompting
-  ralph docker --build      Build image (always fetches latest Claude Code)
-  ralph docker --build --clean  Clean existing image and rebuild from scratch
-  ralph docker --run        Run container (auto-init and build if needed)
-  ralph docker --clean      Remove Docker image and associated resources
+  ralph docker init         Generate Dockerfile and scripts
+  ralph docker init -y      Generate files, overwrite without prompting
+  ralph docker build        Build image (fetches latest CLI versions)
+  ralph docker build --clean  Clean existing image and rebuild from scratch
+  ralph docker run          Run container (auto-init and build if needed)
+  ralph docker clean        Remove Docker image and associated resources
+  ralph docker help         Show this help message
 
 FILES GENERATED:
   .ralph/docker/
@@ -544,11 +555,11 @@ AUTHENTICATION:
   API key users: Uncomment ANTHROPIC_API_KEY in docker-compose.yml.
 
 EXAMPLES:
-  ralph docker                      # Generate files
-  ralph docker --build              # Build image
-  ralph docker --build --clean      # Clean and rebuild from scratch
-  ralph docker --run                # Start interactive shell
-  ralph docker --clean              # Remove image and volumes
+  ralph docker init               # Generate files
+  ralph docker build              # Build image
+  ralph docker build --clean      # Clean and rebuild from scratch
+  ralph docker run                # Start interactive shell
+  ralph docker clean              # Remove image and volumes
 
   # Or use docker compose directly:
   cd .ralph/docker && docker compose run --rm ralph
@@ -578,38 +589,48 @@ INSTALLING PACKAGES (works with Docker & Podman):
     const config = loadConfig();
     // Get image name from config or generate default
     const imageName = config.imageName || `ralph-${basename(process.cwd()).toLowerCase().replace(/[^a-z0-9-]/g, "-")}`;
-    // Handle --build --clean combination: clean first, then build
-    if (hasFlag("--build") && hasFlag("--clean")) {
-        await cleanImage(imageName, ralphDir);
-        console.log(""); // Add spacing between clean and build output
-        await buildImage(ralphDir);
-    }
-    else if (hasFlag("--build")) {
-        await buildImage(ralphDir);
-    }
-    else if (hasFlag("--run")) {
-        await runContainer(ralphDir, imageName, config.language, config.javaVersion);
-    }
-    else if (hasFlag("--clean")) {
-        await cleanImage(imageName, ralphDir);
-    }
-    else {
-        const force = flag === "-y" || flag === "--yes";
-        console.log(`Generating Docker files for: ${config.language}`);
-        if ((config.language === "java" || config.language === "kotlin") && config.javaVersion) {
-            console.log(`Java version: ${config.javaVersion}`);
-        }
-        console.log(`Image name: ${imageName}\n`);
-        await generateFiles(ralphDir, config.language, imageName, force, config.javaVersion);
-        console.log(`
+    const hasFlag = (flag) => subArgs.includes(flag);
+    switch (subcommand) {
+        case "build":
+            // Handle build --clean combination: clean first, then build
+            if (hasFlag("--clean")) {
+                await cleanImage(imageName, ralphDir);
+                console.log(""); // Add spacing between clean and build output
+            }
+            await buildImage(ralphDir);
+            break;
+        case "run":
+            await runContainer(ralphDir, imageName, config.language, config.javaVersion, config.cliProvider);
+            break;
+        case "clean":
+            await cleanImage(imageName, ralphDir);
+            break;
+        case "init":
+        default: {
+            // Default to init if no subcommand or unrecognized subcommand
+            const force = subcommand === "init"
+                ? (subArgs[0] === "-y" || subArgs[0] === "--yes")
+                : (subcommand === "-y" || subcommand === "--yes");
+            console.log(`Generating Docker files for: ${config.language}`);
+            if ((config.language === "java" || config.language === "kotlin") && config.javaVersion) {
+                console.log(`Java version: ${config.javaVersion}`);
+            }
+            if (config.cliProvider && config.cliProvider !== "claude") {
+                console.log(`CLI provider: ${config.cliProvider}`);
+            }
+            console.log(`Image name: ${imageName}\n`);
+            await generateFiles(ralphDir, config.language, imageName, force, config.javaVersion, config.cliProvider);
+            console.log(`
 Docker files generated in .ralph/docker/
 
 Next steps:
-  1. Build the image: ralph docker --build
-  2. Run container:    ralph docker --run
+  1. Build the image: ralph docker build
+  2. Run container:    ralph docker run
 
 Or use docker compose directly:
   cd .ralph/docker && docker compose run --rm ralph
 `);
+            break;
+        }
     }
 }

package/dist/commands/help.js

@@ -7,23 +7,27 @@ USAGE:
 COMMANDS:
   init [opts]       Initialize ralph in current project
   once              Run a single automation iteration
-  run <n> [opts]    Run n automation iterations
+  run [n] [opts]    Run automation iterations (default: all tasks)
   add               Add a new PRD entry (interactive)
   list [opts]       List all PRD entries
   status            Show PRD completion status
   toggle <n>        Toggle passes status for entry n
   clean             Remove all passing entries from the PRD
   prompt [opts]     Display resolved prompt (for testing in Claude Code)
-  docker            Generate Docker sandbox environment
+  docker <sub>      Manage Docker sandbox environment
   help              Show this help message
 
   prd <subcommand>  (Alias) Manage PRD entries - same as add/list/status/toggle/clean
 
-INIT OPTIONS:
-  --tech-stack, -t           Enable technology stack selection prompt
+INIT:
+  The init command uses interactive prompts with arrow key navigation:
+  1. Select AI CLI provider (Claude Code, Aider, OpenCode, etc.)
+  2. Select project language/runtime
+  3. Select technology stack (if available for the language)
 
 RUN OPTIONS:
-  --all, -a                  Run until all tasks are complete, showing progress
+  <n>                        Run exactly n iterations (overrides default --all behavior)
+  --all, -a                  Run until all tasks are complete (default behavior)
   --loop, -l                 Run continuously, waiting for new items when complete
   --category, -c <category>  Filter PRD items by category
                              Valid: ui, feature, bugfix, setup, development, testing, docs
@@ -38,13 +42,19 @@ TOGGLE OPTIONS:
   <n> [n2] [n3]...           Toggle one or more entries by number
   --all, -a                  Toggle all PRD entries
 
+DOCKER SUBCOMMANDS:
+  docker init       Generate Dockerfile and scripts
+  docker build      Build image (always fetches latest Claude Code)
+  docker run        Run container (auto-init and build if needed)
+  docker clean      Remove Docker image and associated resources
+  docker help       Show docker help message
+
 EXAMPLES:
-  ralph init                 # Initialize ralph (language selection only)
-  ralph init --tech-stack    # Initialize with technology stack selection
+  ralph init                 # Initialize ralph (interactive CLI, language, tech selection)
   ralph once                 # Run single iteration
-  ralph run 5                # Run 5 iterations
-  ralph run --all            # Run until all tasks complete (shows progress)
-  ralph run --all -c feature # Complete all feature tasks only
+  ralph run                  # Run until all tasks complete (default)
+  ralph run 5                # Run exactly 5 iterations
+  ralph run -c feature       # Complete all feature tasks only
   ralph run --loop           # Run continuously until interrupted
   ralph add                  # Add new PRD entry
   ralph list                 # Show all entries
@@ -57,9 +67,9 @@ EXAMPLES:
   ralph toggle --all         # Toggle all entries
   ralph clean                # Remove passing entries
   ralph prompt               # Display resolved prompt
-  ralph docker               # Generate Dockerfile for sandboxed env
-  ralph docker --build       # Build Docker image
-  ralph docker --run         # Run container (auto-init/build if needed)
+  ralph docker init          # Generate Dockerfile for sandboxed env
+  ralph docker build         # Build Docker image
+  ralph docker run           # Run container (auto-init/build if needed)
 
 CONFIGURATION:
   After running 'ralph init', you'll have:
@@ -70,15 +80,26 @@ CONFIGURATION:
   └── progress.txt     Progress tracking file
 
 CLI CONFIGURATION:
-  The CLI tool can be configured in .ralph/config.json:
+  The CLI tool is configured during 'ralph init' and stored in .ralph/config.json:
   {
     "cli": {
       "command": "claude",
-      "args": ["--permission-mode", "acceptEdits"]
-    }
+      "args": ["--permission-mode", "acceptEdits"],
+      "yoloArgs": ["--dangerously-skip-permissions"]
+    },
+    "cliProvider": "claude"
   }
 
-  Default uses Claude Code. Customize 'command' and 'args' for other AI CLIs.
+  Available CLI providers (selected during 'ralph init'):
+    - claude: Claude Code (default)
+    - aider: AI pair programming
+    - codex: OpenAI Codex CLI
+    - gemini: Google Gemini CLI
+    - opencode: Open source AI coding agent
+    - amp: Sourcegraph AMP CLI
+    - custom: Configure your own CLI
+
+  Customize 'command', 'args', and 'yoloArgs' for other AI CLIs.
 `;
 export function help(_args) {
     console.log(HELP_TEXT.trim());

package/dist/commands/init.d.ts

@@ -1 +1 @@
-export declare function init(args: string[]): Promise<void>;
+export declare function init(_args: string[]): Promise<void>;

package/dist/commands/init.js

@@ -1,9 +1,8 @@
 import { existsSync, writeFileSync, mkdirSync, copyFileSync } from "fs";
 import { join, basename, dirname } from "path";
 import { fileURLToPath } from "url";
-import { getLanguages, generatePromptTemplate, DEFAULT_PRD, DEFAULT_PROGRESS } from "../templates/prompts.js";
-import { promptSelect, promptConfirm, promptInput, promptMultiSelect } from "../utils/prompt.js";
-import { DEFAULT_CLI_CONFIG } from "../utils/config.js";
+import { getLanguages, generatePromptTemplate, DEFAULT_PRD, DEFAULT_PROGRESS, getCliProviders } from "../templates/prompts.js";
+import { promptSelectWithArrows, promptConfirm, promptInput, promptMultiSelectWithArrows } from "../utils/prompt.js";
 // Get package root directory (works for both dev and installed package)
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -14,13 +13,9 @@ const PROMPT_FILE = "prompt.md";
 const PRD_FILE = "prd.json";
 const PROGRESS_FILE = "progress.txt";
 const PRD_GUIDE_FILE = "HOW-TO-WRITE-PRDs.md";
-function hasFlag(args, ...flags) {
-    return args.some(arg => flags.includes(arg));
-}
-export async function init(args) {
+export async function init(_args) {
     const cwd = process.cwd();
     const ralphDir = join(cwd, RALPH_DIR);
-    const showTechStack = hasFlag(args, "--tech-stack", "-t");
     console.log("Initializing ralph in current directory...\n");
     // Check for existing .ralph directory
     if (existsSync(ralphDir)) {
@@ -34,20 +29,51 @@ export async function init(args) {
         mkdirSync(ralphDir, { recursive: true });
         console.log(`Created ${RALPH_DIR}/`);
     }
-    // Select language
+    // Step 1: Select CLI provider (first)
+    const CLI_PROVIDERS = getCliProviders();
+    const providerKeys = Object.keys(CLI_PROVIDERS);
+    const providerNames = providerKeys.map(k => `${CLI_PROVIDERS[k].name} - ${CLI_PROVIDERS[k].description}`);
+    const selectedProviderName = await promptSelectWithArrows("Select your AI CLI provider:", providerNames);
+    const selectedProviderIndex = providerNames.indexOf(selectedProviderName);
+    const selectedCliProviderKey = providerKeys[selectedProviderIndex];
+    const selectedProvider = CLI_PROVIDERS[selectedCliProviderKey];
+    let cliConfig;
+    // Handle custom CLI provider
+    if (selectedCliProviderKey === "custom") {
+        const customCommand = await promptInput("\nEnter your CLI command: ");
+        const customArgsInput = await promptInput("Enter default arguments (space-separated): ");
+        const customArgs = customArgsInput.trim() ? customArgsInput.trim().split(/\s+/) : [];
+        const customYoloArgsInput = await promptInput("Enter yolo/auto-approve arguments (space-separated): ");
+        const customYoloArgs = customYoloArgsInput.trim() ? customYoloArgsInput.trim().split(/\s+/) : [];
+        cliConfig = {
+            command: customCommand || "claude",
+            args: customArgs,
+            yoloArgs: customYoloArgs.length > 0 ? customYoloArgs : undefined,
+        };
+    }
+    else {
+        cliConfig = {
+            command: selectedProvider.command,
+            args: selectedProvider.defaultArgs,
+            yoloArgs: selectedProvider.yoloArgs.length > 0 ? selectedProvider.yoloArgs : undefined,
+        };
+    }
+    console.log(`\nSelected CLI provider: ${CLI_PROVIDERS[selectedCliProviderKey].name}`);
+    // Step 2: Select language (second)
     const LANGUAGES = getLanguages();
     const languageKeys = Object.keys(LANGUAGES);
     const languageNames = languageKeys.map(k => `${LANGUAGES[k].name} - ${LANGUAGES[k].description}`);
-    const selectedName = await promptSelect("Select your project language/runtime:", languageNames);
+    const selectedName = await promptSelectWithArrows("Select your project language/runtime:", languageNames);
     const selectedIndex = languageNames.indexOf(selectedName);
     const selectedKey = languageKeys[selectedIndex];
     const config = LANGUAGES[selectedKey];
-    // Select technology stack if available (only when --tech-stack flag is provided)
+    console.log(`\nSelected language: ${config.name}`);
+    // Step 3: Select technology stack if available (third)
     let selectedTechnologies = [];
-    if (showTechStack && config.technologies && config.technologies.length > 0) {
+    if (config.technologies && config.technologies.length > 0) {
         const techOptions = config.technologies.map(t => `${t.name} - ${t.description}`);
         const techNames = config.technologies.map(t => t.name);
-        selectedTechnologies = await promptMultiSelect("Select your technology stack (select multiple or add custom):", techOptions);
+        selectedTechnologies = await promptMultiSelectWithArrows("Select your technology stack (optional):", techOptions);
         // Convert display names back to just technology names for predefined options
         selectedTechnologies = selectedTechnologies.map(sel => {
             const idx = techOptions.indexOf(sel);
@@ -60,7 +86,7 @@ export async function init(args) {
             console.log("\nNo technologies selected.");
         }
     }
-    // Allow custom commands
+    // Allow custom commands for "none" language
     let checkCommand = config.checkCommand;
     let testCommand = config.testCommand;
     if (selectedKey === "none") {
@@ -81,7 +107,8 @@ export async function init(args) {
         checkCommand: finalConfig.checkCommand,
         testCommand: finalConfig.testCommand,
         imageName,
-        cli: DEFAULT_CLI_CONFIG,
+        cli: cliConfig,
+        cliProvider: selectedCliProviderKey,
     };
     // Add technologies if any were selected
     if (selectedTechnologies.length > 0) {
@@ -141,6 +168,7 @@ export async function init(args) {
     console.log("\nNext steps:");
     console.log("  1. Read .ralph/HOW-TO-WRITE-PRDs.md for guidance on writing PRDs");
     console.log("  2. Edit .ralph/prd.json to add your project requirements");
-    console.log("  3. Run 'ralph once' to start the first iteration");
-    console.log("  4. Or run 'ralph run 5' for 5 automated iterations");
+    console.log("  3. Run 'ralph docker init' to generate Docker configuration");
+    console.log("  4. Run 'ralph docker build' to build the container");
+    console.log("  5. Run 'ralph docker run' to start ralph in the container");
 }

package/dist/commands/once.js

@@ -15,10 +15,12 @@ export async function once(_args) {
     const paths = getPaths();
     const cliConfig = getCliConfig(config);
     console.log("Starting single ralph iteration...\n");
-    // Build CLI arguments: config args + runtime args
+    // Build CLI arguments: config args + yolo args + prompt args
+    // Use yoloArgs from config if available, otherwise default to Claude's --dangerously-skip-permissions
+    const yoloArgs = cliConfig.yoloArgs ?? ["--dangerously-skip-permissions"];
     const cliArgs = [
         ...(cliConfig.args ?? []),
-        "--dangerously-skip-permissions",
+        ...yoloArgs,
         "-p",
         `@${paths.prd} @${paths.progress} ${prompt}`,
     ];

package/dist/commands/run.js

@@ -28,13 +28,15 @@ function createFilteredPrd(prdPath, category) {
 async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig) {
     return new Promise((resolve, reject) => {
         let output = "";
-        // Build CLI arguments: config args + runtime args
+        // Build CLI arguments: config args + yolo args + prompt args
         const cliArgs = [
             ...(cliConfig.args ?? []),
         ];
-        // Only add --dangerously-skip-permissions when running in a container
+        // Only add yolo args when running in a container
+        // Use yoloArgs from config if available, otherwise default to Claude's --dangerously-skip-permissions
         if (sandboxed) {
-            cliArgs.push("--dangerously-skip-permissions");
+            const yoloArgs = cliConfig.yoloArgs ?? ["--dangerously-skip-permissions"];
+            cliArgs.push(...yoloArgs);
         }
         // Use the filtered PRD (only incomplete items) for the prompt
         cliArgs.push("-p", `@${filteredPrdPath} @${paths.progress} ${prompt}`);
@@ -101,7 +103,7 @@ export async function run(args) {
     // Parse flags
     let category;
     let loopMode = false;
-    let allMode = false;
+    let allModeExplicit = false;
     const filteredArgs = [];
     for (let i = 0; i < args.length; i++) {
         if (args[i] === "--category" || args[i] === "-c") {
@@ -119,7 +121,7 @@ export async function run(args) {
             loopMode = true;
         }
         else if (args[i] === "--all" || args[i] === "-a") {
-            allMode = true;
+            allModeExplicit = true;
         }
         else {
             filteredArgs.push(args[i]);
@@ -131,16 +133,14 @@ export async function run(args) {
         console.error(`Valid categories: ${CATEGORIES.join(", ")}`);
         process.exit(1);
     }
+    // Determine the mode:
+    // - If --loop is specified, use loop mode
+    // - If a specific number of iterations is provided, use that
+    // - Otherwise, default to --all mode (run until all tasks complete)
+    const hasIterationArg = filteredArgs.length > 0 && !isNaN(parseInt(filteredArgs[0])) && parseInt(filteredArgs[0]) >= 1;
+    const allMode = !loopMode && (allModeExplicit || !hasIterationArg);
     // In loop mode or all mode, iterations argument is optional (defaults to unlimited)
     const iterations = (loopMode || allMode) ? (parseInt(filteredArgs[0]) || Infinity) : parseInt(filteredArgs[0]);
-    if (!loopMode && !allMode && (!iterations || iterations < 1 || isNaN(iterations))) {
-        console.error("Usage: ralph run <iterations> [--category <category>]");
-        console.error("       ralph run --loop [--category <category>]");
-        console.error("       ralph run --all [--category <category>]");
-        console.error("  <iterations> must be a positive integer");
-        console.error(`  <category> must be one of: ${CATEGORIES.join(", ")}`);
-        process.exit(1);
-    }
     requireContainer("run");
     checkFilesExist();
     const config = loadConfig();

package/dist/config/cli-providers.json

@@ -0,0 +1,93 @@
+{
+  "providers": {
+    "claude": {
+      "name": "Claude Code",
+      "description": "Anthropic's Claude Code CLI",
+      "command": "claude",
+      "defaultArgs": ["--permission-mode", "acceptEdits"],
+      "yoloArgs": ["--dangerously-skip-permissions"],
+      "docker": {
+        "install": "# Install Claude Code CLI\nRUN curl -fsSL https://claude.ai/install.sh | bash"
+      },
+      "envVars": ["ANTHROPIC_API_KEY"],
+      "credentialMount": "~/.claude:/home/node/.claude"
+    },
+    "aider": {
+      "name": "Aider",
+      "description": "AI pair programming in your terminal",
+      "command": "aider",
+      "defaultArgs": ["--yes"],
+      "yoloArgs": ["--yes-always"],
+      "docker": {
+        "install": "# Install Aider (requires Python)\nRUN apt-get update && apt-get install -y python3 python3-pip && rm -rf /var/lib/apt/lists/* \\\n    && pip3 install --break-system-packages --no-cache-dir aider-chat",
+        "note": "Check 'aider --help' for available flags"
+      },
+      "envVars": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
+      "credentialMount": null
+    },
+    "codex": {
+      "name": "OpenAI Codex CLI",
+      "description": "OpenAI's Codex CLI for code generation",
+      "command": "codex",
+      "defaultArgs": ["--approval-mode", "suggest"],
+      "yoloArgs": ["--approval-mode", "full-auto"],
+      "docker": {
+        "install": "# Install OpenAI Codex CLI\nRUN npm install -g @openai/codex",
+        "note": "Check 'codex --help' for available flags"
+      },
+      "envVars": ["OPENAI_API_KEY"],
+      "credentialMount": null
+    },
+    "gemini": {
+      "name": "Gemini CLI",
+      "description": "Google's Gemini CLI for code assistance",
+      "command": "gemini",
+      "defaultArgs": [],
+      "yoloArgs": ["-y"],
+      "docker": {
+        "install": "# Install Google Gemini CLI\nRUN npm install -g @google/gemini-cli",
+        "note": "Check 'gemini --help' for available flags"
+      },
+      "envVars": ["GOOGLE_API_KEY", "GEMINI_API_KEY"],
+      "credentialMount": "~/.gemini:/home/node/.gemini"
+    },
+    "opencode": {
+      "name": "OpenCode",
+      "description": "Open source AI coding agent for the terminal",
+      "command": "opencode",
+      "defaultArgs": [],
+      "yoloArgs": ["--yolo"],
+      "docker": {
+        "install": "# Install OpenCode\nRUN curl -fsSL https://opencode.ai/install | bash \\\n    && echo 'export PATH=\"$HOME/.opencode/bin:$PATH\"' >> /home/node/.zshrc",
+        "note": "Check 'opencode --help' for available flags"
+      },
+      "envVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GOOGLE_API_KEY"],
+      "credentialMount": null
+    },
+    "amp": {
+      "name": "AMP CLI",
+      "description": "Sourcegraph's AMP coding agent",
+      "command": "amp",
+      "defaultArgs": [],
+      "yoloArgs": ["--yolo"],
+      "docker": {
+        "install": "# Install AMP CLI\nRUN curl -fsSL https://ampcode.com/install.sh | bash \\\n    && echo 'export PATH=\"$HOME/.amp/bin:$PATH\"' >> /home/node/.zshrc",
+        "note": "Check 'amp --help' for available flags"
+      },
+      "envVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
+      "credentialMount": null
+    },
+    "custom": {
+      "name": "Custom CLI",
+      "description": "Configure your own AI CLI tool",
+      "command": "",
+      "defaultArgs": [],
+      "yoloArgs": [],
+      "docker": {
+        "install": "# Custom CLI - add your installation commands here"
+      },
+      "envVars": [],
+      "credentialMount": null
+    }
+  }
+}

package/dist/templates/prompts.d.ts

@@ -27,7 +27,24 @@ export interface LanguageConfig {
 interface LanguagesJson {
     languages: Record<string, LanguageConfigJson>;
 }
+export interface CliProviderConfig {
+    name: string;
+    description: string;
+    command: string;
+    defaultArgs: string[];
+    yoloArgs: string[];
+    docker: {
+        install: string;
+    };
+    envVars: string[];
+    credentialMount: string | null;
+}
+interface CliProvidersJson {
+    providers: Record<string, CliProviderConfig>;
+}
 export declare function getLanguagesJson(): LanguagesJson;
+export declare function getCliProvidersJson(): CliProvidersJson;
+export declare function getCliProviders(): Record<string, CliProviderConfig>;
 export declare function getLanguages(): Record<string, LanguageConfig>;
 export declare const LANGUAGES: Record<string, LanguageConfig>;
 export declare function generatePromptTemplate(): string;

package/dist/templates/prompts.js

@@ -11,6 +11,12 @@ function loadLanguagesConfig() {
     const content = readFileSync(configPath, "utf-8");
     return JSON.parse(content);
 }
+// Load CLI providers from JSON config file
+function loadCliProvidersConfig() {
+    const configPath = join(__dirname, "..", "config", "cli-providers.json");
+    const content = readFileSync(configPath, "utf-8");
+    return JSON.parse(content);
+}
 // Convert JSON config to the legacy format for compatibility
 function convertToLanguageConfig(config) {
     return {
@@ -24,12 +30,22 @@ function convertToLanguageConfig(config) {
 // Lazy-load languages to avoid issues at import time
 let _languagesCache = null;
 let _languagesJsonCache = null;
+let _cliProvidersCache = null;
 export function getLanguagesJson() {
     if (!_languagesJsonCache) {
         _languagesJsonCache = loadLanguagesConfig();
     }
     return _languagesJsonCache;
 }
+export function getCliProvidersJson() {
+    if (!_cliProvidersCache) {
+        _cliProvidersCache = loadCliProvidersConfig();
+    }
+    return _cliProvidersCache;
+}
+export function getCliProviders() {
+    return getCliProvidersJson().providers;
+}
 export function getLanguages() {
     if (!_languagesCache) {
         const json = getLanguagesJson();

package/dist/utils/config.d.ts

@@ -1,6 +1,7 @@
 export interface CliConfig {
     command: string;
     args?: string[];
+    yoloArgs?: string[];
 }
 export interface RalphConfig {
     language: string;
@@ -11,6 +12,7 @@ export interface RalphConfig {
     technologies?: string[];
     javaVersion?: number;
     cli?: CliConfig;
+    cliProvider?: string;
 }
 export declare const DEFAULT_CLI_CONFIG: CliConfig;
 export declare function getCliConfig(config: RalphConfig): CliConfig;

package/dist/utils/config.js

@@ -91,8 +91,9 @@ export function requireContainer(commandName) {
         console.error("For security, ralph executes AI agents only in isolated container environments.");
         console.error("");
         console.error("To set up a container:");
-        console.error("  ralph docker --build   # Build the container image");
-        console.error("  ralph docker --run     # Run ralph inside the container");
+        console.error("  ralph docker init    # Generate Docker configuration files");
+        console.error("  ralph docker build   # Build the container image");
+        console.error("  ralph docker run     # Run ralph inside the container");
         process.exit(1);
     }
 }

package/dist/utils/prompt.d.ts

@@ -2,7 +2,9 @@ export declare function createPrompt(): {
     question: (query: string) => Promise<string>;
     close: () => void;
 };
+export declare function promptSelectWithArrows(message: string, options: string[]): Promise<string>;
 export declare function promptInput(message: string): Promise<string>;
 export declare function promptSelect(message: string, options: string[]): Promise<string>;
 export declare function promptConfirm(message: string): Promise<boolean>;
 export declare function promptMultiSelect(message: string, options: string[]): Promise<string[]>;
+export declare function promptMultiSelectWithArrows(message: string, options: string[]): Promise<string[]>;

package/dist/utils/prompt.js

@@ -13,6 +13,66 @@ export function createPrompt() {
         close: () => rl.close(),
     };
 }
+export async function promptSelectWithArrows(message, options) {
+    return new Promise((resolve) => {
+        let selectedIndex = 0;
+        // Hide cursor and enable raw mode
+        process.stdout.write("\x1B[?25l"); // Hide cursor
+        const render = () => {
+            // Move cursor up to clear previous render (except first time)
+            if (selectedIndex >= 0) {
+                process.stdout.write(`\x1B[${options.length}A`); // Move up
+            }
+            options.forEach((opt, i) => {
+                const prefix = i === selectedIndex ? "\x1B[36m❯\x1B[0m" : " ";
+                const text = i === selectedIndex ? `\x1B[36m${opt}\x1B[0m` : opt;
+                process.stdout.write(`\x1B[2K${prefix} ${text}\n`); // Clear line and write
+            });
+        };
+        const initialRender = () => {
+            console.log(`\n${message}\n`);
+            options.forEach((opt, i) => {
+                const prefix = i === selectedIndex ? "\x1B[36m❯\x1B[0m" : " ";
+                const text = i === selectedIndex ? `\x1B[36m${opt}\x1B[0m` : opt;
+                console.log(`${prefix} ${text}`);
+            });
+        };
+        initialRender();
+        // Set up raw mode for key input
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode(true);
+        }
+        process.stdin.resume();
+        process.stdin.setEncoding("utf8");
+        const onKeypress = (key) => {
+            // Handle arrow keys (escape sequences)
+            if (key === "\x1B[A" || key === "k") { // Up arrow or k
+                selectedIndex = (selectedIndex - 1 + options.length) % options.length;
+                render();
+            }
+            else if (key === "\x1B[B" || key === "j") { // Down arrow or j
+                selectedIndex = (selectedIndex + 1) % options.length;
+                render();
+            }
+            else if (key === "\r" || key === "\n" || key === " ") { // Enter or space
+                cleanup();
+                resolve(options[selectedIndex]);
+            }
+            else if (key === "\x03") { // Ctrl+C
+                cleanup();
+                process.exit(0);
+            }
+        };
+        const cleanup = () => {
+            process.stdin.removeListener("data", onKeypress);
+            if (process.stdin.isTTY) {
+                process.stdin.setRawMode(false);
+            }
+            process.stdout.write("\x1B[?25h"); // Show cursor
+        };
+        process.stdin.on("data", onKeypress);
+    });
+}
 export async function promptInput(message) {
     const prompt = createPrompt();
     const answer = await prompt.question(message);
@@ -99,3 +159,79 @@ export async function promptMultiSelect(message, options) {
         }
     }
 }
+export async function promptMultiSelectWithArrows(message, options) {
+    return new Promise((resolve) => {
+        let selectedIndex = 0;
+        const selected = new Set();
+        // Add a "Done" option at the end
+        const allOptions = [...options, "[Done - press Enter]"];
+        // Hide cursor
+        process.stdout.write("\x1B[?25l");
+        const render = () => {
+            process.stdout.write(`\x1B[${allOptions.length}A`); // Move up
+            allOptions.forEach((opt, i) => {
+                const isLastOption = i === allOptions.length - 1;
+                const cursor = i === selectedIndex ? "\x1B[36m❯\x1B[0m" : " ";
+                const checkbox = isLastOption ? "" : (selected.has(i) ? "\x1B[32m[x]\x1B[0m" : "[ ]");
+                const text = i === selectedIndex ? `\x1B[36m${opt}\x1B[0m` : opt;
+                process.stdout.write(`\x1B[2K${cursor} ${checkbox} ${text}\n`);
+            });
+        };
+        const initialRender = () => {
+            console.log(`\n${message}`);
+            console.log("(Use arrow keys to navigate, Space to select, Enter to confirm)\n");
+            allOptions.forEach((opt, i) => {
+                const isLastOption = i === allOptions.length - 1;
+                const cursor = i === selectedIndex ? "\x1B[36m❯\x1B[0m" : " ";
+                const checkbox = isLastOption ? "" : (selected.has(i) ? "\x1B[32m[x]\x1B[0m" : "[ ]");
+                const text = i === selectedIndex ? `\x1B[36m${opt}\x1B[0m` : opt;
+                console.log(`${cursor} ${checkbox} ${text}`);
+            });
+        };
+        initialRender();
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode(true);
+        }
+        process.stdin.resume();
+        process.stdin.setEncoding("utf8");
+        const onKeypress = (key) => {
+            if (key === "\x1B[A" || key === "k") { // Up
+                selectedIndex = (selectedIndex - 1 + allOptions.length) % allOptions.length;
+                render();
+            }
+            else if (key === "\x1B[B" || key === "j") { // Down
+                selectedIndex = (selectedIndex + 1) % allOptions.length;
+                render();
+            }
+            else if (key === " ") { // Space - toggle selection
+                const isLastOption = selectedIndex === allOptions.length - 1;
+                if (!isLastOption) {
+                    if (selected.has(selectedIndex)) {
+                        selected.delete(selectedIndex);
+                    }
+                    else {
+                        selected.add(selectedIndex);
+                    }
+                    render();
+                }
+            }
+            else if (key === "\r" || key === "\n") { // Enter - confirm
+                cleanup();
+                const result = options.filter((_, i) => selected.has(i));
+                resolve(result);
+            }
+            else if (key === "\x03") { // Ctrl+C
+                cleanup();
+                process.exit(0);
+            }
+        };
+        const cleanup = () => {
+            process.stdin.removeListener("data", onKeypress);
+            if (process.stdin.isTTY) {
+                process.stdin.setRawMode(false);
+            }
+            process.stdout.write("\x1B[?25h"); // Show cursor
+        };
+        process.stdin.on("data", onKeypress);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-cli-sandboxed",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "AI-driven development automation CLI for Claude Code",
   "type": "module",
   "bin": {