@prompts-gpt/client 0.2.3 → 0.2.4

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
-import { DEFAULT_PROMPTS_GPT_API_URL, DEFAULT_PROMPTS_GPT_OUT_DIR, DEFAULT_RUN_CONFIG_PATH, PROMPTS_GPT_CREDENTIALS_FILE, PromptsGptApiError, PromptsGptClient, doctor, initRunConfig, loadRunConfig, normalizeOrchestrationAgent, ORCHESTRATION_AGENT_PROFILES, runBatch, runPrompt, sweepPrompt, validateRunConfig, discoverWorkspaceAssets, SUPPORTED_AGENT_TARGETS, detectProviders, loadLocalCredentials, saveLocalCredentials, syncPrompts, writeAgentFiles, writePromptManifest, writePromptMarkdownFiles, } from "./index.js";
+import { hasTokenUsage, DEFAULT_PROMPTS_GPT_API_URL, DEFAULT_PROMPTS_GPT_OUT_DIR, DEFAULT_RUN_CONFIG_PATH, PROMPTS_GPT_CREDENTIALS_FILE, PromptsGptApiError, PromptsGptClient, doctor, initRunConfig, loadRunConfig, normalizeOrchestrationAgent, ORCHESTRATION_AGENT_PROFILES, runBatch, runPrompt, resolveRunProvider, warnModelProviderMismatch, sweepPrompt, validateRunConfig, discoverWorkspaceAssets, SUPPORTED_AGENT_TARGETS, detectProviders, loadLocalCredentials, saveLocalCredentials, syncPrompts, writeAgentFiles, writePromptManifest, writePromptMarkdownFiles, } from "./index.js";
 const CLI_EXIT_CODES = {
     success: 0,
     general: 1,
@@ -12,7 +12,7 @@ const CLI_EXIT_CODES = {
     usage: 64,
 };
 const VALID_TOOLS = ["Codex", "Claude Code", "Cursor", "GitHub Copilot", "ChatGPT", "Gemini", "Perplexity", "Grok", "DeepSeek", "Claude"];
-const COMMANDS = ["setup", "init", "project", "pull", "generate", "sync", "run", "run-batch", "sweep", "list", "status", "validate", "providers", "doctor", "load-config", "version", "help"];
+const COMMANDS = ["setup", "init", "project", "pull", "generate", "sync", "run", "run-batch", "sweep", "list", "status", "validate", "providers", "doctor", "load-config", "quickstart", "version", "help"];
 const MAX_STDIN_TOKEN_LENGTH = 4_096;
 class CliError extends Error {
     exitCode;
@@ -27,12 +27,15 @@ class CliError extends Error {
 async function main() {
     const argv = process.argv.slice(2);
     if (argv.length === 0) {
-        printHelp();
-        console.log("Quick start:");
-        console.log("  prompts-gpt status      — check workspace readiness");
-        console.log("  prompts-gpt list        — see available prompts, sweeps, agents");
-        console.log("  prompts-gpt help <cmd>  — detailed help for a command");
-        console.log("");
+        console.log(`Prompts-GPT CLI — sync and run AI prompt packs locally
+
+Get started:
+  prompts-gpt quickstart              — setup credentials, config, and first run
+  prompts-gpt list                    — see available prompts and sweeps
+  prompts-gpt sweep                   — run a multi-iteration sweep (auto-detects local sweeps)
+
+Run \`prompts-gpt help\` for the full command list.
+`);
         return;
     }
     const first = argv[0];
@@ -83,7 +86,11 @@ async function runCommand(command, flags) {
         }
         console.log(`Workspace: ${cwd}`);
         for (const provider of providers) {
-            console.log(`${provider.provider}: ${provider.available ? "available" : "missing"} | bin=${provider.bin} | model=${provider.modelDefault}${provider.version ? ` | version=${provider.version}` : ""}`);
+            const status = provider.available ? "✓ available" : "✗ missing";
+            console.log(`${provider.provider}: ${status} | bin=${provider.bin} | model=${provider.modelDefault}${provider.version ? ` | version=${provider.version}` : ""}`);
+            if (!provider.available) {
+                console.log(`  install: ${provider.installHint}`);
+            }
         }
         return;
     }
@@ -124,27 +131,23 @@ async function runCommand(command, flags) {
             return;
         }
         console.log(`Created run config: ${result.configPath}`);
-        console.log(`Default agent: ${result.config.defaultAgent ?? "router"}`);
-        console.log(`Provider order: ${(result.config.providerOrder ?? []).join(", ")}`);
+        console.log(`Config: ${result.configPath}`);
+        console.log(`Agent: ${result.config.defaultAgent ?? "router"} | Providers: ${(result.config.providerOrder ?? []).join(", ")}`);
         if (result.sourceSummary.defaultPromptFile) {
             console.log(`Default prompt file: ${result.sourceSummary.defaultPromptFile}`);
+            console.log(`Default prompt: ${result.sourceSummary.defaultPromptFile}`);
         }
-        if (result.sourceSummary.manifestPath) {
-            console.log(`Batch default manifest: ${result.sourceSummary.manifestPath}`);
-        }
-        else if (result.sourceSummary.promptFiles.length > 0) {
-            console.log(`Batch default prompt files: ${result.sourceSummary.promptFiles.length}`);
-        }
-        else {
-            console.log("Batch default prompt sources: none detected");
-        }
-        console.log("Detected providers:");
-        for (const provider of result.providerSummary) {
-            console.log(`- ${provider.provider}: ${provider.available ? "available" : "missing"} | bin=${provider.bin}`);
+        const availableCount = result.providerSummary.filter((p) => p.available).length;
+        console.log(`Providers: ${availableCount}/${result.providerSummary.length} available`);
+        if (availableCount === 0) {
+            console.log("⚠ No provider CLIs detected. Install codex, cursor agent, claude, or copilot.");
         }
+        const setupAssets = await discoverWorkspaceAssets(cwd);
         console.log("Next steps:");
         console.log(`  prompts-gpt run${result.sourceSummary.defaultPromptFile ? "" : " --prompt-file <path>"}`);
-        console.log("  prompts-gpt run-batch");
+        if (setupAssets.sweeps.length > 0) {
+            console.log(`  prompts-gpt sweep       — run a multi-iteration sweep (${setupAssets.sweeps.length} found)`);
+        }
         console.log("  prompts-gpt list        — see all runnable assets");
         console.log("  prompts-gpt status      — check workspace readiness");
         console.log("  prompts-gpt validate    — validate your config");
@@ -180,10 +183,15 @@ async function runCommand(command, flags) {
         }
         console.log(`Workspace: ${cwd}`);
         console.log("");
+        const providers = await detectProviders(cwd);
+        const availableProviderNames = providers.filter((p) => p.available).map((p) => p.provider);
         if (assets.prompts.length > 0) {
             console.log(`Prompt packs (${assets.prompts.length}):`);
             for (const p of assets.prompts) {
-                console.log(`  ${p.slug} — ${p.title} [${p.source}]`);
+                const providerHint = availableProviderNames.length > 0
+                    ? ` (run with: ${availableProviderNames[0]})`
+                    : "";
+                console.log(`  ${p.slug} — ${p.title} [${p.source}]${providerHint}`);
                 console.log(`    file: .prompts-gpt/${p.file}`);
                 console.log(`    run:  prompts-gpt run --prompt-file .prompts-gpt/${p.file}`);
             }
@@ -197,9 +205,12 @@ async function runCommand(command, flags) {
         if (assets.sweeps.length > 0) {
             console.log(`Sweep prompts (${assets.sweeps.length}):`);
             for (const s of assets.sweeps) {
-                console.log(`  ${s.name}`);
+                const iterCount = await readSweepIterationsFromFrontmatter(path.resolve(cwd, s.file));
+                const iterHint = iterCount ? ` (${iterCount} iterations)` : "";
+                const iterFlag = iterCount ? ` --iterations ${iterCount}` : "";
+                console.log(`  ${s.name}${iterHint}`);
                 console.log(`    file:  ${s.file}`);
-                console.log(`    sweep: prompts-gpt sweep --prompt-file ${s.file}`);
+                console.log(`    sweep: prompts-gpt sweep --prompt-file ${s.file}${iterFlag}`);
             }
             console.log("");
         }
@@ -240,20 +251,38 @@ async function runCommand(command, flags) {
         console.log(`  Credentials:  ${assets.credentialsFound ? "✓" : "✗ — run \`prompts-gpt init --token <token>\`"}`);
         console.log(`  Config:       ${assets.configFound ? "✓" : "✗ — run \`prompts-gpt setup\`"}`);
         console.log(`  Manifest:     ${assets.manifestFound ? "✓" : "✗ — run \`prompts-gpt sync\`"}`);
-        console.log(`  Prompts:      ${assets.prompts.length > 0 ? `✓ (${assets.prompts.length})` : "✗ — none found"}`);
+        const cloudCount = assets.prompts.filter((p) => p.source === "library" || p.source === "generated").length;
+        const localCount = assets.prompts.filter((p) => p.source === "local").length;
+        const promptSummary = assets.prompts.length > 0
+            ? `✓ (${assets.prompts.length}${cloudCount > 0 ? `, ${cloudCount} synced` : ""}${localCount > 0 ? `, ${localCount} local-only` : ""})`
+            : "✗ — none found";
+        console.log(`  Prompts:      ${promptSummary}`);
         console.log(`  Sweeps:       ${assets.sweeps.length > 0 ? `✓ (${assets.sweeps.length})` : "— none found"}`);
         console.log(`  Agents:       ${assets.agents.length > 0 ? `✓ (${assets.agents.length} targets)` : "✗ — run \`prompts-gpt sync\`"}`);
-        console.log(`  Providers:    ${availableProviders.length > 0 ? `✓ (${availableProviders.map((p) => p.provider).join(", ")})` : "✗ — no CLI found"}`);
+        if (availableProviders.length > 0) {
+            console.log(`  Providers:    ✓`);
+            for (const p of availableProviders) {
+                console.log(`    ${p.provider}: ${p.bin} | model: ${p.modelDefault}${p.version ? ` | ${p.version}` : ""}`);
+            }
+        }
+        else {
+            console.log("  Providers:    ✗ — no CLI found");
+        }
         console.log("");
         if (assets.prompts.length > 0 && availableProviders.length > 0) {
             console.log("Ready to run:");
             console.log(`  prompts-gpt run --prompt-file .prompts-gpt/${assets.prompts[0].file}`);
             if (assets.sweeps.length > 0) {
-                console.log(`  prompts-gpt sweep --prompt-file ${assets.sweeps[0].file}`);
+                for (const s of assets.sweeps) {
+                    console.log(`  prompts-gpt sweep --prompt-file ${s.file}`);
+                }
             }
         }
         else {
-            console.log("Next steps:");
+            console.log("Not ready yet. Quick fix:");
+            console.log("  prompts-gpt quickstart");
+            console.log("");
+            console.log("Or step by step:");
             let step = 1;
             if (!assets.credentialsFound)
                 console.log(`  ${step++}. prompts-gpt init --token <project-token>`);
@@ -295,7 +324,7 @@ async function runCommand(command, flags) {
             if (!config.defaultPromptFile && config.batchDefaults.promptFiles.length === 0 && !config.batchDefaults.manifestPath) {
                 const assets = await discoverWorkspaceAssets(cwd);
                 if (assets.prompts.length > 0 || assets.sweeps.length > 0) {
-                    console.log("No default prompt file configured. Available options:\n");
+                    console.log("No default prompt configured. No default prompt file configured. Available options:\n");
                     if (assets.prompts.length > 0) {
                         console.log("Prompt packs:");
                         for (const p of assets.prompts) {
@@ -303,7 +332,7 @@ async function runCommand(command, flags) {
                         }
                     }
                     if (assets.sweeps.length > 0) {
-                        console.log("\nSweep prompts:");
+                        console.log("\nSweep prompts (use `sweep` command):");
                         for (const s of assets.sweeps) {
                             console.log(`  prompts-gpt sweep --prompt-file ${s.file}`);
                         }
@@ -314,11 +343,43 @@ async function runCommand(command, flags) {
             }
         }
         const agent = resolveRunAgent(flags, config.defaultAgent);
+        if (Boolean(flags["dry-run"])) {
+            const providers = await detectProviders(cwd);
+            const resolvedProvider = resolveRunProvider(agent, providers, config.providerOrder);
+            const resolvedModel = getStringFlag(flags, "model")?.trim() || config.modelOverrides[resolvedProvider]?.trim() || "";
+            let resolvedPrompt = promptFile || getStringFlag(flags, "prompt-file") || config.defaultPromptFile || null;
+            if (!resolvedPrompt) {
+                try {
+                    const { resolveDefaultPromptFile: resolvePf } = await import("./index.js");
+                    resolvedPrompt = await resolvePf(cwd, config);
+                }
+                catch {
+                    resolvedPrompt = null;
+                }
+            }
+            const agentStr = getStringFlag(flags, "agent") ? agent : `${agent} (auto-selected)`;
+            console.log("[dry-run] Would execute:");
+            console.log(`  Agent: ${agentStr}`);
+            console.log(`  Provider: ${resolvedProvider}`);
+            console.log(`  Model: ${resolvedModel || "(default)"}`);
+            console.log(`  Prompt: ${resolvedPrompt || "(none found — pass --prompt-file)"}`);
+            console.log(`  Timeout: ${getStringFlag(flags, "timeout") || config.timeoutSeconds}s`);
+            return;
+        }
+        const modelFlag = getStringFlag(flags, "model");
+        if (modelFlag && !Boolean(flags.json) && agent !== "router") {
+            const providers = await detectProviders(cwd);
+            const resolvedProvider = resolveRunProvider(agent, providers, config.providerOrder);
+            const mismatchWarning = warnModelProviderMismatch(resolvedProvider, modelFlag);
+            if (mismatchWarning) {
+                console.error(`[warning] ${mismatchWarning}`);
+            }
+        }
         const result = await runPrompt({
             cwd,
             promptFile,
             agent,
-            model: getStringFlag(flags, "model"),
+            model: modelFlag,
             timeoutSeconds: parsePositiveIntFlag(getStringFlag(flags, "timeout"), "timeout"),
             artifactsDir: getStringFlag(flags, "artifacts-dir"),
             runId: getStringFlag(flags, "run-id"),
@@ -331,14 +392,31 @@ async function runCommand(command, flags) {
             console.log(JSON.stringify(result, null, 2));
             return;
         }
-        const agentLabel = getStringFlag(flags, "agent") ? result.provider : `${result.provider} (auto-selected)`;
+        const agentLabel = getStringFlag(flags, "agent") ? result.provider : `${result.provider} (auto — first available from provider order)`;
         console.log(`Run ID: ${result.runId}`);
         console.log(`Provider: ${agentLabel} | Model: ${result.model}`);
         console.log(`Exit code: ${result.exitCode}`);
         console.log(`Duration: ${formatDuration(result.durationMs)}`);
+        if (hasTokenUsage(result.tokenUsage)) {
+            console.log(`Tokens: ${formatTokenUsage(result.tokenUsage)}`);
+        }
         console.log(`Run dir: ${result.runDir}`);
         console.log(`Summary: ${result.summaryFile}`);
         console.log(`Log: ${result.logFile}`);
+        if (result.exitCode === 0) {
+            console.log("");
+            console.log(`View results: cat ${result.summaryFile}`);
+        }
+        if (result.exitCode !== 0) {
+            const diagnostics = await extractRunDiagnostics(result.logFile, result.provider, result.model);
+            if (diagnostics.length > 0) {
+                console.log("");
+                console.log("Diagnostics:");
+                for (const d of diagnostics) {
+                    console.log(`  ${d}`);
+                }
+            }
+        }
         return;
     }
     if (command === "run-batch") {
@@ -379,9 +457,13 @@ async function runCommand(command, flags) {
             return;
         }
         console.log(`Batch complete: total=${result.total} success=${result.success} failed=${result.failed}`);
+        if (hasTokenUsage(result.tokenUsage)) {
+            console.log(`Batch tokens: ${formatTokenUsage(result.tokenUsage)}`);
+        }
         for (const [idx, run] of result.results.entries()) {
             const status = run.exitCode === 0 ? "ok" : "FAIL";
-            console.log(`  [${idx + 1}/${result.total}] ${status} ${path.basename(run.promptFile)} -> ${run.provider} (exit=${run.exitCode}, ${formatDuration(run.durationMs)})`);
+            const usageStr = hasTokenUsage(run.tokenUsage) ? `, tokens=${run.tokenUsage.totalTokens.toLocaleString()}` : "";
+            console.log(`  [${idx + 1}/${result.total}] ${status} ${path.basename(run.promptFile)} -> ${run.provider} (exit=${run.exitCode}, ${formatDuration(run.durationMs)}${usageStr})`);
         }
         return;
     }
@@ -391,22 +473,43 @@ async function runCommand(command, flags) {
         const config = await loadRunConfig(cwd);
         warnOnConfigIssues(config);
         if (!sweepPromptFile && !Boolean(flags.json)) {
-            if (!config.defaultPromptFile) {
-                const assets = await discoverWorkspaceAssets(cwd);
-                if (assets.sweeps.length > 0) {
-                    console.log("No default prompt file configured. Available sweep prompts:\n");
-                    for (const s of assets.sweeps) {
-                        console.log(`  prompts-gpt sweep --prompt-file ${s.file}`);
-                    }
-                    if (assets.prompts.length > 0) {
-                        console.log("\nOr run a prompt pack instead:");
-                        for (const p of assets.prompts.slice(0, 3)) {
-                            console.log(`  prompts-gpt run --prompt-file .prompts-gpt/${p.file}`);
-                        }
+            const assets = await discoverWorkspaceAssets(cwd);
+            if (assets.sweeps.length === 1) {
+                const autoFile = assets.sweeps[0].file;
+                const iterFromFm = await readSweepIterationsFromFrontmatter(path.resolve(cwd, autoFile));
+                console.log(`Auto-selected sweep: ${autoFile}${iterFromFm ? ` (${iterFromFm} iterations from frontmatter)` : ""}`);
+                flags["prompt-file"] = autoFile;
+                if (iterFromFm && !getStringFlag(flags, "iterations")) {
+                    flags.iterations = String(iterFromFm);
+                }
+            }
+            else if (assets.sweeps.length > 1) {
+                console.log(`${assets.sweeps.length} sweep files found. Pick one with --prompt-file:\n`);
+                for (const s of assets.sweeps) {
+                    const iterCount = await readSweepIterationsFromFrontmatter(path.resolve(cwd, s.file));
+                    const iterFlag = iterCount ? ` --iterations ${iterCount}` : "";
+                    console.log(`  prompts-gpt sweep --prompt-file ${s.file}${iterFlag}`);
+                }
+                if (assets.prompts.length > 0) {
+                    console.log("\nOr run a single prompt:");
+                    for (const p of assets.prompts.slice(0, 3)) {
+                        console.log(`  prompts-gpt run --prompt-file .prompts-gpt/${p.file}`);
                     }
-                    console.log("\nOr set a default: prompts-gpt setup --prompt-file <path>");
-                    return;
                 }
+                return;
+            }
+            else {
+                console.log("No sweep files found.");
+                console.log("  Create .prompts-gpt/sweeps/<name>.md to add sweep prompts.");
+                console.log("  Or set a default: prompts-gpt setup --prompt-file <path>");
+                console.log("  Run `prompts-gpt list` to see what's available.");
+                return;
+            }
+        }
+        if (!getStringFlag(flags, "iterations") && getStringFlag(flags, "prompt-file")) {
+            const iterFromFm = await readSweepIterationsFromFrontmatter(path.resolve(cwd, getStringFlag(flags, "prompt-file")));
+            if (iterFromFm) {
+                flags.iterations = String(iterFromFm);
             }
         }
         const agent = resolveRunAgent(flags, config.defaultAgent);
@@ -454,6 +557,8 @@ async function runCommand(command, flags) {
             dryRun: Boolean(flags["dry-run"]),
             maxRunDirs: parsePositiveIntFlag(getStringFlag(flags, "max-run-dirs"), "max-run-dirs"),
             summaryLines: parsePositiveIntFlag(getStringFlag(flags, "summary-lines"), "summary-lines"),
+            background: Boolean(flags.background),
+            permissionMode: getStringFlag(flags, "permission-mode"),
             onProgress,
         });
         if (Boolean(flags.json)) {
@@ -461,11 +566,25 @@ async function runCommand(command, flags) {
             return;
         }
         if (result.dryRun) {
+            const iterTimeout = parsePositiveIntFlag(getStringFlag(flags, "iteration-timeout"), "iteration-timeout") ?? 5400;
+            const estMaxDuration = result.totalIterations * iterTimeout;
             console.log("[dry-run] Would execute sweep with:");
             console.log(`  Provider: ${result.provider}`);
             console.log(`  Model: ${result.model}`);
             console.log(`  Iterations: ${result.totalIterations}`);
             console.log(`  Prompt: ${result.promptFile}`);
+            console.log(`  Max duration: ~${formatDuration(estMaxDuration * 1000)} (${result.totalIterations} x ${formatDuration(iterTimeout * 1000)})`);
+            try {
+                const { readFile: fsRead } = await import("node:fs/promises");
+                const previewText = await fsRead(result.promptFile, "utf8");
+                const previewLines = previewText.split("\n").slice(0, 5);
+                console.log(`  Prompt preview:`);
+                for (const line of previewLines)
+                    console.log(`    ${line}`);
+                if (previewText.split("\n").length > 5)
+                    console.log(`    ... (${previewText.split("\n").length - 5} more lines)`);
+            }
+            catch { /* skip preview */ }
             return;
         }
         console.log(`Run ID: ${result.runId}`);
@@ -473,13 +592,131 @@ async function runCommand(command, flags) {
         console.log(`Prompt: ${result.promptFile}`);
         console.log(`Iterations: ${result.succeeded}/${result.totalIterations} succeeded`);
         console.log(`Duration: ${formatDuration(result.totalDurationMs)}`);
+        if (hasTokenUsage(result.tokenUsage)) {
+            console.log(`Tokens: ${formatTokenUsage(result.tokenUsage)}`);
+        }
         console.log(`Run dir: ${result.runDir}`);
         console.log(`Manifest: ${result.manifestFile}`);
+        if (result.iterations.length > 1) {
+            console.log("");
+            console.log("Per-iteration results:");
+            for (const iter of result.iterations) {
+                const tools = iter.toolCounts;
+                const toolStr = tools.total > 0 ? ` | tools: ${tools.total} (R:${tools.reads} W:${tools.writes} S:${tools.shells})` : "";
+                const usageStr = hasTokenUsage(iter.tokenUsage) ? ` | tokens: ${iter.tokenUsage.totalTokens.toLocaleString()}` : "";
+                console.log(`  [${iter.iteration}/${result.totalIterations}] ${iter.status} (${formatDuration(iter.durationMs)})${toolStr}${usageStr}`);
+            }
+            const totalTools = result.iterations.reduce((acc, i) => ({
+                reads: acc.reads + i.toolCounts.reads, writes: acc.writes + i.toolCounts.writes,
+                shells: acc.shells + i.toolCounts.shells, searches: acc.searches + i.toolCounts.searches,
+                webSearches: acc.webSearches + i.toolCounts.webSearches, total: acc.total + i.toolCounts.total,
+            }), { reads: 0, writes: 0, shells: 0, searches: 0, webSearches: 0, total: 0 });
+            if (totalTools.total > 0) {
+                console.log(`  Total tools: ${totalTools.total} (reads: ${totalTools.reads}, writes: ${totalTools.writes}, shells: ${totalTools.shells}, searches: ${totalTools.searches})`);
+            }
+        }
+        console.log("");
+        console.log("Inspect results:");
+        console.log(`  cat ${result.manifestFile}`);
+        console.log(`  ls ${result.runDir}`);
         if (result.failed > 0) {
             process.exitCode = 1;
         }
         return;
     }
+    if (command === "quickstart") {
+        const cwd = getResolvedCwd(flags);
+        const assets = await discoverWorkspaceAssets(cwd);
+        const providers = await detectProviders(cwd);
+        const availableProviders = providers.filter((p) => p.available);
+        console.log("Prompts-GPT Quickstart");
+        console.log("======================");
+        console.log("");
+        if (!assets.credentialsFound) {
+            console.log("Step 1: Save your project token");
+            console.log("  prompts-gpt init --token-prompt");
+            console.log("");
+            console.log("  Get your token from: https://prompts-gpt.com/studio/projects");
+            console.log("");
+            console.log("Run `prompts-gpt quickstart` again after saving your token.");
+            return;
+        }
+        console.log("✓ Credentials found");
+        if (!assets.configFound) {
+            console.log("→ Setting up config...");
+            try {
+                await initRunConfig({ cwd, overwrite: false });
+                console.log("✓ Config created");
+            }
+            catch {
+                console.log("✓ Config already exists");
+            }
+        }
+        else {
+            console.log("✓ Config found");
+        }
+        if (availableProviders.length === 0) {
+            console.log("");
+            console.log("✗ No provider CLIs found. Install at least one:");
+            console.log("  - codex:  npm install -g @openai/codex");
+            console.log("  - claude: npm install -g @anthropic-ai/claude-code");
+            console.log("  - cursor: Install Cursor IDE (includes `agent` CLI)");
+            return;
+        }
+        console.log(`✓ Providers: ${availableProviders.map((p) => p.provider).join(", ")}`);
+        if (assets.prompts.length === 0 && assets.sweeps.length === 0) {
+            console.log("");
+            console.log("→ No prompts found. Syncing from Prompts Studio...");
+            try {
+                const clientOpts = await resolveClientOptions("quickstart", flags).catch(() => null);
+                if (clientOpts) {
+                    const qsClient = new PromptsGptClient(clientOpts);
+                    const pulledPrompts = await qsClient.pullPrompts();
+                    if (pulledPrompts.length > 0) {
+                        const syncResult = await syncPrompts(pulledPrompts, { cwd, agent: "all" });
+                        console.log(`✓ Synced ${syncResult.markdown.written.length} prompt(s) and ${syncResult.agents.written.length} agent file(s)`);
+                        const refreshed = await discoverWorkspaceAssets(cwd);
+                        if (refreshed.prompts.length > 0 || refreshed.sweeps.length > 0) {
+                            console.log(`✓ Prompts: ${refreshed.prompts.length} prompt packs, ${refreshed.sweeps.length} sweeps`);
+                        }
+                    }
+                    else {
+                        console.log("No prompts found in your Prompts Studio library.");
+                        console.log("  Configure prompts at: https://prompts-gpt.com/studio/projects");
+                        console.log("  Or run: prompts-gpt generate --goal \"Your task\"");
+                        return;
+                    }
+                }
+                else {
+                    console.log("✗ Could not sync (credentials issue). Run manually:");
+                    console.log("  prompts-gpt sync");
+                    return;
+                }
+            }
+            catch (syncErr) {
+                console.log(`✗ Sync failed: ${syncErr instanceof Error ? syncErr.message : String(syncErr)}`);
+                console.log("  Run manually: prompts-gpt sync");
+                return;
+            }
+            const refreshedAssets = await discoverWorkspaceAssets(cwd);
+            if (refreshedAssets.prompts.length === 0 && refreshedAssets.sweeps.length === 0) {
+                return;
+            }
+        }
+        console.log(`✓ Prompts: ${assets.prompts.length} prompt packs, ${assets.sweeps.length} sweeps`);
+        console.log("");
+        console.log("You're ready! Try these commands:");
+        console.log("");
+        if (assets.prompts.length > 0) {
+            console.log(`  prompts-gpt run --prompt-file .prompts-gpt/${assets.prompts[0].file}`);
+        }
+        if (assets.sweeps.length > 0) {
+            console.log(`  prompts-gpt sweep --prompt-file ${assets.sweeps[0].file}`);
+        }
+        console.log("  prompts-gpt list        — see all available prompts and sweeps");
+        console.log("  prompts-gpt status      — check workspace readiness");
+        return;
+    }
     if (command === "load-config") {
         const cwd = getResolvedCwd(flags);
         const client = await createClientForCommand(command, flags);
@@ -532,10 +769,22 @@ async function runCommand(command, flags) {
                 console.log(`  prompts-gpt run --prompt-file .prompts-gpt/${firstFile}`);
             }
         }
+        const lcAssets = await discoverWorkspaceAssets(cwd);
+        if (lcAssets.sweeps.length > 0) {
+            console.log(`\nSweep files available (${lcAssets.sweeps.length}):`);
+            for (const s of lcAssets.sweeps) {
+                console.log(`  prompts-gpt sweep --prompt-file ${s.file}`);
+            }
+        }
         return;
     }
     if (command === "init") {
-        const token = await resolveTokenInput(flags, { command });
+        let token = await resolveTokenInput(flags, { command });
+        if (!token && process.stdin.isTTY && process.stdout.isTTY) {
+            console.log("No token flag provided — prompting interactively.");
+            console.log("Get your token from: https://prompts-gpt.com/studio/projects\n");
+            token = await readTokenFromPrompt(command);
+        }
         if (!token) {
             throw new CliError("Run `prompts-gpt init --token <project-token>`, `--token-stdin`, or `--token-prompt`.", CLI_EXIT_CODES.validation, {
                 helpCommand: "init",
@@ -573,7 +822,10 @@ async function runCommand(command, flags) {
         });
         console.log(`Saved Prompts-GPT credentials to ${result.credentialsPath}`);
         console.log("The credentials file is added to .gitignore.");
-        console.log("Next: prompts-gpt sync");
+        console.log("");
+        console.log("Next steps:");
+        console.log("  prompts-gpt quickstart  — interactive setup (recommended)");
+        console.log("  prompts-gpt sync        — pull prompts and sync agent files");
         return;
     }
     if (command === "pull") {
@@ -593,28 +845,30 @@ async function runCommand(command, flags) {
         if (result.skipped.length) {
             console.log(`Skipped ${result.skipped.length} existing file(s). Use --overwrite to replace them.`);
         }
+        if (result.written.length > 0) {
+            console.log("");
+            console.log("Run a pulled prompt:");
+            console.log(`  prompts-gpt run --prompt-file ${result.written[0]}`);
+            console.log("  prompts-gpt list  — see all available prompts");
+        }
         return;
     }
     if (command === "generate") {
         validateToolFlag(getStringFlag(flags, "tool"));
         const goal = getStringFlag(flags, "goal");
         if (!goal) {
-            throw new CliError("Prompt generation requires `--goal`.", CLI_EXIT_CODES.validation, {
-                helpCommand: "generate",
-            });
+            throw new CliError("Prompt generation requires `--goal`.\n\n" +
+                "Example:\n" +
+                "  prompts-gpt generate --goal \"Review pull requests for security issues\"\n" +
+                "  prompts-gpt generate --goal \"Write unit tests\" --sync-agents\n\n" +
+                "Use --sync-agents to also write agent files (AGENTS.md, .cursor/rules, etc.).", CLI_EXIT_CODES.validation, { helpCommand: "generate" });
         }
         validateAgentFlag(getStringFlag(flags, "agent"));
+        if (!Boolean(flags.json)) {
+            printDataTransmissionNotice("generate", { goal, context: getStringFlag(flags, "context"), constraints: getStringFlag(flags, "constraints") });
+        }
         const client = await createClientForCommand(command, flags);
-        const prompt = await client.generatePrompt({
-            goal,
-            context: getStringFlag(flags, "context") || "",
-            constraints: getStringFlag(flags, "constraints") || "",
-            desiredOutput: getStringFlag(flags, "desired-output") || "A reusable prompt pack saved as Markdown.",
-            tool: getStringFlag(flags, "tool") || "Codex",
-            mode: getStringFlag(flags, "mode") || "implement",
-            artifactType: getStringFlag(flags, "artifact-type") || "prompt-file",
-            includeWebSearch: Boolean(flags["web-search"]),
-        });
+        const prompt = await client.generatePrompt(buildGenerateInput(flags));
         const cwd = getResolvedCwd(flags);
         const result = await writePromptMarkdownFiles([prompt], {
             cwd,
@@ -624,7 +878,12 @@ async function runCommand(command, flags) {
         const shouldSyncAgents = Boolean(flags["sync-agents"]) || typeof getStringFlag(flags, "agent") === "string";
         if (shouldSyncAgents) {
             const target = getStringFlag(flags, "agent") || "all";
-            const pulled = await client.pullPrompts().catch(() => []);
+            const pulled = await client.pullPrompts().catch((err) => {
+                if (!Boolean(flags.json)) {
+                    console.error(`[warning] Could not pull existing prompts for agent sync: ${err.message}`);
+                }
+                return [];
+            });
             const syncedPrompts = mergePromptPacks([prompt, ...pulled]);
             const agentResult = await writeAgentFiles(syncedPrompts, {
                 cwd,
@@ -653,17 +912,11 @@ async function runCommand(command, flags) {
         const goal = getStringFlag(flags, "goal");
         const generatedOnly = Boolean(flags["generated-only"]);
         const client = await createClientForCommand(command, flags);
+        if (goal && !Boolean(flags.json)) {
+            printDataTransmissionNotice("sync", { goal, context: getStringFlag(flags, "context"), constraints: getStringFlag(flags, "constraints") });
+        }
         if (goal) {
-            prompts.push(await client.generatePrompt({
-                goal,
-                context: getStringFlag(flags, "context") || "",
-                constraints: getStringFlag(flags, "constraints") || "",
-                desiredOutput: getStringFlag(flags, "desired-output") || "A reusable prompt pack saved as Markdown.",
-                tool: getStringFlag(flags, "tool") || "Codex",
-                mode: getStringFlag(flags, "mode") || "implement",
-                artifactType: getStringFlag(flags, "artifact-type") || "prompt-file",
-                includeWebSearch: Boolean(flags["web-search"]),
-            }));
+            prompts.push(await client.generatePrompt(buildGenerateInput(flags)));
         }
         if (!generatedOnly) {
             prompts.push(...await client.pullPrompts(buildPullQuery(flags, parsedLimit)));
@@ -691,6 +944,21 @@ async function runCommand(command, flags) {
         }
         console.log(`Synced ${result.agents.written.length} agent file(s): ${result.agents.targets.join(", ")}.`);
         console.log(`Manifest: ${result.manifest.manifestPath}`);
+        const syncCwd = getResolvedCwd(flags);
+        const postSyncAssets = await discoverWorkspaceAssets(syncCwd);
+        if (postSyncAssets.sweeps.length > 0) {
+            console.log(`Sweeps: ${postSyncAssets.sweeps.length} sweep file(s) available.`);
+        }
+        const postProviders = await detectProviders(syncCwd);
+        const postAvailable = postProviders.filter((p) => p.available);
+        if (postAvailable.length > 0 && postSyncAssets.prompts.length > 0) {
+            console.log("");
+            console.log("Next steps:");
+            console.log(`  prompts-gpt run --prompt-file .prompts-gpt/${postSyncAssets.prompts[0].file}`);
+            if (postSyncAssets.sweeps.length > 0) {
+                console.log(`  prompts-gpt sweep --prompt-file ${postSyncAssets.sweeps[0].file}`);
+            }
+        }
         return;
     }
     if (command === "project") {
@@ -744,7 +1012,11 @@ async function resolveClientOptions(command, flags) {
         }
     }
     if (!token) {
-        throw new CliError("Project token is missing. Run `prompts-gpt init --token <project-token>` or pass `--token`, `--token-stdin`, or `--token-prompt` for this command.", CLI_EXIT_CODES.auth, { helpCommand: command });
+        const cloudCommands = new Set(["sync", "generate", "pull", "load-config", "project"]);
+        const extra = cloudCommands.has(command)
+            ? `\n\nThis command connects to prompts-gpt.com. Set up credentials first:\n  prompts-gpt init --token <project-token>\n  prompts-gpt quickstart`
+            : "";
+        throw new CliError(`Project token is missing. Run \`prompts-gpt init --token <project-token>\` or pass \`--token\`, \`--token-stdin\`, or \`--token-prompt\` for this command.${extra}`, CLI_EXIT_CODES.auth, { helpCommand: command });
     }
     return {
         token,
@@ -911,7 +1183,7 @@ function getCommandOptions(command) {
             help: { type: "boolean" },
             cwd: { type: "string" },
             json: { type: "boolean" },
-            "prompt-file": { type: "string" },
+            "prompt-file": { type: "string", short: "f" },
             agent: { type: "string" },
             model: { type: "string" },
             timeout: { type: "string" },
@@ -921,6 +1193,7 @@ function getCommandOptions(command) {
             "no-approve-mcps": { type: "boolean" },
             background: { type: "boolean" },
             "permission-mode": { type: "string" },
+            "dry-run": { type: "boolean" },
         };
     }
     if (command === "sweep") {
@@ -928,10 +1201,10 @@ function getCommandOptions(command) {
             help: { type: "boolean" },
             cwd: { type: "string" },
             json: { type: "boolean" },
-            "prompt-file": { type: "string" },
+            "prompt-file": { type: "string", short: "f" },
             agent: { type: "string" },
             model: { type: "string" },
-            iterations: { type: "string" },
+            iterations: { type: "string", short: "n" },
             "iteration-timeout": { type: "string" },
             "max-retries": { type: "string" },
             "artifacts-dir": { type: "string" },
@@ -967,7 +1240,7 @@ function getCommandOptions(command) {
             agent: { type: "string" },
         };
     }
-    if (command === "list" || command === "status" || command === "validate" || command === "providers" || command === "doctor") {
+    if (command === "quickstart" || command === "list" || command === "status" || command === "validate" || command === "providers" || command === "doctor") {
         return {
             help: { type: "boolean" },
             cwd: { type: "string" },
@@ -979,18 +1252,61 @@ function getCommandOptions(command) {
     });
 }
 function toCliParseError(error, command) {
-    const message = normalizeParseErrorMessage(error instanceof Error ? error.message : String(error));
+    const runnableCmd = isRunnableCommand(command) ? command : undefined;
+    const message = normalizeParseErrorMessage(error instanceof Error ? error.message : String(error), runnableCmd);
     return new CliError(message, CLI_EXIT_CODES.usage, {
         helpCommand: command,
     });
 }
-function normalizeParseErrorMessage(message) {
+function normalizeParseErrorMessage(message, command) {
     const trimmed = message.trim();
     if (trimmed.startsWith("Unknown option")) {
-        return `${trimmed}.`;
+        const match = trimmed.match(/Unknown option '(--[^']+)'/);
+        const unknownFlag = match?.[1];
+        const base = trimmed.endsWith(".") ? trimmed : `${trimmed}.`;
+        if (unknownFlag && command) {
+            const suggestion = suggestClosestFlag(unknownFlag, command);
+            if (suggestion) {
+                return `${base} Did you mean ${suggestion}?`;
+            }
+        }
+        return base;
     }
     return trimmed;
 }
+function suggestClosestFlag(unknown, command) {
+    const options = getCommandOptions(command);
+    const flagName = unknown.replace(/^--/, "");
+    const candidates = Object.keys(options);
+    let best = null;
+    let bestScore = 0;
+    for (const candidate of candidates) {
+        const score = computeFlagSimilarity(flagName, candidate);
+        if (score > bestScore && score >= 0.4) {
+            bestScore = score;
+            best = candidate;
+        }
+    }
+    return best ? `--${best}` : null;
+}
+function computeFlagSimilarity(a, b) {
+    if (a === b)
+        return 1;
+    const shorter = a.length < b.length ? a : b;
+    const longer = a.length < b.length ? b : a;
+    if (longer.startsWith(shorter) || longer.endsWith(shorter))
+        return 0.8;
+    if (longer.includes(shorter) && shorter.length >= 3)
+        return 0.6;
+    if (shorter.length === 0)
+        return 0;
+    let matches = 0;
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+        if (a[i] === b[i])
+            matches++;
+    }
+    return matches / Math.max(a.length, b.length);
+}
 function validateFlagConflicts(command, flags) {
     const tokenSourceCount = [Boolean(flags.token), Boolean(flags["token-stdin"]), Boolean(flags["token-prompt"])].filter(Boolean).length;
     if (tokenSourceCount > 1) {
@@ -1266,32 +1582,36 @@ Usage:
   prompts-gpt help [command]
   prompts-gpt version
 
-Commands:
-  init            Save a project token in .prompts-gpt/.credentials.json
-  setup           Scaffold .prompts-gpt/config.json for local orchestration
-  load-config     Pull configuration and prompts directly from Prompts Studio
-  pull            Download prompt packs as Markdown files
-  generate        Generate one prompt pack from a goal
-  sync            Generate and/or pull prompt packs, then sync agent files
-  list            Show available prompts, sweeps, and agent integrations
+Setup:
+  quickstart      Interactive setup — credentials, config, and first run
+  init            Save a project token
+  setup           Scaffold local orchestration config
   status          Show workspace readiness and next steps
-  validate        Validate .prompts-gpt/config.json and report issues
-  run             Execute a prompt file with local agent orchestration
-  run-batch       Execute multiple prompt files from config, manifest, or list
-  sweep           Multi-iteration prompt execution with progress and summaries
-  providers       Show detected local provider CLIs
-  doctor          Validate local run prerequisites and config
-  project         Show the current project linked to the token
-  version         Show the current CLI version
-  help            Show global or command-specific help
+  doctor          Validate prerequisites and config
+
+Sync & Generate:
+  sync            Pull prompt packs and sync agent files
+  pull            Download prompt packs as Markdown files
+  generate        Generate a prompt pack from a goal
+  load-config     Pull config and prompts from Prompts Studio
+
+Run:
+  run             Execute one prompt with a local agent (-f <file>)
+  run-batch       Execute multiple prompts
+  sweep           Multi-iteration execution (-f <file> -n <count>)
+
+Inspect:
+  list            Show prompts, sweeps, and agent integrations
+  validate        Check config for errors
+  providers       Show detected provider CLIs
+  project         Show project linked to the token
 
 Global options:
   --help          Show help
   --version       Show the current CLI version
 
-Supported tools: ${VALID_TOOLS.join(", ")}
-Supported agent targets: ${SUPPORTED_AGENT_TARGETS.join(", ")}
-Run agent profiles: ${ORCHESTRATION_AGENT_PROFILES.join(", ")}
+Providers: ${ORCHESTRATION_AGENT_PROFILES.filter((p) => p !== "router").join(", ")} (or router for auto-select)
+Agent targets: ${SUPPORTED_AGENT_TARGETS.join(", ")}
 `);
 }
 function parsePositiveIntFlag(raw, flagName) {
@@ -1339,18 +1659,24 @@ function getCommandHelp(command) {
         return `prompts-gpt init
 
 Usage:
-  prompts-gpt init (--token <project-token> | --token-stdin | --token-prompt) [--api-url <url>] [--cwd <path>]
+  prompts-gpt init [--token <project-token> | --token-stdin | --token-prompt] [--api-url <url>] [--cwd <path>]
 
 Why use it:
-  Stores a project token in a local credentials file so day-one CLI usage does not require re-pasting secrets on every command.
+  Stores a project token locally so you don't have to pass it on every command.
+  If run without flags in an interactive terminal, it will prompt for the token.
 
 Options:
   --token <token>       Project API token. Must start with pgpt_.
-  --token-stdin         Read the project token from stdin so it does not end up in shell history.
+  --token-stdin         Read the project token from stdin (for CI/CD pipelines).
   --token-prompt        Prompt for the project token without echoing it.
   --api-url <url>       Custom API base URL for self-hosted instances.
-  --cwd <path>          Target project directory that will receive .prompts-gpt/.credentials.json.
+  --cwd <path>          Target project directory.
   --help                Show this command help.
+
+Examples:
+  prompts-gpt init                                  # interactive prompt
+  prompts-gpt init --token pgpt_abc123              # direct token
+  printf '%s' "$TOKEN" | prompts-gpt init --token-stdin  # CI/CD
 `;
     }
     if (command === "setup") {
@@ -1411,6 +1737,10 @@ Usage:
 Why use it:
   Pulls prompt packs into local Markdown files so teams can review and use the same prompt assets inside their repository.
 
+Data privacy:
+  Downloads prompts from your prompts-gpt.com project library.
+  No local files or repo content are uploaded.
+
 Options:
   --query <text>        Search query for the project prompt library.
   --q <text>            Short alias for --query.
@@ -1437,6 +1767,11 @@ Usage:
 Why use it:
   Creates a new reusable prompt pack from a concrete developer goal, then optionally installs agent-readable files immediately.
 
+Data privacy:
+  The text you pass via --goal, --context, and --constraints is sent to prompts-gpt.com
+  for AI-powered prompt generation. No local files or repo content are uploaded.
+  Do not include PII, secrets, or confidential data in these flags.
+
 Options:
   --goal <text>            Required. The task to generate a prompt pack for.
   --context <text>         Extra project or stack context for the generator.
@@ -1449,13 +1784,19 @@ Options:
   --out <dir>              Output directory inside the current project. Default: .prompts-gpt
   --overwrite              Replace an existing generated Markdown file.
   --agent <targets>        Sync agent files for specific targets after generation.
-  --sync-agents            Sync all agent files after generation.
+                           When set, also writes agent-specific files (AGENTS.md, .cursor/rules, etc.).
+  --sync-agents            Sync all agent files after generation (same as --agent all).
   --token <token>          Override the saved local token for this command only.
   --token-stdin            Read the override token from stdin for this command only.
   --token-prompt           Prompt for the override token without echoing it.
   --api-url <url>          Override the saved API base URL for this command only.
   --cwd <path>             Project directory to inspect for local credentials and output files.
   --help                   Show this command help.
+
+Examples:
+  prompts-gpt generate --goal "Review PRs for security issues"
+  prompts-gpt generate --goal "Write unit tests" --sync-agents
+  prompts-gpt generate --goal "Add error handling" --agent cursor,codex
 `;
     }
     if (command === "sync") {
@@ -1467,6 +1808,13 @@ Usage:
 Why use it:
   Gives teams a one-command path to refresh Markdown prompts, agent files, and the local manifest from the same source of truth.
 
+Data privacy:
+  Prompts are downloaded from your prompts-gpt.com project library.
+  When --goal is used, the text you pass is sent to prompts-gpt.com for AI generation.
+  No local files or repo content are uploaded — only explicit flag values are transmitted.
+  Do not include PII, secrets, or confidential data in --goal, --context, or --constraints.
+  Use --dry-run to preview what would be synced without sending or writing anything.
+
 Options:
   --goal <text>            Generate one prompt pack before syncing.
   --generated-only         Skip library pull and sync only the generated prompt pack from --goal.
@@ -1492,19 +1840,26 @@ Options:
   --api-url <url>          Override the saved API base URL for this command only.
   --cwd <path>             Project directory to inspect for local credentials and output files.
   --help                   Show this command help.
+
+Examples:
+  prompts-gpt sync                                      # pull all prompts + sync agent files
+  prompts-gpt sync --goal "Add error handling"           # generate + pull + sync
+  prompts-gpt sync --dry-run                             # preview without writing
+  prompts-gpt sync --agent cursor,codex                  # sync only specific agents
 `;
     }
     if (command === "run") {
         return `prompts-gpt run
 
 Usage:
-  prompts-gpt run [--prompt-file <path>] [--agent codex|cursor|claude|copilot|router] [--model <name>] [--timeout <seconds>] [--artifacts-dir <path>] [--run-id <id>] [--sandbox <mode>] [--no-approve-mcps] [--background] [--permission-mode <mode>] [--json] [--cwd <path>]
+  prompts-gpt run [-f <path>] [--agent <name>] [--model <name>] [--timeout <seconds>] [--dry-run]
 
 Why use it:
-  Executes one local prompt file with the built-in provider adapter runtime and writes run artifacts. If \`--prompt-file\` is omitted, the command uses the configured default prompt.
+  Executes one local prompt file with the built-in provider adapter runtime and writes run artifacts.
+  If \`--prompt-file\` is omitted and only one prompt exists locally, it is auto-selected.
 
 Options:
-  --prompt-file <path>       Optional explicit prompt Markdown or text file.
+  -f, --prompt-file <path>   Optional explicit prompt Markdown or text file.
   --agent <name>             Orchestration profile. Default from ${DEFAULT_RUN_CONFIG_PATH} or router.
   --model <name>             Optional model override for the selected provider.
   --timeout <seconds>        Execution timeout in seconds.
@@ -1514,6 +1869,7 @@ Options:
   --no-approve-mcps          Disable Cursor MCP auto-approval flag.
   --background               Run as a background agent (Cursor cloud agent mode).
   --permission-mode <mode>   Claude Code permission mode. Default: acceptEdits.
+  --dry-run                  Preview the execution parameters without actually running.
   --json                     Print machine-readable JSON output.
   --cwd <path>               Project directory.
   --help                     Show this command help.
@@ -1523,7 +1879,7 @@ Options:
         return `prompts-gpt run-batch
 
 Usage:
-  prompts-gpt run-batch [--manifest <path> | --prompt-files <a,b,c>] [--agent codex|cursor|claude|copilot|router] [--model <name>] [--timeout <seconds>] [--artifacts-dir <path>] [--json] [--cwd <path>]
+  prompts-gpt run-batch [--manifest <path> | --prompt-files <a,b,c>] [--agent <name>] [--model <name>] [--timeout <seconds>]
 
 Why use it:
   Executes multiple prompt files in sequence using the configured prompt source, a manifest, or an explicit file list.
@@ -1538,25 +1894,31 @@ Options:
   --json                 Print machine-readable JSON output.
   --cwd <path>           Project directory.
   --help                 Show this command help.
+
+Examples:
+  prompts-gpt run-batch --manifest .prompts-gpt/manifest.json
+  prompts-gpt run-batch --prompt-files .prompts-gpt/review.md,.prompts-gpt/tests.md
 `;
     }
     if (command === "sweep") {
         return `prompts-gpt sweep
 
 Usage:
-  prompts-gpt sweep [--prompt-file <path>] [--agent codex|cursor|claude|copilot|router] [--model <name>] [--iterations <n>] [--iteration-timeout <seconds>] [--max-retries <n>] [--phase <name>] [--artifacts-dir <path>] [--run-id <id>] [--sandbox <mode>] [--no-approve-mcps] [--background] [--permission-mode <mode>] [--max-run-dirs <n>] [--summary-lines <n>] [--dry-run] [--json] [--cwd <path>]
+  prompts-gpt sweep [-f <path>] [-n <count>] [--agent <name>] [--model <name>] [--dry-run]
 
 Why use it:
-  Replaces the bash sweep scripts with a generic multi-iteration execution engine.
   Runs the same prompt N times, feeding each iteration's summary into the next.
-  Includes pre-flight checks, safety guards, SIGTERM handling, progress monitoring,
-  and a structured sweep manifest.
+  Includes pre-flight checks, safety guards, SIGTERM handling, and progress monitoring.
+
+  When --prompt-file is omitted and only one .prompts-gpt/sweeps/*.md file exists,
+  it is auto-selected. The iteration count defaults to the \`iterations:\` value
+  in the sweep file's YAML frontmatter (or 1 if not specified).
 
 Options:
-  --prompt-file <path>         Prompt file to sweep. Reads from config if omitted.
+  -f, --prompt-file <path>     Prompt file to sweep. Auto-detects local sweeps if omitted.
+  -n, --iterations <n>         Number of iterations. Default: from frontmatter or 1.
   --agent <name>               Orchestration profile. Default from config or router.
   --model <name>               Model override for the selected provider.
-  --iterations <n>             Number of sweep iterations. Default: 1
   --iteration-timeout <secs>   Timeout per iteration in seconds. Default: 5400 (90 min)
   --max-retries <n>            Max retries per iteration on spawn/timeout. Default: 2
   --phase <name>               Optional phase label injected into the prompt.
@@ -1572,6 +1934,12 @@ Options:
   --json                       Print machine-readable JSON output.
   --cwd <path>                 Project directory.
   --help                       Show this command help.
+
+Examples:
+  prompts-gpt sweep                                               # auto-pick local sweep
+  prompts-gpt sweep -f .prompts-gpt/sweeps/sdk-hardening.md       # explicit file
+  prompts-gpt sweep -f .prompts-gpt/sweeps/design.md -n 5         # 5 iterations
+  prompts-gpt sweep --dry-run                                     # preview without running
 `;
     }
     if (command === "list") {
@@ -1653,6 +2021,10 @@ Why use it:
   into your local workspace. Replaces the multi-step init + sync + setup flow
   for users who manage their prompt library in the Prompts Studio web app.
 
+Data privacy:
+  Downloads prompts and project config from your prompts-gpt.com project.
+  No local files or repo content are uploaded.
+
 Options:
   --agent <targets>       Comma-separated agent targets. Default: all
   --out <dir>             Output directory. Default: .prompts-gpt
@@ -1663,6 +2035,22 @@ Options:
   --api-url <url>         Override API URL.
   --cwd <path>            Project directory.
   --help                  Show this command help.
+`;
+    }
+    if (command === "quickstart") {
+        return `prompts-gpt quickstart
+
+Usage:
+  prompts-gpt quickstart [--json] [--cwd <path>]
+
+Why use it:
+  Walks through setup in one command — checks credentials, creates config, detects providers,
+  and shows runnable commands. The fastest path from install to first run.
+
+Options:
+  --json                Print machine-readable JSON output.
+  --cwd <path>          Project directory.
+  --help                Show this command help.
 `;
     }
     if (command === "version") {
@@ -1684,6 +2072,41 @@ Why use it:
   Shows focused usage for the exact command you are trying to run so shell users do not have to scan the full command list.
 `;
 }
+async function readSweepIterationsFromFrontmatter(filePath) {
+    try {
+        const { readFile: fsRead } = await import("node:fs/promises");
+        const content = await fsRead(filePath, "utf8");
+        const match = content.match(/iterations:\s*(\d+)/i);
+        if (match) {
+            const val = parseInt(match[1], 10);
+            if (val > 0 && val <= 50)
+                return val;
+        }
+    }
+    catch { /* skip */ }
+    return null;
+}
+function buildGenerateInput(flags) {
+    return {
+        goal: getStringFlag(flags, "goal") || "",
+        context: sanitizeGenerateInput(getStringFlag(flags, "context") || ""),
+        constraints: sanitizeGenerateInput(getStringFlag(flags, "constraints") || ""),
+        desiredOutput: getStringFlag(flags, "desired-output") || "A reusable prompt pack saved as Markdown.",
+        tool: getStringFlag(flags, "tool") || "Codex",
+        mode: getStringFlag(flags, "mode") || "implement",
+        artifactType: getStringFlag(flags, "artifact-type") || "prompt-file",
+        includeWebSearch: Boolean(flags["web-search"]),
+    };
+}
+function sanitizeGenerateInput(value) {
+    return value.replace(/pgpt_[a-zA-Z0-9]{4,}/g, "pgpt_***").replace(/sk-[a-zA-Z0-9]{20,}/g, "sk-***").replace(/ghp_[a-zA-Z0-9]{36,}/g, "ghp_***");
+}
+function printDataTransmissionNotice(command, input) {
+    console.log(`[notice] The --goal text${input.context ? ", --context" : ""}${input.constraints ? ", --constraints" : ""} you provided will be sent to prompts-gpt.com to generate a prompt.`);
+    console.log("[notice] Do not include PII, secrets, or confidential data in these flags.");
+    console.log(`[notice] No local files or repo content are uploaded. Only the explicit flag values for \`${command}\` are transmitted.`);
+    console.log("");
+}
 main().catch((error) => {
     if (error instanceof CliError) {
         console.error(error.message);
@@ -1708,6 +2131,46 @@ main().catch((error) => {
     console.error(msg.replace(/pgpt_[a-zA-Z0-9]{4,}/g, "pgpt_***"));
     process.exitCode = CLI_EXIT_CODES.general;
 });
+async function extractRunDiagnostics(logFile, provider, model) {
+    const diagnostics = [];
+    try {
+        const { readFile: fsReadFile } = await import("node:fs/promises");
+        const log = await fsReadFile(logFile, "utf8");
+        const errorLines = log.split("\n").filter((line) => line.startsWith("ERROR:") || line.includes('"error"'));
+        for (const line of errorLines.slice(0, 5)) {
+            if (line.includes("not supported")) {
+                const modelMatch = line.match(/The '([^']+)' model is not supported/);
+                const badModel = modelMatch?.[1] ?? model;
+                diagnostics.push(`Model "${badModel}" is not supported by ${provider} with your account.`);
+                diagnostics.push(`Fix: prompts-gpt run --model o4-mini`);
+                diagnostics.push(`Or:  prompts-gpt run --agent claude`);
+                break;
+            }
+            if (line.includes("unauthorized") || line.includes("authentication")) {
+                diagnostics.push(`Authentication failed for ${provider}. Check your ${provider} account login.`);
+                diagnostics.push(`Fix: Run the ${provider} CLI directly to verify auth: ${provider} --version`);
+                break;
+            }
+            if (line.includes("rate_limit") || line.includes("429")) {
+                diagnostics.push(`Rate limited by ${provider}. Wait and try again.`);
+                break;
+            }
+        }
+        if (diagnostics.length === 0 && errorLines.length > 0) {
+            const firstError = errorLines[0].slice(0, 200);
+            diagnostics.push(`Provider error: ${firstError}`);
+        }
+        if (diagnostics.length === 0) {
+            diagnostics.push(`${provider} exited with code 1. Check the log for details:`);
+            diagnostics.push(`  cat ${logFile}`);
+            diagnostics.push(`Try a different provider: prompts-gpt run --agent claude`);
+        }
+    }
+    catch {
+        diagnostics.push(`Could not read log file. Check: ${logFile}`);
+    }
+    return diagnostics;
+}
 function warnOnConfigIssues(config) {
     for (const w of config.configWarnings) {
         console.error(`[config warning] ${w}`);
@@ -1728,4 +2191,21 @@ function formatApiError(error) {
     }
     return lines.join("\n");
 }
+function formatTokenUsage(usage) {
+    const parts = [
+        `total=${usage.totalTokens.toLocaleString()}`,
+        `input=${usage.inputTokens.toLocaleString()}`,
+        `output=${usage.outputTokens.toLocaleString()}`,
+    ];
+    if (usage.reasoningTokens > 0) {
+        parts.push(`reasoning=${usage.reasoningTokens.toLocaleString()}`);
+    }
+    if (usage.cacheReadTokens > 0) {
+        parts.push(`cache-read=${usage.cacheReadTokens.toLocaleString()}`);
+    }
+    if (usage.cacheWriteTokens > 0) {
+        parts.push(`cache-write=${usage.cacheWriteTokens.toLocaleString()}`);
+    }
+    return parts.join(" | ");
+}
 //# sourceMappingURL=cli.js.map