owo-cli 1.2.0 → 1.3.0

package/README.md

@@ -73,6 +73,22 @@ chmod +x dist/owo-cli
 mv dist/owo-cli /usr/local/bin/owo-cli
 ```
 
+### Quick Start
+
+The fastest way to get started is with the interactive setup wizard:
+
+```bash
+owo setup
+```
+
+This walks you through picking a provider, entering your API key, choosing a model, and enabling optional features. It writes the config file for you.
+
+Alternatively, you can skip setup entirely with inline flags:
+
+```bash
+owo -p openai -k sk-your-key -m gpt-4.1 list all files larger than 100MB
+```
+
 ### Configuration
 
 `owo` is configured through a single `config.json` file. The first time you run `owo`, it will automatically create a default configuration file to get you started.
@@ -369,6 +385,99 @@ owo generate a new ssh key called owo-key and add it to the ssh agent
 
 You'll see the generated command in your shell's input line. Press **Enter** to run it, or edit it first. Executed commands will show up in your shell's history just like any other command.
 
+### CLI Flags
+
+All flags can override config values for a single invocation without editing `config.json`.
+
+#### Provider Overrides
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--provider <type>` | `-p` | Override provider (`openai`, `claude`, `gemini`, `github`, `claudecode`, `custom`) |
+| `--model <name>` | `-m` | Override model |
+| `--api-key <key>` | `-k` | Override API key (highest precedence: flag > config > env var) |
+| `--base-url <url>` | | Override base URL for custom/OpenAI-compatible providers |
+
+```bash
+# Use Claude for a single query without changing config
+owo -p claude -m claude-sonnet-4-20250514 find large log files
+
+# Use a local Ollama model
+owo -p custom --base-url http://localhost:11434/v1 -m llama3 show disk usage
+```
+
+#### Behavior
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--copy` | `-c` | Copy generated command to clipboard |
+| `--no-copy` | | Don't copy to clipboard |
+| `--history` | | Include shell history context |
+| `--no-history` | | Exclude shell history context |
+| `--history-count <n>` | | Number of history commands to include (implies `--history`) |
+
+```bash
+# Copy command even if config has clipboard disabled
+owo --copy find all zombie processes
+
+# Use history context for a single query
+owo --history redo that but with sudo
+```
+
+#### Output
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--exec` | `-x` | Execute the generated command after `Execute? [y/N]` confirmation |
+| `--explain` | `-e` | Show a brief explanation of the command on stderr |
+| `--raw` | `-r` | Suppress all non-command output (clean for piping) |
+
+```bash
+# Execute with confirmation
+owo -x delete all .tmp files older than 7 days
+
+# Get an explanation alongside the command
+owo -e find all files larger than 100mb
+
+# Pipe-safe output
+result=$(owo -r show my public IP)
+```
+
+#### Debugging
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--dry-run` | `-n` | Print the prompt that would be sent without making an API call |
+| `--verbose` | `-V` | Print diagnostics (provider, model, latency) to stderr |
+| `--retry <n>` | | Override retry count (default: 2) |
+
+```bash
+# See exactly what would be sent to the API
+owo --dry-run find large files
+
+# Debug with full diagnostics
+owo -V convert all heic files to jpg
+
+# Fail fast with no retries
+owo --retry 0 list disk usage
+```
+
+#### Stdin / Pipe Support
+
+`owo` auto-detects piped input and reads the description from stdin:
+
+```bash
+echo "find files larger than 100mb" | owo
+```
+
+#### The `--` Separator
+
+Use `--` to separate flags from the description when your description looks like a flag:
+
+```bash
+owo -- -rf delete these files
+```
+
 ## License
 
 [MIT](LICENSE)

package/dist/owo.js

@@ -24278,6 +24278,7 @@ var esm_default = createClient;
 
 // index.ts
 import { execSync } from "child_process";
+import readline from "readline";
 import os5 from "os";
 import fs3 from "fs";
 import path4 from "path";
@@ -24452,6 +24453,193 @@ function buildContextHistory(contextConfig) {
 }
 
 // index.ts
+var PROVIDER_ALIASES = {
+  openai: "OpenAI",
+  custom: "Custom",
+  claude: "Claude",
+  gemini: "Gemini",
+  github: "GitHub",
+  claudecode: "ClaudeCode"
+};
+function parseArgs(argv) {
+  const result = {
+    help: false,
+    version: false,
+    dryRun: false,
+    exec: false,
+    explain: false,
+    raw: false,
+    verbose: false,
+    copy: undefined,
+    history: undefined,
+    provider: undefined,
+    model: undefined,
+    apiKey: undefined,
+    baseUrl: undefined,
+    historyCount: undefined,
+    retry: undefined,
+    subcommand: undefined,
+    subcommandArgs: [],
+    description: ""
+  };
+  if (argv[0] === "config") {
+    result.subcommand = "config";
+    result.subcommandArgs = argv.slice(1);
+    return result;
+  }
+  if (argv[0] === "setup") {
+    result.subcommand = "setup";
+    result.subcommandArgs = argv.slice(1);
+    return result;
+  }
+  const descriptionParts = [];
+  let i2 = 0;
+  while (i2 < argv.length) {
+    const arg = argv[i2];
+    if (arg === "--") {
+      descriptionParts.push(...argv.slice(i2 + 1));
+      break;
+    }
+    switch (arg) {
+      case "--help":
+        result.help = true;
+        i2++;
+        continue;
+      case "--version":
+        result.version = true;
+        i2++;
+        continue;
+      case "--dry-run":
+        result.dryRun = true;
+        i2++;
+        continue;
+      case "--exec":
+        result.exec = true;
+        i2++;
+        continue;
+      case "--explain":
+        result.explain = true;
+        i2++;
+        continue;
+      case "--raw":
+        result.raw = true;
+        i2++;
+        continue;
+      case "--verbose":
+        result.verbose = true;
+        i2++;
+        continue;
+      case "--copy":
+        result.copy = true;
+        i2++;
+        continue;
+      case "--no-copy":
+        result.copy = false;
+        i2++;
+        continue;
+      case "--history":
+        result.history = true;
+        i2++;
+        continue;
+      case "--no-history":
+        result.history = false;
+        i2++;
+        continue;
+      case "--provider":
+        result.provider = argv[++i2];
+        i2++;
+        continue;
+      case "--model":
+        result.model = argv[++i2];
+        i2++;
+        continue;
+      case "--api-key":
+        result.apiKey = argv[++i2];
+        i2++;
+        continue;
+      case "--base-url":
+        result.baseUrl = argv[++i2];
+        i2++;
+        continue;
+      case "--history-count": {
+        const val = argv[++i2];
+        result.historyCount = val ? parseInt(val, 10) : undefined;
+        result.history = true;
+        i2++;
+        continue;
+      }
+      case "--retry": {
+        const val = argv[++i2];
+        result.retry = val ? parseInt(val, 10) : undefined;
+        i2++;
+        continue;
+      }
+    }
+    if (arg.startsWith("-") && !arg.startsWith("--") && arg.length >= 2) {
+      let consumed = false;
+      switch (arg) {
+        case "-p":
+          result.provider = argv[++i2];
+          i2++;
+          consumed = true;
+          break;
+        case "-m":
+          result.model = argv[++i2];
+          i2++;
+          consumed = true;
+          break;
+        case "-k":
+          result.apiKey = argv[++i2];
+          i2++;
+          consumed = true;
+          break;
+      }
+      if (consumed)
+        continue;
+      const chars = arg.slice(1);
+      let allValid = true;
+      for (const ch of chars) {
+        switch (ch) {
+          case "h":
+            result.help = true;
+            break;
+          case "v":
+            result.version = true;
+            break;
+          case "n":
+            result.dryRun = true;
+            break;
+          case "x":
+            result.exec = true;
+            break;
+          case "e":
+            result.explain = true;
+            break;
+          case "r":
+            result.raw = true;
+            break;
+          case "V":
+            result.verbose = true;
+            break;
+          case "c":
+            result.copy = true;
+            break;
+          default:
+            allValid = false;
+            break;
+        }
+      }
+      if (allValid) {
+        i2++;
+        continue;
+      }
+    }
+    descriptionParts.push(arg);
+    i2++;
+  }
+  result.description = descriptionParts.join(" ").trim();
+  return result;
+}
 var CLAUDE_MAX_TOKENS = 1024;
 var DEFAULT_CONFIG = {
   type: "OpenAI",
@@ -24579,24 +24767,54 @@ async function copyToClipboard(text) {
     throw new Error(`Clipboard operation failed: ${error2}`);
   }
 }
-var VERSION3 = "1.1.3";
+var VERSION3 = "1.3.0";
 function printHelp() {
   console.log(`owo v${VERSION3} - Natural language to shell commands using AI
 
 Usage:
   owo <command description>    Generate a shell command from a description
