@prompts-gpt/client 0.2.2 → 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, PROMPTS_GPT_CREDENTIALS_FILE, PromptsGptApiError, PromptsGptClient, SUPPORTED_AGENT_TARGETS, loadLocalCredentials, saveLocalCredentials, syncPrompts, writeAgentFiles, 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 = ["init", "project", "pull", "generate", "sync", "install-agents", "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,11 +27,18 @@ class CliError extends Error {
 async function main() {
     const argv = process.argv.slice(2);
     if (argv.length === 0) {
-        printHelp();
+        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 normalizedArgv = normalizeLegacyFlags(argv);
-    const first = normalizedArgv[0];
+    const first = argv[0];
     if (first === "--help") {
         printHelp();
         return;
@@ -41,11 +48,11 @@ async function main() {
         return;
     }
     if (first === "help") {
-        handleHelpCommand(normalizedArgv.slice(1));
+        handleHelpCommand(argv.slice(1));
         return;
     }
     if (first === "version") {
-        if (normalizedArgv.length > 1) {
+        if (argv.length > 1) {
             throw new CliError("The `version` command does not accept additional arguments.", CLI_EXIT_CODES.usage, {
                 helpCommand: "version",
             });
@@ -62,7 +69,7 @@ async function main() {
             helpCommand: "help",
         });
     }
-    const flags = parseCommandFlags(command, normalizedArgv.slice(1));
+    const flags = parseCommandFlags(command, argv.slice(1));
     if (Boolean(flags.help)) {
         printHelp(command);
         return;
@@ -70,8 +77,714 @@ async function main() {
     await runCommand(command, flags);
 }
 async function runCommand(command, flags) {
+    if (command === "providers") {
+        const cwd = getResolvedCwd(flags);
+        const providers = await detectProviders(cwd);
+        if (Boolean(flags.json)) {
+            console.log(JSON.stringify({ cwd, providers }, null, 2));
+            return;
+        }
+        console.log(`Workspace: ${cwd}`);
+        for (const provider of providers) {
+            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;
+    }
+    if (command === "setup") {
+        const cwd = getResolvedCwd(flags);
+        const providerOrder = getStringFlag(flags, "provider-order")
+            ?.split(",")
+            .map((item) => item.trim())
+            .filter(Boolean);
+        validateProviderOrderFlag(providerOrder);
+        const promptFile = getStringFlag(flags, "prompt-file");
+        const promptFiles = getStringFlag(flags, "prompt-files")
+            ?.split(",")
+            .map((item) => item.trim())
+            .filter(Boolean);
+        const result = await initRunConfig({
+            cwd,
+            promptFile,
+            manifestPath: getStringFlag(flags, "manifest"),
+            promptFiles,
+            promptDir: getStringFlag(flags, "prompt-dir"),
+            defaultAgent: resolveRunAgent(flags, "router"),
+            providerOrder,
+            artifactsDir: getStringFlag(flags, "artifacts-dir"),
+            timeoutSeconds: parsePositiveIntFlag(getStringFlag(flags, "timeout"), "timeout"),
+            retryCount: parseNonNegativeIntFlag(getStringFlag(flags, "retry-count"), "retry-count"),
+            disallowDestructiveGit: Boolean(flags["allow-destructive-git"]) ? false : true,
+            modelOverrides: {
+                codex: getStringFlag(flags, "codex-model"),
+                cursor: getStringFlag(flags, "cursor-model"),
+                claude: getStringFlag(flags, "claude-model"),
+                copilot: getStringFlag(flags, "copilot-model"),
+            },
+            overwrite: Boolean(flags.overwrite),
+        });
+        if (Boolean(flags.json)) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Created run config: ${result.configPath}`);
+        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}`);
+        }
+        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>"}`);
+        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");
+        return;
+    }
+    if (command === "doctor") {
+        const cwd = getResolvedCwd(flags);
+        const report = await doctor(cwd);
+        if (Boolean(flags.json)) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        console.log(`Workspace: ${report.cwd}`);
+        console.log(`Node: ${report.nodeVersion} | OS: ${report.osPlatform}/${report.osArch} | CPUs: ${report.cpuCount}`);
+        console.log(`Config: ${report.configFound ? "found" : "not found"} (${report.configPath})`);
+        for (const provider of report.providers) {
+            console.log(`${provider.provider}: ${provider.available ? "available" : "missing"} | bin=${provider.bin}${provider.version ? ` | version=${provider.version}` : ""}`);
+            if (!provider.available) {
+                console.log(`  hint: ${provider.installHint}`);
+            }
+        }
+        for (const note of report.notes) {
+            console.log(`note: ${note}`);
+        }
+        return;
+    }
+    if (command === "list") {
+        const cwd = getResolvedCwd(flags);
+        const assets = await discoverWorkspaceAssets(cwd);
+        if (Boolean(flags.json)) {
+            console.log(JSON.stringify(assets, null, 2));
+            return;
+        }
+        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) {
+                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}`);
+            }
+            console.log("");
+        }
+        else {
+            console.log("Prompt packs: none found");
+            console.log("  Run `prompts-gpt sync` to pull prompt packs, or `prompts-gpt pull` to download them.");
+            console.log("");
+        }
+        if (assets.sweeps.length > 0) {
+            console.log(`Sweep prompts (${assets.sweeps.length}):`);
+            for (const s of assets.sweeps) {
+                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}${iterFlag}`);
+            }
+            console.log("");
+        }
+        else {
+            console.log("Sweep prompts: none found");
+            console.log("  Create .prompts-gpt/sweeps/<name>.md to add sweep prompts.");
+            console.log("");
+        }
+        if (assets.agents.length > 0) {
+            console.log(`Agent integrations (${assets.agents.length}):`);
+            for (const a of assets.agents) {
+                console.log(`  ${a.target} — ${a.file}`);
+            }
+            console.log("");
+        }
+        else {
+            console.log("Agent integrations: none synced");
+            console.log("  Run `prompts-gpt sync` to generate agent files.");
+            console.log("");
+        }
+        console.log(`Config:      ${assets.configFound ? "found" : "not found — run `prompts-gpt setup`"}`);
+        console.log(`Manifest:    ${assets.manifestFound ? "found" : "not found — run `prompts-gpt sync`"}`);
+        console.log(`Credentials: ${assets.credentialsFound ? "found" : "not found — run `prompts-gpt init --token <token>`"}`);
+        return;
+    }
+    if (command === "status") {
+        const cwd = getResolvedCwd(flags);
+        const assets = await discoverWorkspaceAssets(cwd);
+        const providers = await detectProviders(cwd);
+        const availableProviders = providers.filter((p) => p.available);
+        if (Boolean(flags.json)) {
+            console.log(JSON.stringify({ cwd, assets, providers }, null, 2));
+            return;
+        }
+        console.log(`Workspace: ${cwd}`);
+        console.log("");
+        console.log("Readiness:");
+        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\`"}`);
+        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\`"}`);
+        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) {
+                for (const s of assets.sweeps) {
+                    console.log(`  prompts-gpt sweep --prompt-file ${s.file}`);
+                }
+            }
+        }
+        else {
+            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>`);
+            if (assets.prompts.length === 0)
+                console.log(`  ${step++}. prompts-gpt sync`);
+            if (availableProviders.length === 0)
+                console.log(`  ${step++}. Install a provider CLI (codex, cursor agent, claude, copilot)`);
+            if (!assets.configFound)
+                console.log(`  ${step++}. prompts-gpt setup`);
+        }
+        return;
+    }
+    if (command === "validate") {
+        const cwd = getResolvedCwd(flags);
+        const result = await validateRunConfig(cwd);
+        if (Boolean(flags.json)) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Config: ${result.configPath}`);
+        console.log(`Valid: ${result.valid ? "yes" : "no"}`);
+        for (const e of result.errors) {
+            console.log(`  error: ${e}`);
+        }
+        for (const w of result.warnings) {
+            console.log(`  warning: ${w}`);
+        }
+        if (result.valid && result.errors.length === 0 && result.warnings.length === 0) {
+            console.log("  No issues found.");
+        }
+        return;
+    }
+    if (command === "run") {
+        const cwd = getResolvedCwd(flags);
+        const promptFile = getStringFlag(flags, "prompt-file");
+        const config = await loadRunConfig(cwd);
+        warnOnConfigIssues(config);
+        if (!promptFile && !Boolean(flags.json)) {
+            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 configured. No default prompt file configured. Available options:\n");
+                    if (assets.prompts.length > 0) {
+                        console.log("Prompt packs:");
+                        for (const p of assets.prompts) {
+                            console.log(`  prompts-gpt run --prompt-file .prompts-gpt/${p.file}`);
+                        }
+                    }
+                    if (assets.sweeps.length > 0) {
+                        console.log("\nSweep prompts (use `sweep` command):");
+                        for (const s of assets.sweeps) {
+                            console.log(`  prompts-gpt sweep --prompt-file ${s.file}`);
+                        }
+                    }
+                    console.log("\nOr set a default: prompts-gpt setup --prompt-file <path>");
+                    return;
+                }
+            }
+        }
+        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: modelFlag,
+            timeoutSeconds: parsePositiveIntFlag(getStringFlag(flags, "timeout"), "timeout"),
+            artifactsDir: getStringFlag(flags, "artifacts-dir"),
+            runId: getStringFlag(flags, "run-id"),
+            approveMcps: !Boolean(flags["no-approve-mcps"]),
+            sandboxMode: getStringFlag(flags, "sandbox"),
+            background: Boolean(flags.background),
+            permissionMode: getStringFlag(flags, "permission-mode"),
+        });
+        if (Boolean(flags.json)) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        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") {
+        const cwd = getResolvedCwd(flags);
+        const promptFiles = getStringFlag(flags, "prompt-files")
+            ?.split(",")
+            .map((item) => item.trim())
+            .filter(Boolean);
+        const config = await loadRunConfig(cwd);
+        warnOnConfigIssues(config);
+        if (!promptFiles && !getStringFlag(flags, "manifest") && !Boolean(flags.json)) {
+            if (!config.batchDefaults.manifestPath && config.batchDefaults.promptFiles.length === 0) {
+                const assets = await discoverWorkspaceAssets(cwd);
+                if (assets.prompts.length > 0) {
+                    console.log("No batch source configured. Available prompt packs:\n");
+                    const fileList = assets.prompts.map((p) => `.prompts-gpt/${p.file}`).join(",");
+                    console.log(`  prompts-gpt run-batch --prompt-files ${fileList}`);
+                    if (assets.manifestFound) {
+                        console.log(`  prompts-gpt run-batch --manifest .prompts-gpt/manifest.json`);
+                    }
+                    console.log("\nOr configure batch defaults: prompts-gpt setup");
+                    return;
+                }
+            }
+        }
+        const agent = resolveRunAgent(flags, config.defaultAgent);
+        const result = await runBatch({
+            cwd,
+            manifestPath: getStringFlag(flags, "manifest"),
+            promptFiles,
+            agent,
+            model: getStringFlag(flags, "model"),
+            timeoutSeconds: parsePositiveIntFlag(getStringFlag(flags, "timeout"), "timeout"),
+            artifactsDir: getStringFlag(flags, "artifacts-dir"),
+        });
+        if (Boolean(flags.json)) {
+            console.log(JSON.stringify(result, null, 2));
+            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";
+            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;
+    }
+    if (command === "sweep") {
+        const cwd = getResolvedCwd(flags);
+        const sweepPromptFile = getStringFlag(flags, "prompt-file");
+        const config = await loadRunConfig(cwd);
+        warnOnConfigIssues(config);
+        if (!sweepPromptFile && !Boolean(flags.json)) {
+            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}`);
+                    }
+                }
+                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);
+        const onProgress = Boolean(flags.json)
+            ? undefined
+            : (event) => {
+                if (event.type === "preflight") {
+                    const report = JSON.parse(event.message);
+                    console.log(`[preflight] provider=${report.provider} model=${report.model} branch=${report.gitBranch} dirty=${report.gitDirtyFiles} disk=${report.diskFreeMb}MB iterations=${report.iterations}`);
+                    console.log(`[preflight] prompt=${report.promptFile}`);
+                    for (const w of report.warnings)
+                        console.log(`[preflight] warning: ${w}`);
+                }
+                else if (event.type === "iteration_start") {
+                    console.log(`\n--- Iteration ${event.iteration}/${event.total} ---`);
+                }
+                else if (event.type === "iteration_end") {
+                    const elapsed = formatDuration(event.durationMs);
+                    console.log(`--- Iteration ${event.iteration} ${event.status} (${elapsed}) ---`);
+                }
+                else if (event.type === "attempt_retry") {
+                    console.log(`[retry] iteration ${event.iteration}, attempt ${event.attempt}/${event.maxAttempts}, backoff ${event.backoffMs}ms`);
+                }
+                else if (event.type === "summary") {
+                    const preview = event.lines.slice(0, 5).join("\n");
+                    console.log(`[summary] iteration ${event.iteration}:\n${preview}${event.lines.length > 5 ? `\n  ... (${event.lines.length - 5} more lines)` : ""}`);
+                }
+                else if (event.type === "sweep_end") {
+                    console.log(`\nSweep complete: ${event.result.succeeded}/${event.result.totalIterations} succeeded in ${formatDuration(event.result.totalDurationMs)}`);
+                }
+            };
+        const result = await sweepPrompt({
+            cwd,
+            promptFile: getStringFlag(flags, "prompt-file"),
+            agent,
+            model: getStringFlag(flags, "model"),
+            iterations: parsePositiveIntFlag(getStringFlag(flags, "iterations"), "iterations"),
+            iterationTimeoutSeconds: parsePositiveIntFlag(getStringFlag(flags, "iteration-timeout"), "iteration-timeout"),
+            maxRetries: parseNonNegativeIntFlag(getStringFlag(flags, "max-retries"), "max-retries"),
+            artifactsDir: getStringFlag(flags, "artifacts-dir"),
+            runId: getStringFlag(flags, "run-id"),
+            approveMcps: !Boolean(flags["no-approve-mcps"]),
+            sandboxMode: getStringFlag(flags, "sandbox"),
+            phase: getStringFlag(flags, "phase"),
+            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)) {
+            console.log(JSON.stringify(result, null, 2));
+            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}`);
+        console.log(`Provider: ${result.provider} | Model: ${result.model}`);
+        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);
+        const project = await client.getProject();
+        const prompts = await client.pullPrompts();
+        if (prompts.length === 0) {
+            console.log("No prompt packs found in the project library. Configure prompts in Prompts Studio first.");
+            console.log(`  Open: https://prompts-gpt.com/studio/projects`);
+            return;
+        }
+        const result = await syncPrompts(prompts, {
+            cwd,
+            outDir: getStringFlag(flags, "out") || DEFAULT_PROMPTS_GPT_OUT_DIR,
+            overwrite: true,
+            agent: getStringFlag(flags, "agent") || "all",
+        });
+        const providers = await detectProviders(cwd);
+        const availableProviders = providers.filter((p) => p.available);
+        let configError = null;
+        const configResult = await initRunConfig({
+            cwd,
+            overwrite: true,
+        }).catch((err) => {
+            configError = err.message;
+            return null;
+        });
+        if (Boolean(flags.json)) {
+            console.log(JSON.stringify({
+                project: { brandName: project.brandName, websiteUrl: project.websiteUrl },
+                synced: { prompts: result.markdown.written.length, agents: result.agents.written.length },
+                providers: availableProviders.map((p) => p.provider),
+                config: configResult ? "created" : "skipped",
+            }, null, 2));
+            return;
+        }
+        console.log(`Loaded configuration from Prompts Studio for: ${project.brandName}`);
+        console.log(`Synced ${result.markdown.written.length} prompt pack(s) to ${result.markdown.outDir}`);
+        console.log(`Synced ${result.agents.written.length} agent file(s): ${result.agents.targets.join(", ")}`);
+        console.log(`Manifest: ${result.manifest.manifestPath}`);
+        if (configResult) {
+            console.log(`Config: ${configResult.configPath}`);
+        }
+        else if (configError) {
+            console.error(`[config] Skipped: ${configError}`);
+        }
+        if (availableProviders.length > 0 && result.manifest.manifest.prompts.length > 0) {
+            const firstFile = result.manifest.manifest.prompts[0]?.file;
+            if (firstFile) {
+                console.log(`\nReady to run:`);
+                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",
@@ -88,13 +801,31 @@ async function runCommand(command, flags) {
             });
         }
         const cwd = getResolvedCwd(flags);
