@prompts-gpt/client 0.2.0 → 0.2.3

package/dist/cli.js

@@ -1,186 +1,1248 @@
 #!/usr/bin/env node
-import { DEFAULT_PROMPTS_GPT_API_URL, DEFAULT_PROMPTS_GPT_OUT_DIR, PromptsGptApiError, PromptsGptClient, SUPPORTED_AGENT_TARGETS, loadLocalCredentials, saveLocalCredentials, syncPrompts, writeAgentFiles, writePromptMarkdownFiles, } from "./index.js";
-const CLI_EXIT_CODES = { success: 0, general: 1, auth: 2, validation: 3 };
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { DEFAULT_PROMPTS_GPT_API_URL, DEFAULT_PROMPTS_GPT_OUT_DIR, DEFAULT_RUN_CONFIG_PATH, PROMPTS_GPT_CREDENTIALS_FILE, PromptsGptApiError, PromptsGptClient, doctor, initRunConfig, loadRunConfig, normalizeOrchestrationAgent, ORCHESTRATION_AGENT_PROFILES, runBatch, runPrompt, sweepPrompt, validateRunConfig, discoverWorkspaceAssets, SUPPORTED_AGENT_TARGETS, detectProviders, loadLocalCredentials, saveLocalCredentials, syncPrompts, writeAgentFiles, writePromptManifest, writePromptMarkdownFiles, } from "./index.js";
+const CLI_EXIT_CODES = {
+    success: 0,
+    general: 1,
+    auth: 2,
+    validation: 3,
+    rateLimit: 4,
+    usage: 64,
+};
 const VALID_TOOLS = ["Codex", "Claude Code", "Cursor", "GitHub Copilot", "ChatGPT", "Gemini", "Perplexity", "Grok", "DeepSeek", "Claude"];
