@prompts-gpt/client 0.2.2 → 0.2.3

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 { DEFAULT_PROMPTS_GPT_API_URL, DEFAULT_PROMPTS_GPT_OUT_DIR, DEFAULT_RUN_CONFIG_PATH, PROMPTS_GPT_CREDENTIALS_FILE, PromptsGptApiError, PromptsGptClient, doctor, initRunConfig, loadRunConfig, normalizeOrchestrationAgent, ORCHESTRATION_AGENT_PROFILES, runBatch, runPrompt, sweepPrompt, validateRunConfig, discoverWorkspaceAssets, SUPPORTED_AGENT_TARGETS, detectProviders, loadLocalCredentials, saveLocalCredentials, syncPrompts, writeAgentFiles, writePromptManifest, writePromptMarkdownFiles, } from "./index.js";
 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", "version", "help"];
 const MAX_STDIN_TOKEN_LENGTH = 4_096;
 class CliError extends Error {
     exitCode;
@@ -28,10 +28,14 @@ async function main() {
     const argv = process.argv.slice(2);
     if (argv.length === 0) {
         printHelp();
+        console.log("Quick start:");
+        console.log("  prompts-gpt status      — check workspace readiness");
+        console.log("  prompts-gpt list        — see available prompts, sweeps, agents");
+        console.log("  prompts-gpt help <cmd>  — detailed help for a command");
+        console.log("");
         return;
     }
-    const normalizedArgv = normalizeLegacyFlags(argv);
-    const first = normalizedArgv[0];
+    const first = argv[0];
     if (first === "--help") {
         printHelp();
         return;
@@ -41,11 +45,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 +66,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,6 +74,466 @@ 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) {
+            console.log(`${provider.provider}: ${provider.available ? "available" : "missing"} | bin=${provider.bin} | model=${provider.modelDefault}${provider.version ? ` | version=${provider.version}` : ""}`);
+        }
+        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(`Default agent: ${result.config.defaultAgent ?? "router"}`);
+        console.log(`Provider order: ${(result.config.providerOrder ?? []).join(", ")}`);
+        if (result.sourceSummary.defaultPromptFile) {
+            console.log(`Default prompt file: ${result.sourceSummary.defaultPromptFile}`);
+        }
+        if (result.sourceSummary.manifestPath) {
+            console.log(`Batch default manifest: ${result.sourceSummary.manifestPath}`);
+        }
+        else if (result.sourceSummary.promptFiles.length > 0) {
+            console.log(`Batch default prompt files: ${result.sourceSummary.promptFiles.length}`);
+        }
+        else {
+            console.log("Batch default prompt sources: none detected");
+        }
+        console.log("Detected providers:");
+        for (const provider of result.providerSummary) {
+            console.log(`- ${provider.provider}: ${provider.available ? "available" : "missing"} | bin=${provider.bin}`);
+        }
+        console.log("Next steps:");
+        console.log(`  prompts-gpt run${result.sourceSummary.defaultPromptFile ? "" : " --prompt-file <path>"}`);
+        console.log("  prompts-gpt run-batch");
+        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("");
+        if (assets.prompts.length > 0) {
+            console.log(`Prompt packs (${assets.prompts.length}):`);
+            for (const p of assets.prompts) {
+                console.log(`  ${p.slug} — ${p.title} [${p.source}]`);
+                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) {
+                console.log(`  ${s.name}`);
+                console.log(`    file:  ${s.file}`);
+                console.log(`    sweep: prompts-gpt sweep --prompt-file ${s.file}`);
+            }
+            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\`"}`);
+        console.log(`  Prompts:      ${assets.prompts.length > 0 ? `✓ (${assets.prompts.length})` : "✗ — none found"}`);
+        console.log(`  Sweeps:       ${assets.sweeps.length > 0 ? `✓ (${assets.sweeps.length})` : "— none found"}`);
+        console.log(`  Agents:       ${assets.agents.length > 0 ? `✓ (${assets.agents.length} targets)` : "✗ — run \`prompts-gpt sync\`"}`);
+        console.log(`  Providers:    ${availableProviders.length > 0 ? `✓ (${availableProviders.map((p) => p.provider).join(", ")})` : "✗ — no CLI found"}`);
+        console.log("");
+        if (assets.prompts.length > 0 && availableProviders.length > 0) {
+            console.log("Ready to run:");
+            console.log(`  prompts-gpt run --prompt-file .prompts-gpt/${assets.prompts[0].file}`);
+            if (assets.sweeps.length > 0) {
+                console.log(`  prompts-gpt sweep --prompt-file ${assets.sweeps[0].file}`);
+            }
+        }
+        else {
+            console.log("Next steps:");
+            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 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:");
+                        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);
+        const result = await runPrompt({
+            cwd,
+            promptFile,
+            agent,
+            model: getStringFlag(flags, "model"),
+            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-selected)`;
+        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)}`);
+        console.log(`Run dir: ${result.runDir}`);
+        console.log(`Summary: ${result.summaryFile}`);
+        console.log(`Log: ${result.logFile}`);
+        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}`);
+        for (const [idx, run] of result.results.entries()) {
+            const status = run.exitCode === 0 ? "ok" : "FAIL";
+            console.log(`  [${idx + 1}/${result.total}] ${status} ${path.basename(run.promptFile)} -> ${run.provider} (exit=${run.exitCode}, ${formatDuration(run.durationMs)})`);
+        }
+        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)) {
+            if (!config.defaultPromptFile) {
+                const assets = await discoverWorkspaceAssets(cwd);
+                if (assets.sweeps.length > 0) {
+                    console.log("No default prompt file configured. Available sweep prompts:\n");
+                    for (const s of assets.sweeps) {
+                        console.log(`  prompts-gpt sweep --prompt-file ${s.file}`);
+                    }
+                    if (assets.prompts.length > 0) {
+                        console.log("\nOr run a prompt pack instead:");
+                        for (const p of assets.prompts.slice(0, 3)) {
+                            console.log(`  prompts-gpt run --prompt-file .prompts-gpt/${p.file}`);
+                        }
+                    }
+                    console.log("\nOr set a default: prompts-gpt setup --prompt-file <path>");
+                    return;
+                }
+            }
+        }
+        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"),
+            onProgress,
+        });
+        if (Boolean(flags.json)) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        if (result.dryRun) {
+            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}`);
+            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)}`);
+        console.log(`Run dir: ${result.runDir}`);
+        console.log(`Manifest: ${result.manifestFile}`);
+        if (result.failed > 0) {
+            process.exitCode = 1;
+        }
+        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}`);
+            }
+        }
+        return;
+    }
     if (command === "init") {
         const token = await resolveTokenInput(flags, { command });
         if (!token) {
@@ -88,13 +552,28 @@ 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("Next: prompts-gpt sync");
         return;
     }
     if (command === "pull") {
@@ -145,12 +624,19 @@ 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(() => []);
+            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}.`);
@@ -199,45 +685,43 @@ 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.`);
-        }
-        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;
-        }
-        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;
+            console.log(`Kept ${result.markdown.skipped.length} existing file(s) unchanged. Use --overwrite to replace.`);
         }