+        const apiUrlFlag = getStringFlag(flags, "api-url");
+        if (apiUrlFlag) {
+            try {
+                const parsed = new URL(apiUrlFlag);
+                if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+                    throw new CliError("--api-url must use https or http.", CLI_EXIT_CODES.validation, { helpCommand: "init" });
+                }
+            }
+            catch (e) {
+                if (e instanceof CliError)
+                    throw e;
+                throw new CliError(`--api-url is not a valid URL: ${apiUrlFlag}`, CLI_EXIT_CODES.validation, { helpCommand: "init" });
+            }
+        }
         const result = await saveLocalCredentials({
             token,
-            apiUrl: getStringFlag(flags, "api-url") || DEFAULT_PROMPTS_GPT_API_URL,
+            apiUrl: apiUrlFlag || DEFAULT_PROMPTS_GPT_API_URL,
             cwd,
         });
         console.log(`Saved Prompts-GPT credentials to ${result.credentialsPath}`);
         console.log("The credentials file is added to .gitignore.");
+        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") {
@@ -114,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,
@@ -145,12 +878,24 @@ 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 agentResult = await writeAgentFiles([prompt], {
+            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,
                 agent: target,
                 overwriteAgentFiles: true,
             });
+            const manifestResult = await writePromptManifest(syncedPrompts, {
+                cwd,
+                outDir: getStringFlag(flags, "out") || DEFAULT_PROMPTS_GPT_OUT_DIR,
+            });
             console.log(`Synced ${agentResult.written.length} agent file(s) for ${agentResult.targets.join(", ")}.`);