+  owo setup                    Interactive first-run configuration wizard
   owo config path              Print config file location
   owo config show              Display current config (API keys masked)
   owo config set <key> <value> Set a config value
 
-Options:
-  --help, -h       Show this help message
-  --version, -v    Show version number
+Provider Overrides:
+  -p, --provider <type>      Override provider (openai, claude, gemini, github, claudecode, custom)
+  -m, --model <name>         Override model
+  -k, --api-key <key>        Override API key
+      --base-url <url>       Override base URL (custom providers)
+
+Behavior:
+  -c, --copy                 Copy command to clipboard
+      --no-copy              Don't copy to clipboard
+      --history              Include shell history context
+      --no-history           Exclude shell history context
+      --history-count <n>    History commands to include (implies --history)
+
+Output:
+  -x, --exec                 Execute generated command (with confirmation)
+  -e, --explain              Show command explanation on stderr
+  -r, --raw                  Suppress all non-command output
+
+Debugging:
+  -n, --dry-run              Show prompt without making API call
+  -V, --verbose              Show diagnostics (provider, latency, tokens)
+      --retry <n>            Override retry count (default: 2)
+
+General:
+  -h, --help                 Show this help message
+  -v, --version              Show version number
+
+Use -- to separate flags from description:
+  owo -- -rf delete these files
 
 Examples:
   owo list all files larger than 100MB