+const COMMANDS = ["setup", "init", "project", "pull", "generate", "sync", "run", "run-batch", "sweep", "list", "status", "validate", "providers", "doctor", "load-config", "version", "help"];
+const MAX_STDIN_TOKEN_LENGTH = 4_096;
+class CliError extends Error {
+    exitCode;
+    helpCommand;
+    constructor(message, exitCode, options) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+        this.helpCommand = options?.helpCommand;
+    }
+}
 async function main() {
-    const [command, ...args] = process.argv.slice(2);
-    const flags = parseFlags(args);
-    if (!command || command === "help" || flags.help) {
+    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 first = argv[0];
+    if (first === "--help") {
         printHelp();
         return;
     }
-    if (command === "version" || command === "--version" || flags.version) {
-        const version = await getCliVersion();
-        console.log(`@prompts-gpt/client v${version}`);
+    if (first === "--version") {
+        await printVersion();
+        return;
+    }
+    if (first === "help") {
+        handleHelpCommand(argv.slice(1));
+        return;
+    }
+    if (first === "version") {
+        if (argv.length > 1) {
+            throw new CliError("The `version` command does not accept additional arguments.", CLI_EXIT_CODES.usage, {
+                helpCommand: "version",
+            });
+        }
+        await printVersion();
+        return;
+    }
+    const command = asCommandName(first);
+    if (!command) {
+        throw new CliError(`Unknown command: ${first}.`, CLI_EXIT_CODES.usage);
+    }
+    if (!isRunnableCommand(command)) {
+        throw new CliError(`Unknown command: ${first}.`, CLI_EXIT_CODES.usage, {
+            helpCommand: "help",
+        });
+    }
+    const flags = parseCommandFlags(command, argv.slice(1));
+    if (Boolean(flags.help)) {
+        printHelp(command);
+        return;
+    }
+    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 = flags.token;
-        if (!token)
-            throw new Error("Run `prompts-gpt init --token <project-token>`.");
-        if (typeof token !== "string" || token.length > 256)
-            throw new Error("Token value is invalid or too long.");
-        if (!token.startsWith("pgpt_"))
-            throw new Error("Token must start with 'pgpt_'. Copy the full token from the Prompts-GPT dashboard.");
+        const token = await resolveTokenInput(flags, { command });
+        if (!token) {
+            throw new CliError("Run `prompts-gpt init --token <project-token>`, `--token-stdin`, or `--token-prompt`.", CLI_EXIT_CODES.validation, {
+                helpCommand: "init",
+            });
+        }
+        if (token.length > 256) {
+            throw new CliError("Token value is invalid or too long.", CLI_EXIT_CODES.validation, {
+                helpCommand: "init",
+            });
+        }
+        if (!token.startsWith("pgpt_")) {
+            throw new CliError("Token must start with `pgpt_`. Copy the full token from the Prompts-GPT dashboard.", CLI_EXIT_CODES.validation, {
+                helpCommand: "init",
+            });
+        }
+        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: flags.apiUrl || DEFAULT_PROMPTS_GPT_API_URL,
-            cwd: flags.cwd || process.cwd(),
+            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.");
-        return;
-    }
-    const cwd = flags.cwd || process.cwd();
-    const credentials = await loadLocalCredentials(cwd);
-    const client = new PromptsGptClient({
-        token: flags.token || credentials?.token || "",
-        apiUrl: flags.apiUrl || credentials?.apiUrl || DEFAULT_PROMPTS_GPT_API_URL,
-        fetch,
-    });
-    if (command === "project") {
-        const project = await client.getProject();
-        console.log(`${project.brandName} (${project.websiteUrl})`);
+        console.log("Next: prompts-gpt sync");
         return;
     }
     if (command === "pull") {
-        const prompts = await client.pullPrompts(buildPullQuery(flags));
+        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. Try different filters or check the project prompt library.");
             return;
         }
         const result = await writePromptMarkdownFiles(prompts, {
-            cwd,
-            outDir: flags.out || DEFAULT_PROMPTS_GPT_OUT_DIR,
+            cwd: getResolvedCwd(flags),
+            outDir: getStringFlag(flags, "out") || DEFAULT_PROMPTS_GPT_OUT_DIR,
             overwrite: Boolean(flags.overwrite),
         });
         console.log(`Wrote ${result.written.length} prompt file(s) to ${result.outDir}.`);
-        if (result.skipped.length)
+        if (result.skipped.length) {
             console.log(`Skipped ${result.skipped.length} existing file(s). Use --overwrite to replace them.`);
+        }
         return;
     }
     if (command === "generate") {
-        validateToolFlag(flags.tool);
-        const prompt = await generatePromptFromFlags(client, flags);
+        validateToolFlag(getStringFlag(flags, "tool"));
+        const goal = getStringFlag(flags, "goal");
+        if (!goal) {
+            throw new CliError("Prompt generation requires `--goal`.", CLI_EXIT_CODES.validation, {
+                helpCommand: "generate",
+            });
+        }
+        validateAgentFlag(getStringFlag(flags, "agent"));
+        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 cwd = getResolvedCwd(flags);
         const result = await writePromptMarkdownFiles([prompt], {
             cwd,
-            outDir: flags.out || DEFAULT_PROMPTS_GPT_OUT_DIR,
+            outDir: getStringFlag(flags, "out") || DEFAULT_PROMPTS_GPT_OUT_DIR,
             overwrite: Boolean(flags.overwrite),
         });
-        const agentFlag = (flags.agent || flags.agents || flags.syncAgents);
-        if (agentFlag) {
-            const agentResult = await writeAgentFiles([prompt], {
+        const shouldSyncAgents = Boolean(flags["sync-agents"]) || typeof getStringFlag(flags, "agent") === "string";
+        if (shouldSyncAgents) {
+            const target = getStringFlag(flags, "agent") || "all";
+            const pulled = await client.pullPrompts().catch(() => []);
+            const syncedPrompts = mergePromptPacks([prompt, ...pulled]);
+            const agentResult = await writeAgentFiles(syncedPrompts, {
                 cwd,
-                agent: typeof agentFlag === "string" ? agentFlag : "all",
+                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}.`);
-        if (result.skipped.length)
+        if (result.skipped.length) {
             console.log("Skipped existing generated prompt. Use --overwrite to replace it.");
+        }
         return;
     }
     if (command === "sync") {
-        validateToolFlag(flags.tool);
+        validateToolFlag(getStringFlag(flags, "tool"));
+        validateAgentFlag(getStringFlag(flags, "agent"));
+        const parsedLimit = parseLimitFlag(getStringFlag(flags, "limit"));
         const prompts = [];
-        if (flags.goal) {
-            prompts.push(await generatePromptFromFlags(client, flags));
+        const goal = getStringFlag(flags, "goal");
+        const generatedOnly = Boolean(flags["generated-only"]);
+        const client = await createClientForCommand(command, flags);
+        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"]),
+            }));
         }
-        if (!flags.generatedOnly) {
-            prompts.push(...await client.pullPrompts(buildPullQuery(flags)));
+        if (!generatedOnly) {
+            prompts.push(...await client.pullPrompts(buildPullQuery(flags, parsedLimit)));
+        }
+        if (prompts.length === 0) {
+            throw new CliError("No prompts to sync. Provide `--goal` or remove `--generated-only`.", CLI_EXIT_CODES.validation, {
+                helpCommand: "sync",
+            });
+        }
+        if (Boolean(flags["dry-run"])) {
+            console.log(`[dry-run] Would sync ${prompts.length} prompt(s) for agent target: ${getStringFlag(flags, "agent") || "all"}.`);
+            for (const p of prompts)
+                console.log(`  - ${p.title} (${p.source})`);
+            return;
         }
-        if (prompts.length === 0)
-            throw new Error("No prompts to sync. Provide --goal or remove --generated-only.");
         const result = await syncPrompts(prompts, {
-            cwd,
-            outDir: flags.out || DEFAULT_PROMPTS_GPT_OUT_DIR,
+            cwd: getResolvedCwd(flags),
+            outDir: getStringFlag(flags, "out") || DEFAULT_PROMPTS_GPT_OUT_DIR,
             overwrite: Boolean(flags.overwrite),
-            agent: flags.agent || flags.agents || "all",
+            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}`);
-        if (result.markdown.skipped.length)
-            console.log(`Skipped ${result.markdown.skipped.length} existing Markdown file(s). Use --overwrite to replace them.`);
+        console.log(`Synced ${result.markdown.written.length} new prompt file(s) to ${result.markdown.outDir}.`);
+        if (result.markdown.skipped.length) {
+            console.log(`Kept ${result.markdown.skipped.length} existing file(s) unchanged. Use --overwrite to replace.`);
+        }
+        console.log(`Synced ${result.agents.written.length} agent file(s): ${result.agents.targets.join(", ")}.`);
+        console.log(`Manifest: ${result.manifest.manifestPath}`);
         return;
     }
-    if (command === "install-agents") {
-        const prompts = await client.pullPrompts(buildPullQuery(flags));
-        const result = await writeAgentFiles(prompts, {
-            cwd,
-            agent: flags.agent || flags.agents || "all",
-            overwriteAgentFiles: true,
-        });
-        console.log(`Synced ${result.written.length} agent integration file(s): ${result.targets.join(", ")}.`);
+    if (command === "project") {
+        const clientOptions = await resolveClientOptions(command, flags);
+        const client = new PromptsGptClient(clientOptions);
+        const project = await client.getProject();
+        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;
     }
-    throw new Error(`Unknown command: ${command}. Run \`prompts-gpt help\` for usage.`);
 }
-function buildPullQuery(flags) {
+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");
+    const credentialsPath = path.resolve(cwd, DEFAULT_PROMPTS_GPT_OUT_DIR, PROMPTS_GPT_CREDENTIALS_FILE);
+    const hasCredentialsFile = existsSync(credentialsPath);
+    const credentials = await loadLocalCredentials(cwd);
+    if (hasCredentialsFile && !credentials && !explicitToken) {
+        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 {
-        q: (flags.query || flags.q),
-        category: flags.category,
-        tool: flags.tool,
-        outputType: flags.outputType,
-        limit: flags.limit,
+        token,
+        apiUrl: explicitApiUrl || credentials?.apiUrl || DEFAULT_PROMPTS_GPT_API_URL,
+        fetch,
+    };
+}
+function buildPullQuery(flags, limit) {
+    return {
+        q: getStringFlag(flags, "query") || getStringFlag(flags, "q"),
+        category: getStringFlag(flags, "category"),
+        tool: getStringFlag(flags, "tool"),
+        outputType: getStringFlag(flags, "output-type"),
+        limit,
+    };
+}
+function parseCommandFlags(command, argv) {
+    const options = getCommandOptions(command);
+    try {
+        const result = parseArgs({
+            args: argv,
+            options,
+            allowPositionals: false,
+            strict: true,
+        });
+        const values = result.values;
+        validateFlagConflicts(command, values);
+        return values;
+    }
+    catch (error) {
+        throw toCliParseError(error, command);
+    }
+}
+function handleHelpCommand(argv) {
+    try {
+        const { positionals, values } = parseArgs({
+            args: argv,
+            options: { help: { type: "boolean" } },
+            allowPositionals: true,
+            strict: true,
+        });
+        if (values.help) {
+            printHelp();
+            return;
+        }
+        if (positionals.length > 1) {
+            throw new CliError("The `help` command accepts at most one command name.", CLI_EXIT_CODES.usage, {
+                helpCommand: "help",
+            });
+        }
+        if (positionals.length === 0) {
+            printHelp();
+            return;
+        }
+        const topic = asCommandName(positionals[0]);
+        if (!topic) {
+            throw new CliError(`Unknown help topic: ${positionals[0]}.`, CLI_EXIT_CODES.usage, {
+                helpCommand: "help",
+            });
+        }
+        printHelp(topic);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw toCliParseError(error, "help");
+    }
+}
+function getCommandOptions(command) {
+    const common = {
+        help: { type: "boolean" },
+        token: { type: "string" },
+        "token-stdin": { type: "boolean" },
+        "token-prompt": { type: "boolean" },
+        "api-url": { type: "string" },
+        cwd: { type: "string" },
     };
+    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,
+            json: { type: "boolean" },
+        };
+    }
+    if (command === "pull") {
+        return {
+            ...common,
+            query: { type: "string" },
+            q: { type: "string" },
+            category: { type: "string" },
+            tool: { type: "string" },
+            "output-type": { type: "string" },
+            limit: { type: "string" },
+            out: { type: "string" },
+            overwrite: { type: "boolean" },
+        };
+    }
+    if (command === "generate") {
+        return {
+            ...common,
+            goal: { type: "string" },
+            context: { type: "string" },
+            constraints: { type: "string" },
+            "desired-output": { type: "string" },
+            tool: { type: "string" },
+            mode: { type: "string" },
+            "artifact-type": { type: "string" },
+            "web-search": { type: "boolean" },
+            out: { type: "string" },
+            overwrite: { type: "boolean" },
+            agent: { type: "string" },
+            "sync-agents": { type: "boolean" },
+        };
+    }
+    if (command === "sync") {
+        return {
+            ...common,
+            goal: { type: "string" },
+            context: { type: "string" },
+            constraints: { type: "string" },
+            "desired-output": { type: "string" },
+            tool: { type: "string" },
+            mode: { type: "string" },
+            "artifact-type": { type: "string" },
+            "web-search": { type: "boolean" },
+            query: { type: "string" },
+            q: { type: "string" },
+            category: { type: "string" },
+            "output-type": { type: "string" },
+            limit: { type: "string" },
+            out: { type: "string" },
+            overwrite: { type: "boolean" },
+            agent: { type: "string" },
+            "generated-only": { type: "boolean" },
+            "dry-run": { type: "boolean" },
+        };
+    }
+    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) {
+    const message = normalizeParseErrorMessage(error instanceof Error ? error.message : String(error));
+    return new CliError(message, CLI_EXIT_CODES.usage, {
+        helpCommand: command,
+    });
+}
+function normalizeParseErrorMessage(message) {
+    const trimmed = message.trim();
+    if (trimmed.startsWith("Unknown option")) {
+        return `${trimmed}.`;
+    }
+    return trimmed;
+}
+function validateFlagConflicts(command, flags) {
+    const tokenSourceCount = [Boolean(flags.token), Boolean(flags["token-stdin"]), Boolean(flags["token-prompt"])].filter(Boolean).length;
+    if (tokenSourceCount > 1) {
+        throw new CliError("Use only one token source: `--token`, `--token-stdin`, or `--token-prompt`.", CLI_EXIT_CODES.usage, {
+            helpCommand: command,
+        });
+    }
+    if (flags.query && flags.q) {
+        throw new CliError("Use either `--query` or `--q`, not both.", CLI_EXIT_CODES.usage, {
+            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();
+    if (explicitToken) {
+        return explicitToken;
+    }
+    if (flags["token-stdin"]) {
+        const token = await readTokenFromStdin();
+        if (!token) {
+            throw new CliError("No token was received on stdin. Pipe a project token into `--token-stdin`.", CLI_EXIT_CODES.validation, {
+                helpCommand: options.command,
+            });
+        }
+        return token;
+    }
+    if (flags["token-prompt"]) {
+        return readTokenFromPrompt(options.command);
+    }
+    return undefined;
+}
+async function readTokenFromStdin() {
+    if (process.stdin.isTTY) {
+        throw new CliError("`--token-stdin` expects piped input. Use `--token-prompt` for an interactive terminal.", CLI_EXIT_CODES.usage);
+    }
+    const chunks = [];
+    let totalLength = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        totalLength += buffer.length;
+        if (totalLength > MAX_STDIN_TOKEN_LENGTH) {
+            throw new CliError("Token input from stdin is too long.", CLI_EXIT_CODES.validation);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString("utf8").trim();
+}
+function readTokenFromPrompt(command) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new CliError("`--token-prompt` requires an interactive terminal. Use `--token-stdin` for CI or piped input.", CLI_EXIT_CODES.usage, {
+            helpCommand: command,
+        });
+    }
+    return new Promise((resolve, reject) => {
+        const stdin = process.stdin;
+        const stdout = process.stdout;
+        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 = extractAndWipe();
+                    if (!trimmed) {
+                        finish(() => reject(new CliError("Project token is required.", CLI_EXIT_CODES.validation, { helpCommand: command })));
+                        return;
+                    }
+                    finish(() => resolve(trimmed));
+                    return;
+                }
+                if (char === "\u007f" || char === "\b") {
+                    if (bufLen > 0) {
+                        bufLen--;
+                        buf[bufLen] = 0;
+                    }
+                    continue;
+                }
+                if (char >= " ") {
+                    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");
+        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);
+    });
+}
+function parseLimitFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw)) {
+        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 || value > 100) {
+        throw new CliError("`--limit` must be a positive integer between 1 and 100.", CLI_EXIT_CODES.validation);
+    }
+    return value;
 }
 function validateToolFlag(tool) {
     if (!tool)
         return;
     const validSet = new Set(VALID_TOOLS);
     if (!validSet.has(tool)) {
-        throw new Error(`Invalid --tool "${tool}". Valid tools: ${VALID_TOOLS.join(", ")}.`);
-    }
-}
-async function generatePromptFromFlags(client, flags) {
-    const goal = flags.goal;
-    if (!goal)
-        throw new Error("Prompt generation requires --goal.");
-    return client.generatePrompt({
-        goal,
-        context: flags.context || "",
-        constraints: flags.constraints || "",
-        desiredOutput: flags.desiredOutput || "A reusable prompt pack saved as Markdown.",
-        tool: flags.tool || "Codex",
-        mode: flags.mode || "implement",
-        artifactType: flags.artifactType || "prompt-file",
-        includeWebSearch: Boolean(flags.webSearch),
+        throw new CliError(`Invalid --tool "${tool}". Valid tools: ${VALID_TOOLS.join(", ")}.`, CLI_EXIT_CODES.validation);
+    }
+}
+function validateAgentFlag(agent) {
+    if (!agent)
+        return;
+    const targets = agent.split(",").map((item) => item.trim().toLowerCase()).filter(Boolean);
+    const validSet = new Set([...SUPPORTED_AGENT_TARGETS, "all"]);
+    const invalid = [...new Set(targets.filter((target) => !validSet.has(target)))];
+    if (invalid.length) {
+        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);
+    }
 }
-const MAX_FLAG_VALUE_LENGTH = 2000;
-function parseFlags(args) {
-    const flags = {};
-    for (let index = 0; index < args.length; index += 1) {
-        const arg = args[index];
-        if (!arg.startsWith("--"))
-            continue;
-        const eqIndex = arg.indexOf("=");
-        if (eqIndex !== -1) {
-            const key = normalizeFlag(arg.slice(2, eqIndex));
-            if (!key || key.length > 64)
-                continue;
-            flags[key] = arg.slice(eqIndex + 1).slice(0, MAX_FLAG_VALUE_LENGTH);
-            continue;
-        }
-        const key = normalizeFlag(arg.slice(2));
-        if (!key || key.length > 64)
-            continue;
-        const next = args[index + 1];
-        if (!next || next.startsWith("--")) {
-            flags[key] = true;
-        }
-        else {
-            flags[key] = String(next).slice(0, MAX_FLAG_VALUE_LENGTH);
-            index += 1;
-        }
+function getResolvedCwd(flags) {
+    return path.resolve(getStringFlag(flags, "cwd") || process.cwd());
+}
+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 flags;
+    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 normalizeFlag(raw) {
-    return raw.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+function asCommandName(value) {
+    if (!value)
+        return undefined;
+    return COMMANDS.find((command) => command === value);
+}
+function isRunnableCommand(command) {
+    return command !== "help" && command !== "version";
+}
+async function printVersion() {
+    const version = await getCliVersion();
+    console.log(`@prompts-gpt/client v${version}`);
 }
 async function getCliVersion() {
     try {
@@ -192,47 +1254,478 @@ async function getCliVersion() {
         return "0.0.0";
     }
 }
-function printHelp() {
+function printHelp(command) {
+    if (command) {
+        console.log(getCommandHelp(command));
+        return;
+    }
     console.log(`Prompts-GPT CLI
 
-Commands:
-  prompts-gpt init --token <token> [--api-url https://prompts-gpt.com] [--cwd /path/to/repo]
+Usage:
+  prompts-gpt <command> [options]
+  prompts-gpt help [command]
   prompts-gpt version
-  prompts-gpt project
-  prompts-gpt pull [--query "repo audit"] [--category coding] [--tool Codex] [--limit 25] [--out .prompts-gpt] [--overwrite]
-  prompts-gpt generate --goal "Review this diff" [--context "Next.js app"] [--agent codex,cursor,vscode]
-  prompts-gpt sync [--goal "Review this diff"] [--limit 25] [--agent all] [--out .prompts-gpt] [--cwd /path/to/repo]
-  prompts-gpt install-agents [--agent codex,cursor,vscode,copilot]
 
-Options:
-  --token <token>       Project API token
-  --api-url <url>       Custom API base URL for self-hosted instances
-  --cwd <path>          Target local project directory for config and generated files
-  --agent <targets>     Comma-separated agent targets: codex,cursor,vscode,copilot or all
-  --help                Show this help message
-  --version             Show the current CLI version
-
-Agent targets:
-  codex    writes AGENTS.md with prompt-pack links
-  cursor   writes .cursor/rules/prompts-gpt-*.mdc
-  vscode   writes .github/copilot-instructions.md and .vscode snippets
-  copilot  writes .github/prompts/*.prompt.md
+Commands:
+  init            Save a project token in .prompts-gpt/.credentials.json
+  setup           Scaffold .prompts-gpt/config.json for local orchestration
+  load-config     Pull configuration and prompts directly from Prompts Studio
+  pull            Download prompt packs as Markdown files
+  generate        Generate one prompt pack from a goal
+  sync            Generate and/or pull prompt packs, then sync agent files
+  list            Show available prompts, sweeps, and agent integrations
+  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
+
+Global options:
+  --help          Show help
+  --version       Show the current CLI version
 
 Supported tools: ${VALID_TOOLS.join(", ")}
 Supported agent targets: ${SUPPORTED_AGENT_TARGETS.join(", ")}
+Run agent profiles: ${ORCHESTRATION_AGENT_PROFILES.join(", ")}
 `);
 }
+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>]
+
+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.
+
+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-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.
+  --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 [--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.
+  --api-url <url>       Override the saved API base URL for this command only.
+  --cwd <path>          Project directory to inspect for local credentials.
+  --help                Show this command help.
+`;
+    }
+    if (command === "pull") {
+        return `prompts-gpt pull
+
+Usage:
+  prompts-gpt pull [--query <text> | --q <text>] [--category <name>] [--tool <name>] [--output-type <name>] [--limit <n>] [--out <dir>] [--overwrite] [--token <project-token> | --token-stdin | --token-prompt] [--api-url <url>] [--cwd <path>]
+
+Why use it:
+  Pulls prompt packs into local Markdown files so teams can review and use the same prompt assets inside their repository.
+
+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.
+  --out <dir>           Output directory inside the current project. Default: .prompts-gpt
+  --overwrite           Replace existing Markdown files instead of skipping them.
+  --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.
+`;
+    }
+    if (command === "generate") {
+        return `prompts-gpt generate
+
+Usage:
+  prompts-gpt generate --goal <text> [--context <text>] [--constraints <text>] [--desired-output <text>] [--tool <name>] [--mode <name>] [--artifact-type <name>] [--web-search] [--out <dir>] [--overwrite] [--agent <targets>] [--sync-agents] [--token <project-token> | --token-stdin | --token-prompt] [--api-url <url>] [--cwd <path>]
+
+Why use it:
+  Creates a new reusable prompt pack from a concrete developer goal, then optionally installs agent-readable files immediately.
+
+Options:
+  --goal <text>            Required. The task to generate a prompt pack for.
+  --context <text>         Extra project or stack context for the generator.
+  --constraints <text>     Constraints that the generated prompt must honor.
+  --desired-output <text>  Preferred output shape for the generated prompt pack.
+  --tool <name>            Target tool. Default: Codex
+  --mode <name>            Prompt generation mode. Default: implement
+  --artifact-type <name>   Artifact type. Default: prompt-file
+  --web-search             Allow server-side web research when generating the prompt.
+  --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.
+  --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.
+`;
+    }
+    if (command === "sync") {
+        return `prompts-gpt sync
+
+Usage:
+  prompts-gpt sync [--goal <text>] [--generated-only] [--query <text> | --q <text>] [--category <name>] [--tool <name>] [--output-type <name>] [--limit <n>] [--context <text>] [--constraints <text>] [--desired-output <text>] [--mode <name>] [--artifact-type <name>] [--web-search] [--agent <targets>] [--out <dir>] [--overwrite] [--dry-run] [--token <project-token> | --token-stdin | --token-prompt] [--api-url <url>] [--cwd <path>]
+
+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.
+
+Options:
+  --goal <text>            Generate one prompt pack before syncing.
+  --generated-only         Skip library pull and sync only the generated prompt pack from --goal.
+  --query <text>           Search query for pulled prompt packs.
+  --q <text>               Short alias for --query.
+  --category <name>        Filter pulled prompt packs by category.
+  --tool <name>            Filter pulled prompt packs and generated output by tool.
+  --output-type <name>     Filter pulled prompt packs by output type.
+  --limit <n>              Positive integer limit for pulled prompt packs.
+  --context <text>         Extra project or stack context for generated prompt packs.
+  --constraints <text>     Constraints for generated prompt packs.
+  --desired-output <text>  Preferred output shape for generated prompt packs.
+  --mode <name>            Prompt generation mode. Default: implement
+  --artifact-type <name>   Artifact type. Default: prompt-file
+  --web-search             Allow server-side web research when generating a prompt pack.
+  --agent <targets>        Comma-separated agent targets. Default: all
+  --out <dir>              Output directory inside the current project. Default: .prompts-gpt
+  --overwrite              Replace existing Markdown files instead of skipping them.
+  --dry-run                Preview what would be synced 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 output files.
+  --help                   Show this command help.
+`;
+    }
+    if (command === "run") {
+        return `prompts-gpt run
+
+Usage:
+  prompts-gpt run [--prompt-file <path>] [--agent codex|cursor|claude|copilot|router] [--model <name>] [--timeout <seconds>] [--artifacts-dir <path>] [--run-id <id>] [--sandbox <mode>] [--no-approve-mcps] [--background] [--permission-mode <mode>] [--json] [--cwd <path>]
+
+Why use it:
+  Executes one local prompt file with the built-in provider adapter runtime and writes run artifacts. If \`--prompt-file\` is omitted, the command uses the configured default prompt.
+
+Options:
+  --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") {
+        return `prompts-gpt version
+
+Usage:
+  prompts-gpt version
+
+Why use it:
+  Confirms the installed CLI version when debugging package resolution or publish issues.
+`;
+    }
+    return `prompts-gpt help
+
+Usage:
+  prompts-gpt help [command]
+
+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.
+`;
+}
 main().catch((error) => {
+    if (error instanceof CliError) {
+        console.error(error.message);
+        if (error.helpCommand) {
+            console.error(`Run \`prompts-gpt help${error.helpCommand ? ` ${error.helpCommand}` : ""}\` for usage.`);
+        }
+        process.exitCode = error.exitCode;
+        return;
+    }
     if (error instanceof PromptsGptApiError) {
-        console.error(`${error.message}\n${error.recovery}`);
+        console.error(formatApiError(error));
         process.exitCode = error.status === 401 || error.status === 403
             ? CLI_EXIT_CODES.auth
-            : error.code === "VALIDATION_ERROR"
-                ? CLI_EXIT_CODES.validation
-                : CLI_EXIT_CODES.general;
+            : error.status === 429
+                ? CLI_EXIT_CODES.rateLimit
+                : error.code === "VALIDATION_ERROR"
+                    ? CLI_EXIT_CODES.validation
+                    : 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 ?? {})) {
+        for (const message of messages ?? []) {
+            lines.push(`- ${field}: ${message}`);
+        }
+    }
+    if (error.requestId) {
+        lines.push(`Request ID: ${error.requestId}`);
+    }
+    if (error.recovery) {
+        lines.push(error.recovery);
+    }
+    return lines.join("\n");
+}
 //# sourceMappingURL=cli.js.map