+            console.log(`Updated manifest: ${manifestResult.manifestPath}`);
         }
         console.log(`Generated: ${prompt.title}`);
         console.log(`Wrote to ${result.written[0] ?? result.outDir}.`);
@@ -167,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)));
@@ -199,45 +938,58 @@ async function runCommand(command, flags) {
             overwrite: Boolean(flags.overwrite),
             agent: getStringFlag(flags, "agent") || "all",
         });
-        console.log(`Synced ${result.markdown.written.length} Markdown prompt file(s) to ${result.markdown.outDir}.`);
-        console.log(`Synced ${result.agents.written.length} agent integration file(s): ${result.agents.targets.join(", ")}.`);
-        console.log(`Updated manifest: ${result.manifest.manifestPath}`);
+        console.log(`Synced ${result.markdown.written.length} new prompt file(s) to ${result.markdown.outDir}.`);
         if (result.markdown.skipped.length) {
-            console.log(`Skipped ${result.markdown.skipped.length} existing Markdown file(s). Use --overwrite to replace them.`);
+            console.log(`Kept ${result.markdown.skipped.length} existing file(s) unchanged. Use --overwrite to replace.`);
         }
-        return;
-    }
-    if (command === "install-agents") {
-        validateAgentFlag(getStringFlag(flags, "agent"));
-        const parsedLimit = parseLimitFlag(getStringFlag(flags, "limit"));
-        const client = await createClientForCommand(command, flags);
-        const prompts = await client.pullPrompts(buildPullQuery(flags, parsedLimit));
-        if (prompts.length === 0) {
-            console.log("No prompts matched the query, so no agent files were written.");
-            return;
+        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.`);
         }
-        if (Boolean(flags["dry-run"])) {
-            console.log(`[dry-run] Would install agent files for ${prompts.length} prompt(s), target: ${getStringFlag(flags, "agent") || "all"}.`);
-            for (const p of prompts)
-                console.log(`  - ${p.title}`);
-            return;
+        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}`);
+            }
         }