-  owo find and replace foo with bar in all js files
-  owo compress all png files in current directory
+  owo -p claude -m claude-sonnet-4-20250514 find large log files
+  owo --dry-run find files modified today
+  owo --copy find all zombie processes
+  owo -x delete all .tmp files older than 7 days
+  echo "find large files" | owo
 
 Providers: OpenAI, Custom, Claude, Gemini, GitHub, ClaudeCode
 
@@ -24655,20 +24873,148 @@ function handleConfigSubcommand(args) {
   console.error("Usage: owo config <path|show|set>");
   process.exit(1);
 }
+function createReadlineInterface() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stderr
+  });
+}
+function prompt(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+var DEFAULT_MODELS = {
+  OpenAI: "gpt-4.1",
+  Custom: "llama3",
+  Claude: "claude-sonnet-4-20250514",
+  Gemini: "gemini-pro",
+  GitHub: "openai/gpt-4.1-nano",
+  ClaudeCode: "sonnet"
+};
+async function handleSetupSubcommand() {
+  const rl = createReadlineInterface();
+  console.error(`
+owo setup - Interactive Configuration Wizard
+`);
+  const providers = ["OpenAI", "Claude", "Gemini", "GitHub", "ClaudeCode", "Custom"];
+  console.error("Available providers:");
+  providers.forEach((p2, i2) => console.error(`  ${i2 + 1}. ${p2}`));
+  let providerIdx;
+  while (true) {
+    const answer = await prompt(rl, `
+Select provider [1-${providers.length}]: `);
+    providerIdx = parseInt(answer, 10) - 1;
+    if (providerIdx >= 0 && providerIdx < providers.length)
+      break;
+    console.error("Invalid selection. Please enter a number.");
+  }
+  const providerType = providers[providerIdx];
+  let apiKey = "";
+  if (providerType !== "ClaudeCode") {
+    const envVar = {
+      OpenAI: "OPENAI_API_KEY",
+      Custom: "OPENAI_API_KEY",
+      Claude: "ANTHROPIC_API_KEY",
+      Gemini: "GOOGLE_API_KEY",
+      GitHub: "GITHUB_TOKEN"
+    }[providerType] || "OPENAI_API_KEY";
+    apiKey = await prompt(rl, `
+API key (or press Enter to use $${envVar}): `);
+  }
+  const defaultModel = DEFAULT_MODELS[providerType];
+  const modelAnswer = await prompt(rl, `
+Model [${defaultModel}]: `);
+  const model = modelAnswer.trim() || defaultModel;
+  let baseURL;
+  if (providerType === "Custom") {
+    const urlAnswer = await prompt(rl, `
+Base URL (e.g., http://localhost:11434/v1): `);
+    baseURL = urlAnswer.trim() || undefined;
+  }
+  const clipAnswer = await prompt(rl, `
+Auto-copy commands to clipboard? [y/N]: `);
+  const clipboard = clipAnswer.trim().toLowerCase() === "y";
+  const histAnswer = await prompt(rl, "Include shell history context? [y/N]: ");
+  const historyEnabled = histAnswer.trim().toLowerCase() === "y";
+  rl.close();
+  const newConfig = {
+    type: providerType,
+    apiKey,
+    model,
+    clipboard,
+    context: {
+      enabled: historyEnabled,
+      maxHistoryCommands: 10
+    }
+  };
+  if (baseURL)
+    newConfig.baseURL = baseURL;
+  const paths = envPaths("owo", { suffix: "" });
+  const configPath = path4.join(paths.config, "config.json");
+  fs3.mkdirSync(paths.config, { recursive: true });
+  fs3.writeFileSync(configPath, JSON.stringify(newConfig, null, 2));
+  console.error(`
+Configuration saved to: ${configPath}`);
+  console.error(`You're all set! Try: owo list all files larger than 100MB
+`);
+  process.exit(0);
+}
 var rawArgs = process.argv.slice(2);
-if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+var parsed = parseArgs(rawArgs);
+if (parsed.help) {
   printHelp();
   process.exit(0);
 }
-if (rawArgs.includes("--version") || rawArgs.includes("-v")) {
+if (parsed.version) {
   console.log(VERSION3);
   process.exit(0);
 }
-if (rawArgs[0] === "config") {
-  handleConfigSubcommand(rawArgs.slice(1));
+if (parsed.subcommand === "config") {
+  handleConfigSubcommand(parsed.subcommandArgs);
+}
+if (parsed.subcommand === "setup") {
+  await handleSetupSubcommand();
+}
+var commandDescription = parsed.description;
+if (!commandDescription && !process.stdin.isTTY) {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  commandDescription = Buffer.concat(chunks).toString("utf-8").trim();
 }
 var config = getConfig();
-var commandDescription = rawArgs.join(" ").trim();
+if (parsed.provider) {
+  const normalized = parsed.provider.toLowerCase();
+  const mapped = PROVIDER_ALIASES[normalized];
+  if (!mapped) {
+    console.error(`Error: Unknown provider "${parsed.provider}".`);
+    console.error(`Valid providers: ${Object.keys(PROVIDER_ALIASES).join(", ")}`);
+    process.exit(1);
+  }
+  config.type = mapped;
+}
+if (parsed.model)
+  config.model = parsed.model;
+if (parsed.apiKey)
+  config.apiKey = parsed.apiKey;
+if (parsed.baseUrl)
+  config.baseURL = parsed.baseUrl;
+if (parsed.copy !== undefined)
+  config.clipboard = parsed.copy;
+if (parsed.history !== undefined) {
+  if (!config.context)
+    config.context = { ...DEFAULT_CONTEXT_CONFIG };
+  config.context.enabled = parsed.history;
+}
+if (parsed.historyCount !== undefined) {
+  if (!config.context)
+    config.context = { ...DEFAULT_CONTEXT_CONFIG };
+  config.context.maxHistoryCommands = parsed.historyCount;
+}
+if (!parsed.apiKey && !config.apiKey) {
+  config.apiKey = getEnvApiKey(config.type);
+}
+validateConfig(config);
 if (!commandDescription) {
   console.error("Error: No command description provided.");
   console.error("Usage: owo <command description>");
@@ -24702,7 +25048,7 @@ function sanitizeResponse(content) {
   }
   return lines.at(-1)?.trim() || "";
 }
-async function generateCommand(config2, commandDescription2) {
+function buildPrompts(config2, commandDescription2, explain) {
   const envContext = `
 Operating System: ${os5.type()} ${os5.release()} (${os5.platform()} - ${os5.arch()})
 Node.js Version: ${process.version}
@@ -24728,7 +25074,26 @@ Free Memory: ${(os5.freemem() / 1024 / 1024).toFixed(0)} MB
   }
   const contextConfig = config2.context || DEFAULT_CONTEXT_CONFIG;
   const historyContext = buildContextHistory(contextConfig);
-  const systemPrompt = `
+  let systemPrompt;
+  if (explain) {
+    systemPrompt = `
+You live in a developer's CLI, helping them convert natural language into CLI commands.
+Based on the description of the command given, generate the command and a brief explanation.
+Make sure to escape characters when appropriate. The result of \`${lsCommand}\` is given with the command.
+Output your response in exactly this format:
+COMMAND: <the command>
+EXPLANATION: <brief explanation of what the command does>
+Do not wrap the command in quotes.
+
+--- ENVIRONMENT CONTEXT ---
+${envContext}
+--- END ENVIRONMENT CONTEXT ---
+
+Result of \`${lsCommand}\` in working directory:
+${lsResult}
+${historyContext}`;
+  } else {
+    systemPrompt = `
 You live in a developer's CLI, helping them convert natural language into CLI commands.
 Based on the description of the command given, generate the command. Output only the command and nothing else.
 Make sure to escape characters when appropriate. The result of \`${lsCommand}\` is given with the command.
@@ -24742,6 +25107,11 @@ ${envContext}
 Result of \`${lsCommand}\` in working directory:
 ${lsResult}
 ${historyContext}`;
+  }
+  return { systemPrompt, userMessage: `Command description: ${commandDescription2}` };
+}
+async function generateCommand(config2, commandDescription2, explain) {
+  const { systemPrompt, userMessage } = buildPrompts(config2, commandDescription2, explain);
   if (config2.type !== "ClaudeCode" && !config2.apiKey) {
     const envVar = {
       OpenAI: "OPENAI_API_KEY",
@@ -24765,14 +25135,11 @@ ${historyContext}`;
         model: config2.model,
         messages: [
           { role: "system", content: systemPrompt },
-          {
-            role: "user",
-            content: `Command description: ${commandDescription2}`
-          }
+          { role: "user", content: userMessage }
         ]
       });
       const raw = response?.choices?.[0]?.message?.content ?? "";
-      return sanitizeResponse(String(raw));
+      return explain ? String(raw) : sanitizeResponse(String(raw));
     }
     case "Claude": {
       const anthropic = new sdk_default({ apiKey: config2.apiKey });
@@ -24781,26 +25148,23 @@ ${historyContext}`;
         system: systemPrompt,
         max_tokens: CLAUDE_MAX_TOKENS,
         messages: [
-          {
-            role: "user",
-            content: `Command description: ${commandDescription2}`
-          }
+          { role: "user", content: userMessage }
         ]
       });
       const firstBlock = response.content?.[0];
       const raw = (firstBlock && firstBlock.type === "text" ? firstBlock.text : "") ?? "";
-      return sanitizeResponse(String(raw));
+      return explain ? String(raw) : sanitizeResponse(String(raw));
     }
     case "Gemini": {
       const genAI = new GoogleGenerativeAI(config2.apiKey);
       const model = genAI.getGenerativeModel({ model: config2.model });
-      const prompt = `${systemPrompt}
+      const fullPrompt = `${systemPrompt}
 
-Command description: ${commandDescription2}`;
-      const result = await model.generateContent(prompt);
+${userMessage}`;
+      const result = await model.generateContent(fullPrompt);
       const response = await result.response;
       const raw = await response.text();
-      return sanitizeResponse(String(raw));
+      return explain ? String(raw) : sanitizeResponse(String(raw));
     }
     case "GitHub": {
       const endpoint = config2.baseURL ? config2.baseURL : "https://models.github.ai/inference";
@@ -24810,7 +25174,7 @@ Command description: ${commandDescription2}`;
         body: {
           messages: [
             { role: "system", content: systemPrompt },
-            { role: "user", content: `Command description: ${commandDescription2}` }
+            { role: "user", content: userMessage }
           ],
           model
         }
@@ -24819,7 +25183,7 @@ Command description: ${commandDescription2}`;
         throw response.body.error;
       }
       const content = response.body.choices?.[0]?.message?.content;
-      return sanitizeResponse(String(content ?? ""));
+      return explain ? String(content ?? "") : sanitizeResponse(String(content ?? ""));
     }
     case "ClaudeCode": {
       try {
@@ -24841,29 +25205,84 @@ Command description: ${commandDescription2}`;
       if (config2.model) {
         args.push("--model", config2.model);
       }
-      args.push(JSON.stringify(`Command description: ${commandDescription2}`));
+      args.push(JSON.stringify(userMessage));
       const result = execSync(args.join(" "), {
         encoding: "utf-8",
         timeout: 30000
       });
-      return sanitizeResponse(result);
+      return explain ? result : sanitizeResponse(result);
     }
     default:
       console.error(`Error: Unknown provider type "${config2.type}" in config.json.`);
       process.exit(1);
   }
 }
+if (parsed.dryRun) {
+  const { systemPrompt, userMessage } = buildPrompts(config, commandDescription, parsed.explain);
+  console.log("--- SYSTEM PROMPT ---");
+  console.log(systemPrompt);
+  console.log("--- USER MESSAGE ---");
+  console.log(userMessage);
+  console.log("---");
+  console.log(`Provider: ${config.type}`);
+  console.log(`Model: ${config.model}`);
+  process.exit(0);
+}
+var retryCount = parsed.retry !== undefined ? parsed.retry : 2;
 try {
-  const command = await withRetry(() => generateCommand(config, commandDescription));
+  if (parsed.verbose) {
+    console.error(`Provider: ${config.type}`);
+    console.error(`Model: ${config.model}`);
+    if (config.baseURL)
+      console.error(`Base URL: ${config.baseURL}`);
+  }
+  const startTime = Date.now();
+  const rawResult = await withRetry(() => generateCommand(config, commandDescription, parsed.explain), retryCount);
+  const elapsed = Date.now() - startTime;
+  let command;
+  let explanation;
+  if (parsed.explain) {
+    const commandMatch = rawResult.match(/COMMAND:\s*(.+)/);
+    const explainMatch = rawResult.match(/EXPLANATION:\s*([\s\S]+)/);
+    command = commandMatch ? sanitizeResponse(commandMatch[1]) : sanitizeResponse(rawResult);
+    explanation = explainMatch ? explainMatch[1].trim() : undefined;
+  } else {
+    command = rawResult;
+  }
+  if (parsed.verbose) {
+    console.error(`Latency: ${elapsed}ms`);
+  }
   if (config.clipboard) {
     try {
       await copyToClipboard(command);
+      if (!parsed.raw)
+        console.error("Copied to clipboard.");
     } catch (clipboardError) {
-      console.error("Warning: Failed to copy to clipboard:", clipboardError.message);
+      if (!parsed.raw)
+        console.error("Warning: Failed to copy to clipboard:", clipboardError.message);
     }
   }
+  if (explanation && !parsed.raw) {
+    console.error(`
+Explanation: ${explanation}`);
+  }
   console.log(command);
+  if (parsed.exec) {
+    const rl = createReadlineInterface();
+    const answer = await prompt(rl, `
+Execute? [y/N]: `);
+    rl.close();
+    if (answer.trim().toLowerCase() === "y") {
+      try {
+        execSync(command, { stdio: "inherit" });
+      } catch (execError) {
+        process.exit(execError.status ?? 1);
+      }
+    }
+  }
 } catch (error2) {
-  console.error(`Error generating command (provider: ${config.type}, model: ${config.model}):`, error2.message);
+  if (!parsed.raw) {
+    console.error(`Error generating command (provider: ${config.type}, model: ${config.model}):`, error2.message);
+  }
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "owo-cli",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Natural language to shell commands using AI",
   "type": "module",
   "bin": {