@prompts-gpt/client 0.1.0 → 0.2.2

package/dist/cli.js

@@ -1,178 +1,591 @@
 #!/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, PROMPTS_GPT_CREDENTIALS_FILE, 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,
+    rateLimit: 4,
+    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 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();
+        return;
+    }
+    const normalizedArgv = normalizeLegacyFlags(argv);
+    const first = normalizedArgv[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(normalizedArgv.slice(1));
+        return;
+    }
+    if (first === "version") {
+        if (normalizedArgv.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, normalizedArgv.slice(1));
+    if (Boolean(flags.help)) {
+        printHelp(command);
         return;
     }
+    await runCommand(command, flags);
+}
+async function runCommand(command, flags) {
     if (command === "init") {
-        const token = (flags.token || process.env.PROMPTS_GPT_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.");
+        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 result = await saveLocalCredentials({
             token,
-            apiUrl: flags.apiUrl || DEFAULT_PROMPTS_GPT_API_URL,
-            cwd: flags.cwd || process.cwd(),
+            apiUrl: getStringFlag(flags, "api-url") || 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 || process.env.PROMPTS_GPT_TOKEN,
-        apiUrl: flags.apiUrl || credentials?.apiUrl || DEFAULT_PROMPTS_GPT_API_URL,
-    });
-    if (command === "project") {
-        const project = await client.getProject();
-        console.log(`${project.brandName} (${project.websiteUrl})`);
-        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 shouldSyncAgents = Boolean(flags["sync-agents"]) || typeof getStringFlag(flags, "agent") === "string";
+        if (shouldSyncAgents) {
+            const target = getStringFlag(flags, "agent") || "all";
             const agentResult = await writeAgentFiles([prompt], {
                 cwd,
-                agent: typeof agentFlag === "string" ? agentFlag : "all",
+                agent: target,
                 overwriteAgentFiles: true,
             });
             console.log(`Synced ${agentResult.written.length} agent file(s) for ${agentResult.targets.join(", ")}.`);
         }
-        console.log(`Wrote generated prompt to ${result.written[0] ?? result.outDir}.`);
-        if (result.skipped.length)
+        console.log(`Generated: ${prompt.title}`);
+        console.log(`Wrote to ${result.written[0] ?? result.outDir}.`);
+        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 (!generatedOnly) {
+            prompts.push(...await client.pullPrompts(buildPullQuery(flags, parsedLimit)));
         }
-        if (!flags.generatedOnly) {
-            prompts.push(...await client.pullPrompts(buildPullQuery(flags)));
+        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)
+        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") {
-        const prompts = await client.pullPrompts(buildPullQuery(flags));
+        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;
+        }
         const result = await writeAgentFiles(prompts, {
-            cwd,
-            agent: flags.agent || flags.agents || "all",
+            cwd: getResolvedCwd(flags),
+            agent: getStringFlag(flags, "agent") || "all",
             overwriteAgentFiles: true,
         });
         console.log(`Synced ${result.written.length} agent integration file(s): ${result.targets.join(", ")}.`);
         return;
     }
-    throw new Error(`Unknown command: ${command}. Run \`prompts-gpt help\` for usage.`);
+    if (command === "project") {
+        const client = await createClientForCommand(command, flags);
+        const project = await client.getProject();
+        console.log(`${project.brandName} (${project.websiteUrl})`);
+        return;
+    }
+}
+async function createClientForCommand(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) {
+        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({
+        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 buildPullQuery(flags) {
+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 === "project") {
+        return common;
+    }
+    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" },
+        };
+    }
     return {
-        q: (flags.query || flags.q),
-        category: flags.category,
-        tool: flags.tool,
-        outputType: flags.outputType,
-        limit: flags.limit,
+        ...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)}`;
+    });
+}
+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,
+        });
+    }
+}
+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;
+        let token = "";
+        const cleanup = () => {
+            stdin.removeListener("data", onData);
+            stdin.setRawMode?.(false);
+            stdin.pause();
+        };
+        const finish = (callback) => {
+            stdout.write("\n");
+            cleanup();
+            callback();
+        };
+        const onData = (chunk) => {
+            const value = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            for (const char of value) {
+                if (char === "\u0003") {
+                    finish(() => reject(new CliError("Token entry cancelled.", CLI_EXIT_CODES.general, { helpCommand: command })));
+                    return;
+                }
+                if (char === "\r" || char === "\n") {
+                    const trimmed = token.trim();
+                    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") {
+                    token = token.slice(0, -1);
+                    continue;
+                }
+                if (char >= " ") {
+                    token += char;
+                    if (token.length > MAX_STDIN_TOKEN_LENGTH) {
+                        finish(() => reject(new CliError("Token input is too long.", CLI_EXIT_CODES.validation, { helpCommand: command })));
+                        return;
+                    }
+                }
+            }
+        };
+        stdout.write("Project token: ");
+        stdin.setEncoding("utf8");
+        stdin.setRawMode?.(true);
+        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.", 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);
+    }
+    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);
+    }
 }
-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 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);
     }
-    return flags;
 }
-function normalizeFlag(raw) {
-    return raw.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+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 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 {
@@ -184,47 +597,246 @@ 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 (or set PROMPTS_GPT_TOKEN env var)
-  --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
+  project         Show the current project linked to the token
+  pull            Download prompt packs as Markdown files
+  generate        Generate one prompt pack from a goal
+  sync            Generate and/or pull prompt packs, then sync agent files
+  install-agents  Refresh agent-specific instruction files from pulled prompts
+  version         Show the current CLI version
+  help            Show global or command-specific help
+
+Global options:
+  --help          Show help
+  --version       Show the current CLI version
 
 Supported tools: ${VALID_TOOLS.join(", ")}
 Supported agent targets: ${SUPPORTED_AGENT_TARGETS.join(", ")}
 `);
 }
+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 === "project") {
+        return `prompts-gpt project
+
+Usage:
+  prompts-gpt project [--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:
+  --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 === "install-agents") {
+        return `prompts-gpt install-agents
+
+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>]
+
+Why use it:
+  Refreshes agent-specific instruction files from the current prompt library without rewriting the Markdown prompt directory.
+
+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.
+  --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));
     process.exitCode = CLI_EXIT_CODES.general;
 });
+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