-        const result = await writeAgentFiles(prompts, {
-            cwd: getResolvedCwd(flags),
-            agent: getStringFlag(flags, "agent") || "all",
-            overwriteAgentFiles: true,
-        });
-        console.log(`Synced ${result.written.length} agent integration file(s): ${result.targets.join(", ")}.`);
         return;
     }
     if (command === "project") {
-        const client = await createClientForCommand(command, flags);
+        const clientOptions = await resolveClientOptions(command, flags);
+        const client = new PromptsGptClient(clientOptions);
         const project = await client.getProject();
-        console.log(`${project.brandName} (${project.websiteUrl})`);
+        const apiUrl = clientOptions.apiUrl;
+        if (Boolean(flags.json)) {
+            console.log(JSON.stringify({
+                project,
+                apiUrl,
+            }, null, 2));
+            return;
+        }
+        console.log(`Project: ${project.brandName}`);
+        console.log(`Website: ${project.websiteUrl}`);
+        console.log(`Industry: ${project.industryCategory}`);
+        console.log(`Language: ${project.targetLanguage}`);
+        console.log(`Countries: ${formatList(project.targetCountries)}`);
+        console.log(`Aliases: ${formatList(project.brandAliases)}`);
+        console.log(`Keywords: ${formatList(project.productKeywords)}`);
+        console.log(`Personas: ${formatList(project.targetPersonas)}`);
+        console.log(`Competitors: ${formatCompetitors(project.competitors)}`);
+        console.log(`API URL: ${apiUrl}`);
         return;
     }
 }
 async function createClientForCommand(command, flags) {
+    return new PromptsGptClient(await resolveClientOptions(command, flags));
+}
+async function resolveClientOptions(command, flags) {
     const cwd = getResolvedCwd(flags);
     const explicitToken = await resolveTokenInput(flags, { command });
     const explicitApiUrl = getStringFlag(flags, "api-url");
@@ -248,14 +1000,29 @@ async function createClientForCommand(command, flags) {
         throw new CliError(`Could not read local credentials at ${credentialsPath}. Re-run \`prompts-gpt init --token <project-token>\` to replace the file.`, CLI_EXIT_CODES.auth, { helpCommand: command });
     }
     const token = explicitToken || credentials?.token || "";
+    if (!token && !process.stdin.isTTY) {
+        // CI fallback — never read process.env in the importable SDK, only in the CLI entrypoint
+        const envToken = process.env.PROMPTS_GPT_TOKEN?.trim();
+        if (envToken) {
+            return {
+                token: envToken,
+                apiUrl: explicitApiUrl || credentials?.apiUrl || DEFAULT_PROMPTS_GPT_API_URL,
+                fetch,
+            };
+        }
+    }
     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 new PromptsGptClient({
+    return {
         token,
         apiUrl: explicitApiUrl || credentials?.apiUrl || DEFAULT_PROMPTS_GPT_API_URL,
         fetch,
-    });
+    };
 }
 function buildPullQuery(flags, limit) {
     return {
@@ -330,8 +1097,33 @@ function getCommandOptions(command) {
     if (command === "init") {
         return common;
     }
+    if (command === "setup") {
+        return {
+            help: { type: "boolean" },
+            cwd: { type: "string" },
+            json: { type: "boolean" },
+            overwrite: { type: "boolean" },
+            "prompt-file": { type: "string" },
+            "prompt-dir": { type: "string" },
+            manifest: { type: "string" },
+            "prompt-files": { type: "string" },
+            agent: { type: "string" },
+            "provider-order": { type: "string" },
+            timeout: { type: "string" },
+            "retry-count": { type: "string" },
+            "artifacts-dir": { type: "string" },
+            "allow-destructive-git": { type: "boolean" },
+            "codex-model": { type: "string" },
+            "cursor-model": { type: "string" },
+            "claude-model": { type: "string" },
+            "copilot-model": { type: "string" },
+        };
+    }
     if (command === "project") {
-        return common;
+        return {
+            ...common,
+            json: { type: "boolean" },
+        };
     }
     if (command === "pull") {
         return {
@@ -386,54 +1178,135 @@ function getCommandOptions(command) {
             "dry-run": { type: "boolean" },
         };
     }
-    return {
-        ...common,
-        query: { type: "string" },
-        q: { type: "string" },
-        category: { type: "string" },
-        tool: { type: "string" },
-        "output-type": { type: "string" },
-        limit: { type: "string" },
-        agent: { type: "string" },
-        "dry-run": { type: "boolean" },
-    };
-}
-function normalizeLegacyFlags(argv) {
-    const aliases = new Map([
-        ["agents", "agent"],
-        ["apiUrl", "api-url"],
-        ["desiredOutput", "desired-output"],
-        ["artifactType", "artifact-type"],
-        ["outputType", "output-type"],
-        ["webSearch", "web-search"],
-        ["generatedOnly", "generated-only"],
-        ["syncAgents", "sync-agents"],
-        ["tokenStdin", "token-stdin"],
-        ["tokenPrompt", "token-prompt"],
-        ["dryRun", "dry-run"],
-    ]);
-    return argv.map((arg) => {
-        if (!arg.startsWith("--"))
-            return arg;
-        const eqIndex = arg.indexOf("=");
-        const rawKey = eqIndex === -1 ? arg.slice(2) : arg.slice(2, eqIndex);
-        const mappedKey = aliases.get(rawKey) ?? rawKey;
-        return eqIndex === -1 ? `--${mappedKey}` : `--${mappedKey}=${arg.slice(eqIndex + 1)}`;
+    if (command === "run") {
+        return {
+            help: { type: "boolean" },
+            cwd: { type: "string" },
+            json: { type: "boolean" },
+            "prompt-file": { type: "string", short: "f" },
+            agent: { type: "string" },
+            model: { type: "string" },
+            timeout: { type: "string" },
+            "artifacts-dir": { type: "string" },
+            "run-id": { type: "string" },
+            sandbox: { type: "string" },
+            "no-approve-mcps": { type: "boolean" },
+            background: { type: "boolean" },
+            "permission-mode": { type: "string" },
+            "dry-run": { type: "boolean" },
+        };
+    }
+    if (command === "sweep") {
+        return {
+            help: { type: "boolean" },
+            cwd: { type: "string" },
+            json: { type: "boolean" },
+            "prompt-file": { type: "string", short: "f" },
+            agent: { type: "string" },
+            model: { type: "string" },
+            iterations: { type: "string", short: "n" },
+            "iteration-timeout": { type: "string" },
+            "max-retries": { type: "string" },
+            "artifacts-dir": { type: "string" },
+            "run-id": { type: "string" },
+            sandbox: { type: "string" },
+            "no-approve-mcps": { type: "boolean" },
+            phase: { type: "string" },
+            "dry-run": { type: "boolean" },
+            "max-run-dirs": { type: "string" },
+            "summary-lines": { type: "string" },
+            background: { type: "boolean" },
+            "permission-mode": { type: "string" },
+        };
+    }
+    if (command === "run-batch") {
+        return {
+            help: { type: "boolean" },
+            cwd: { type: "string" },
+            json: { type: "boolean" },
+            manifest: { type: "string" },
+            "prompt-files": { type: "string" },
+            agent: { type: "string" },
+            model: { type: "string" },
+            timeout: { type: "string" },
+            "artifacts-dir": { type: "string" },
+        };
+    }
+    if (command === "load-config") {
+        return {
+            ...common,
+            json: { type: "boolean" },
+            out: { type: "string" },
+            agent: { type: "string" },
+        };
+    }
+    if (command === "quickstart" || command === "list" || command === "status" || command === "validate" || command === "providers" || command === "doctor") {
+        return {
+            help: { type: "boolean" },
+            cwd: { type: "string" },
+            json: { type: "boolean" },
+        };
+    }
+    throw new CliError(`Unsupported command: ${command}.`, CLI_EXIT_CODES.usage, {
+        helpCommand: "help",
     });
 }
 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) {
@@ -446,6 +1319,22 @@ function validateFlagConflicts(command, flags) {
             helpCommand: command,
         });
     }
+    const promptSourceCount = [
+        Boolean(flags["prompt-file"]),
+        Boolean(flags["prompt-files"]),
+        Boolean(flags.manifest),
+        Boolean(flags["prompt-dir"]),
+    ].filter(Boolean).length;
+    if (command === "setup" && promptSourceCount > 1) {
+        throw new CliError("Use only one prompt source for `setup`: `--prompt-file`, `--prompt-files`, `--manifest`, or `--prompt-dir`.", CLI_EXIT_CODES.usage, {
+            helpCommand: command,
+        });
+    }
+    if (command === "run-batch" && Boolean(flags["prompt-files"]) && Boolean(flags.manifest)) {
+        throw new CliError("Use either `--prompt-files` or `--manifest`, not both.", CLI_EXIT_CODES.usage, {
+            helpCommand: command,
+        });
+    }
 }
 async function resolveTokenInput(flags, options) {
     const explicitToken = getStringFlag(flags, "token")?.trim();
@@ -491,26 +1380,48 @@ function readTokenFromPrompt(command) {
     return new Promise((resolve, reject) => {
         const stdin = process.stdin;
         const stdout = process.stdout;
-        let token = "";
+        const buf = Buffer.alloc(MAX_STDIN_TOKEN_LENGTH);
+        let bufLen = 0;
         const cleanup = () => {
             stdin.removeListener("data", onData);
+            process.removeListener("SIGTERM", onSigterm);
+            process.removeListener("SIGINT", onSigint);
             stdin.setRawMode?.(false);
             stdin.pause();
         };
+        const extractAndWipe = () => {
+            const result = buf.toString("utf8", 0, bufLen).trim();
+            buf.fill(0, 0, bufLen);
+            bufLen = 0;
+            return result;
+        };
         const finish = (callback) => {
             stdout.write("\n");
             cleanup();
             callback();
         };
+        const onSigterm = () => {
+            buf.fill(0, 0, bufLen);
+            cleanup();
+            process.exit(130);
+        };
+        const onSigint = () => {
+            buf.fill(0, 0, bufLen);
+            cleanup();
+            process.exit(130);
+        };
+        process.on("SIGTERM", onSigterm);
+        process.on("SIGINT", onSigint);
         const onData = (chunk) => {
             const value = typeof chunk === "string" ? chunk : chunk.toString("utf8");
             for (const char of value) {
                 if (char === "\u0003") {
+                    buf.fill(0, 0, bufLen);
                     finish(() => reject(new CliError("Token entry cancelled.", CLI_EXIT_CODES.general, { helpCommand: command })));
                     return;
                 }
                 if (char === "\r" || char === "\n") {
-                    const trimmed = token.trim();
+                    const trimmed = extractAndWipe();
                     if (!trimmed) {
                         finish(() => reject(new CliError("Project token is required.", CLI_EXIT_CODES.validation, { helpCommand: command })));
                         return;
@@ -519,21 +1430,33 @@ function readTokenFromPrompt(command) {
                     return;
                 }
                 if (char === "\u007f" || char === "\b") {
-                    token = token.slice(0, -1);
+                    if (bufLen > 0) {
+                        bufLen--;
+                        buf[bufLen] = 0;
+                    }
                     continue;
                 }
                 if (char >= " ") {
-                    token += char;
-                    if (token.length > MAX_STDIN_TOKEN_LENGTH) {
+                    const charBytes = Buffer.byteLength(char, "utf8");
+                    if (bufLen + charBytes > MAX_STDIN_TOKEN_LENGTH) {
+                        buf.fill(0, 0, bufLen);
                         finish(() => reject(new CliError("Token input is too long.", CLI_EXIT_CODES.validation, { helpCommand: command })));
                         return;
                     }
+                    buf.write(char, bufLen, "utf8");
+                    bufLen += charBytes;
                 }
             }
         };
         stdout.write("Project token: ");
         stdin.setEncoding("utf8");
-        stdin.setRawMode?.(true);
+        try {
+            stdin.setRawMode?.(true);
+        }
+        catch {
+            reject(new CliError("Cannot enable raw mode for token prompt. Use --token-stdin instead.", CLI_EXIT_CODES.usage, { helpCommand: command }));
+            return;
+        }
         stdin.resume();
         stdin.on("data", onData);
     });
@@ -542,11 +1465,11 @@ function parseLimitFlag(raw) {
     if (raw === undefined)
         return undefined;
     if (!/^\d+$/.test(raw)) {
-        throw new CliError("`--limit` must be a positive integer.", CLI_EXIT_CODES.validation);
+        throw new CliError("`--limit` must be a positive integer between 1 and 100.", CLI_EXIT_CODES.validation);
     }
     const value = Number.parseInt(raw, 10);
-    if (!Number.isSafeInteger(value) || value < 1) {
-        throw new CliError("`--limit` must be a positive integer.", CLI_EXIT_CODES.validation);
+    if (!Number.isSafeInteger(value) || value < 1 || value > 100) {
+        throw new CliError("`--limit` must be a positive integer between 1 and 100.", CLI_EXIT_CODES.validation);
     }
     return value;
 }
@@ -568,6 +1491,18 @@ function validateAgentFlag(agent) {
         throw new CliError(`Invalid --agent target: ${invalid.join(", ")}. Use ${SUPPORTED_AGENT_TARGETS.join(", ")}, or all.`, CLI_EXIT_CODES.validation);
     }
 }
+function validateProviderOrderFlag(values) {
+    if (!values?.length)
+        return;
+    const invalid = values.filter((value) => {
+        const raw = value.trim().toLowerCase();
+        const normalized = normalizeOrchestrationAgent(raw);
+        return !raw || normalized === "router";
+    });
+    if (invalid.length > 0) {
+        throw new CliError(`Invalid --provider-order value: ${invalid.join(", ")}. Use codex, cursor, claude, or copilot.`, CLI_EXIT_CODES.validation);
+    }
+}
 function getResolvedCwd(flags) {
     return path.resolve(getStringFlag(flags, "cwd") || process.cwd());
 }
@@ -575,6 +1510,44 @@ function getStringFlag(flags, name) {
     const value = flags[name];
     return typeof value === "string" ? value : undefined;
 }
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const totalSeconds = Math.round(ms / 1000);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours > 0)
+        return `${hours}h ${minutes}m ${seconds}s`;
+    if (minutes > 0)
+        return `${minutes}m ${seconds}s`;
+    return `${seconds}s`;
+}
+function formatList(values) {
+    if (!Array.isArray(values) || values.length === 0)
+        return "None";
+    return values.join(", ");
+}
+function formatCompetitors(values) {
+    if (!Array.isArray(values) || values.length === 0)
+        return "None";
+    return values.map((competitor) => {
+        const aliases = competitor.aliases?.length ? ` [aliases: ${competitor.aliases.join(", ")}]` : "";
+        return competitor.websiteUrl ? `${competitor.name} (${competitor.websiteUrl})${aliases}` : `${competitor.name}${aliases}`;
+    }).join("; ");
+}
+function mergePromptPacks(prompts) {
+    const deduped = new Map();
+    for (const prompt of prompts) {
+        deduped.set(normalizePromptKey(prompt), prompt);
+    }
+    return [...deduped.values()];
+}
+function normalizePromptKey(prompt) {
+    const raw = String(prompt.slug || prompt.title || "prompt").trim().toLowerCase();
+    const normalized = raw.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return normalized || "prompt";
+}
 function asCommandName(value) {
     if (!value)
         return undefined;
@@ -609,53 +1582,144 @@ Usage:
   prompts-gpt help [command]
   prompts-gpt version
 
-Commands:
-  init            Save a project token in .prompts-gpt/.credentials.json
-  project         Show the current project linked to the token
+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
+  doctor          Validate prerequisites and config
+
+Sync & Generate:
+  sync            Pull prompt packs and sync agent files
   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
-  install-agents  Refresh agent-specific instruction files from pulled prompts
-  version         Show the current CLI version
-  help            Show global or command-specific help
+  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(", ")}
+Providers: ${ORCHESTRATION_AGENT_PROFILES.filter((p) => p !== "router").join(", ")} (or router for auto-select)
+Agent targets: ${SUPPORTED_AGENT_TARGETS.join(", ")}
 `);
 }
+function parsePositiveIntFlag(raw, flagName) {
+    if (raw === undefined)
+        return undefined;
+    const label = flagName ? `--${flagName}` : "Value";
+    if (!/^\d+$/.test(raw)) {
+        throw new CliError(`${label} must be a positive integer, got "${raw}".`, CLI_EXIT_CODES.validation);
+    }
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new CliError(`${label} must be a positive integer, got "${raw}".`, CLI_EXIT_CODES.validation);
+    }
+    return value;
+}
+function parseNonNegativeIntFlag(raw, flagName) {
+    if (raw === undefined)
+        return undefined;
+    const label = flagName ? `--${flagName}` : "Value";
+    if (!/^\d+$/.test(raw)) {
+        throw new CliError(`${label} must be a non-negative integer, got "${raw}".`, CLI_EXIT_CODES.validation);
+    }
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new CliError(`${label} must be a non-negative integer, got "${raw}".`, CLI_EXIT_CODES.validation);
+    }
+    return value;
+}
+function resolveRunAgent(flags, fallback) {
+    const raw = getStringFlag(flags, "agent");
+    if (!raw)
+        return fallback;
+    const normalizedRaw = raw.trim().toLowerCase();
+    const normalized = normalizeOrchestrationAgent(raw);
+    if (normalized === "router" && normalizedRaw !== "router") {
+        const profiles = ORCHESTRATION_AGENT_PROFILES.join(", ");
+        const hint = ORCHESTRATION_AGENT_PROFILES.find((p) => p.startsWith(normalizedRaw.slice(0, 3)));
+        const suggestion = hint ? ` Did you mean "${hint}"?` : "";
+        throw new CliError(`Invalid --agent target: ${raw}. Use ${profiles}.${suggestion}`, CLI_EXIT_CODES.validation);
+    }
+    return normalized;
+}
 function getCommandHelp(command) {
     if (command === "init") {
         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") {
+        return `prompts-gpt setup
+
+Usage:
+  prompts-gpt setup [--prompt-file <path> | --prompt-files <a,b,c> | --manifest <path> | --prompt-dir <path>] [--agent codex|cursor|claude|copilot|router] [--provider-order <a,b,c>] [--timeout <seconds>] [--retry-count <n>] [--artifacts-dir <path>] [--codex-model <name>] [--cursor-model <name>] [--claude-model <name>] [--copilot-model <name>] [--allow-destructive-git] [--overwrite] [--json] [--cwd <path>]
+
+Why use it:
+  Scaffolds a generic local orchestration config so a repo can run prompts through Codex, Cursor, Claude Code, or Copilot with minimal repeated CLI flags.
+
+Options:
+  --prompt-file <path>      Default single prompt file for \`prompts-gpt run\`.
+  --prompt-files <list>     Default batch prompt files for \`prompts-gpt run-batch\`.
+  --manifest <path>         Use this manifest as the batch source. Default: auto-detect .prompts-gpt/manifest.json
+  --prompt-dir <path>       Scan a prompt directory when you do not use .prompts-gpt.
+  --agent <name>            Default orchestration profile. Default: router
+  --provider-order <list>   Comma-separated router order such as codex,cursor,claude,copilot
+  --timeout <seconds>       Default timeout in seconds. Default: 900
+  --retry-count <n>         Retry count for spawn and timeout failures. Default: 0
+  --artifacts-dir <path>    Run artifact directory. Default: .scripts/runs
+  --codex-model <name>      Default model override for codex.
+  --cursor-model <name>     Default model override for cursor.
+  --claude-model <name>     Default model override for claude.
+  --copilot-model <name>    Default model override for copilot.
+  --allow-destructive-git   Write config with destructive git protection disabled.
+  --overwrite               Replace an existing config file.
+  --json                    Print the generated config payload as JSON.
+  --cwd <path>              Project directory.
+  --help                    Show this command help.
 `;
     }
     if (command === "project") {
         return `prompts-gpt project
 
 Usage:
-  prompts-gpt project [--token <project-token> | --token-stdin | --token-prompt] [--api-url <url>] [--cwd <path>]
+  prompts-gpt project [--json] [--token <project-token> | --token-stdin | --token-prompt] [--api-url <url>] [--cwd <path>]
 
 Why use it:
   Verifies that the current local token resolves to the expected Prompts-GPT project before syncing files.
 
 Options:
+  --json                Print the full project payload as JSON.
   --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.
@@ -673,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.
@@ -699,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.
@@ -711,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") {
@@ -729,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.
@@ -754,31 +1840,216 @@ 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 === "install-agents") {
-        return `prompts-gpt install-agents
+    if (command === "run") {
+        return `prompts-gpt run
 
 Usage:
-  prompts-gpt install-agents [--query <text> | --q <text>] [--category <name>] [--tool <name>] [--output-type <name>] [--limit <n>] [--agent <targets>] [--dry-run] [--token <project-token> | --token-stdin | --token-prompt] [--api-url <url>] [--cwd <path>]
+  prompts-gpt run [-f <path>] [--agent <name>] [--model <name>] [--timeout <seconds>] [--dry-run]
 
 Why use it:
-  Refreshes agent-specific instruction files from the current prompt library without rewriting the Markdown prompt directory.
+  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:
-  --query <text>        Search query for the project prompt library.
-  --q <text>            Short alias for --query.
-  --category <name>     Filter prompts by category.
-  --tool <name>         Filter prompts by supported tool.
-  --output-type <name>  Filter prompts by output type.
-  --limit <n>           Positive integer limit for returned prompts.
-  --agent <targets>     Comma-separated agent targets. Default: all
-  --dry-run             Preview what would be installed without writing any files.
-  --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 agent files.
+  -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.
+  --artifacts-dir <path>     Override run artifacts directory.
+  --run-id <id>              Explicit run ID for artifact folder naming.
+  --sandbox <mode>           Codex sandbox mode. Default: workspace-write.
+  --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.
+`;
+    }
+    if (command === "run-batch") {
+        return `prompts-gpt run-batch
+
+Usage:
+  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.
+
+Options:
+  --manifest <path>      Prompt manifest path. Overrides config batch defaults.
+  --prompt-files <list>  Comma-separated prompt files to run.
+  --agent <name>         Orchestration profile. Default from ${DEFAULT_RUN_CONFIG_PATH} or router.
+  --model <name>         Optional model override for all runs.
+  --timeout <seconds>    Execution timeout in seconds per prompt.
+  --artifacts-dir <path> Override run artifacts directory.
+  --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 [-f <path>] [-n <count>] [--agent <name>] [--model <name>] [--dry-run]
+
+Why use it:
+  Runs the same prompt N times, feeding each iteration's summary into the next.
+  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:
+  -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.
+  --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.
+  --artifacts-dir <path>       Override run artifacts directory.
+  --run-id <id>                Explicit run ID for artifact folder naming.
+  --sandbox <mode>             Codex sandbox mode. Default: workspace-write
+  --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
+  --max-run-dirs <n>           Max artifact directories to keep. Default: 20
+  --summary-lines <n>          Lines of summary to extract per iteration. Default: 40
+  --dry-run                    Preview what the sweep would do without executing.
+  --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") {
+        return `prompts-gpt list
+
+Usage:
+  prompts-gpt list [--json] [--cwd <path>]
+
+Why use it:
+  Shows all prompt packs, sweep files, and agent integrations available in the workspace.
+  Gives runnable commands for each entry so you can copy-paste them directly.
+
+Options:
+  --json                Print as JSON.
+  --cwd <path>          Project directory.
+  --help                Show this command help.
+`;
+    }
+    if (command === "status") {
+        return `prompts-gpt status
+
+Usage:
+  prompts-gpt status [--json] [--cwd <path>]
+
+Why use it:
+  Shows workspace readiness at a glance: credentials, config, manifest,
+  prompts, sweeps, agent integrations, and available providers.
+
+Options:
+  --json                Print as JSON.
+  --cwd <path>          Project directory.
+  --help                Show this command help.
+`;
+    }
+    if (command === "validate") {
+        return `prompts-gpt validate
+
+Usage:
+  prompts-gpt validate [--json] [--cwd <path>]
+
+Why use it:
+  Validates the .prompts-gpt/config.json file and reports errors and
+  warnings without running any commands.
+
+Options:
+  --json                Print as JSON.
+  --cwd <path>          Project directory.
+  --help                Show this command help.
+`;
+    }
+    if (command === "providers") {
+        return `prompts-gpt providers
+
+Usage:
+  prompts-gpt providers [--json] [--cwd <path>]
+
+Why use it:
+  Shows provider CLI detection details for codex, cursor, claude, and copilot so you can decide the best router order before running setup.
+`;
+    }
+    if (command === "doctor") {
+        return `prompts-gpt doctor
+
+Usage:
+  prompts-gpt doctor [--json] [--cwd <path>]
+
+Why use it:
+  Checks runtime prerequisites, provider availability, prompt-source readiness, and run config health.
+`;
+    }
+    if (command === "load-config") {
+        return `prompts-gpt load-config
+
+Usage:
+  prompts-gpt load-config [--agent <targets>] [--out <dir>] [--json] [--token <project-token> | --token-stdin | --token-prompt] [--api-url <url>] [--cwd <path>]
+
+Why use it:
+  One command to pull all prompts, agent files, and config from Prompts Studio
+  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
+  --json                  Print machine-readable JSON output.
+  --token <token>         Override saved token.
+  --token-stdin           Read token from stdin.
+  --token-prompt          Prompt for token.
+  --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.
 `;
     }
@@ -801,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);
@@ -821,9 +2127,55 @@ main().catch((error) => {
                     : CLI_EXIT_CODES.general;
         return;
     }
-    console.error(error instanceof Error ? error.message : String(error));
+    const msg = error instanceof Error ? error.message : String(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}`);
+    }
+}
 function formatApiError(error) {
     const lines = [error.message];
     for (const [field, messages] of Object.entries(error.fieldErrors ?? {})) {
@@ -839,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