-        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(", ")}.`);
+        console.log(`Synced ${result.agents.written.length} agent file(s): ${result.agents.targets.join(", ")}.`);
+        console.log(`Manifest: ${result.manifest.manifestPath}`);
         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 +732,25 @@ 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 });
     }
-    return new PromptsGptClient({
+    return {
         token,
         apiUrl: explicitApiUrl || credentials?.apiUrl || DEFAULT_PROMPTS_GPT_API_URL,
         fetch,
-    });
+    };
 }
 function buildPullQuery(flags, limit) {
     return {
@@ -330,8 +825,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,39 +906,76 @@ 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" },
+            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" },
+        };
+    }
+    if (command === "sweep") {
+        return {
+            help: { type: "boolean" },
+            cwd: { type: "string" },
+            json: { type: "boolean" },
+            "prompt-file": { type: "string" },
+            agent: { type: "string" },
+            model: { type: "string" },
+            iterations: { type: "string" },
+            "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 === "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) {
@@ -446,6 +1003,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 +1064,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 +1114,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 +1149,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 +1175,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 +1194,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;
@@ -611,11 +1268,20 @@ Usage:
 
 Commands:
   init            Save a project token in .prompts-gpt/.credentials.json
-  project         Show the current project linked to the token
+  setup           Scaffold .prompts-gpt/config.json for local orchestration
+  load-config     Pull configuration and prompts directly from Prompts Studio
   pull            Download prompt packs as Markdown files
   generate        Generate one prompt pack from a goal
   sync            Generate and/or pull prompt packs, then sync agent files
-  install-agents  Refresh agent-specific instruction files from pulled prompts
+  list            Show available prompts, sweeps, and agent integrations
+  status          Show workspace readiness and next steps
+  validate        Validate .prompts-gpt/config.json and report issues
+  run             Execute a prompt file with local agent orchestration
+  run-batch       Execute multiple prompt files from config, manifest, or list
+  sweep           Multi-iteration prompt execution with progress and summaries
+  providers       Show detected local provider CLIs
+  doctor          Validate local run prerequisites and config
+  project         Show the current project linked to the token
   version         Show the current CLI version
   help            Show global or command-specific help
 
@@ -625,8 +1291,49 @@ Global options:
 
 Supported tools: ${VALID_TOOLS.join(", ")}
 Supported agent targets: ${SUPPORTED_AGENT_TARGETS.join(", ")}
+Run agent profiles: ${ORCHESTRATION_AGENT_PROFILES.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
@@ -644,18 +1351,49 @@ Options:
   --api-url <url>       Custom API base URL for self-hosted instances.
   --cwd <path>          Target project directory that will receive .prompts-gpt/.credentials.json.
   --help                Show this command help.
+`;
+    }
+    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.
@@ -756,30 +1494,175 @@ Options:
   --help                   Show this command help.
 `;
     }
-    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 [--prompt-file <path>] [--agent codex|cursor|claude|copilot|router] [--model <name>] [--timeout <seconds>] [--artifacts-dir <path>] [--run-id <id>] [--sandbox <mode>] [--no-approve-mcps] [--background] [--permission-mode <mode>] [--json] [--cwd <path>]
 
 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, the command uses the configured default prompt.
 
 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.
+  --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.
+  --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 codex|cursor|claude|copilot|router] [--model <name>] [--timeout <seconds>] [--artifacts-dir <path>] [--json] [--cwd <path>]
+
+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.
+`;
+    }
+    if (command === "sweep") {
+        return `prompts-gpt sweep
+
+Usage:
+  prompts-gpt sweep [--prompt-file <path>] [--agent codex|cursor|claude|copilot|router] [--model <name>] [--iterations <n>] [--iteration-timeout <seconds>] [--max-retries <n>] [--phase <name>] [--artifacts-dir <path>] [--run-id <id>] [--sandbox <mode>] [--no-approve-mcps] [--background] [--permission-mode <mode>] [--max-run-dirs <n>] [--summary-lines <n>] [--dry-run] [--json] [--cwd <path>]
+
+Why use it:
+  Replaces the bash sweep scripts with a generic multi-iteration execution engine.
+  Runs the same prompt N times, feeding each iteration's summary into the next.
+  Includes pre-flight checks, safety guards, SIGTERM handling, progress monitoring,
+  and a structured sweep manifest.
+
+Options:
+  --prompt-file <path>         Prompt file to sweep. Reads from config if omitted.
+  --agent <name>               Orchestration profile. Default from config or router.
+  --model <name>               Model override for the selected provider.
+  --iterations <n>             Number of sweep iterations. Default: 1
+  --iteration-timeout <secs>   Timeout per iteration in seconds. Default: 5400 (90 min)
+  --max-retries <n>            Max retries per iteration on spawn/timeout. Default: 2
+  --phase <name>               Optional phase label injected into the prompt.
+  --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.
+`;
+    }
+    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.
+
+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 === "version") {
@@ -821,9 +1704,15 @@ 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;
 });
+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 ?? {})) {