prdforge 0.1.0

package/.env.example

@@ -0,0 +1,9 @@
+# PRDForge CLI — Environment Variables
+# Copy to .env and fill in your values.
+# Alternatively, run 'prdforge auth login' to store your key interactively.
+
+# Your PRDForge API key (get this from Dashboard → Settings → API Keys)
+PRDFORGE_API_KEY=
+
+# Override the default API base URL (optional — only for self-hosted or staging)
+# PRDFORGE_API_URL=https://jnlkzcmeiksqljnbtfhb.supabase.co/functions/v1

package/README.md

@@ -0,0 +1,129 @@
+# PRDForge CLI
+
+The official command-line interface for [PRDForge](https://prdforge.dev) — generate, manage, and export AI-powered Product Requirements Documents from your terminal, CI pipeline, or AI agents.
+
+**PRDForge** turns a product idea into a full blueprint in minutes: structured PRD, architecture, guardrails, and task breakdowns—ready for Cursor, Claude Code, Lovable, or any tool that speaks MCP. This CLI gives you the same power from the command line.
+
+**[→ prdforge.dev](https://prdforge.dev)** · [Web app](https://prdforge.dev) (dashboard, API keys, export)
+
+---
+
+## Installation
+
+```bash
+npm install -g prdforge
+# or run directly
+npx prdforge
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate with your API key
+prdforge auth login
+
+# 2. Create a new PRD from a prompt
+prdforge prd create --name "My App" --prompt "A task manager for remote teams"
+
+# 3. Export to Markdown for Claude Code / Cursor
+prdforge export <projectId> --format markdown
+```
+
+## Authentication
+
+Get your API key from the PRDForge dashboard: **Dashboard → Settings → API Keys**
+
+Requires an active **Pro** or **Starter** subscription.
+
+```bash
+prdforge auth login          # Set your API key interactively
+prdforge auth status         # Check authentication status
+prdforge auth logout         # Remove stored key
+```
+
+You can also set `PRDFORGE_API_KEY` as an environment variable (useful for CI/CD and agents).
+
+## Commands
+
+### `prdforge prd`
+
+```bash
+prdforge prd list                          # List all projects
+prdforge prd get <id>                      # Show all PRD sections
+prdforge prd get <id> --section feature_list  # Show a specific section
+prdforge prd create --name "App" --prompt "..."  # Generate a new PRD
+prdforge prd update <id> --prompt "..."    # Smart-merge an update
+prdforge prd refresh <id>                  # Regenerate stale stages
+```
+
+### `prdforge export`
+
+```bash
+prdforge export <id>                       # Export as Markdown (default)
+prdforge export <id> --format json         # Export as JSON
+prdforge export <id> --output ./CLAUDE.md  # Custom output path
+prdforge export <id> --stdout              # Print to stdout (pipe to files/agents)
+```
+
+### `prdforge watch`
+
+```bash
+prdforge watch <projectId>                 # Poll project and re-export PRD.md when it changes
+prdforge watch <id> -o ./PRD.md -i 60      # Custom output path and 60s interval
+```
+
+### `prdforge mcp`
+
+```bash
+prdforge mcp serve                         # Run MCP server on stdio (for Cursor / MCP clients)
+```
+
+Exposes tools: `prdforge_list_projects`, `prdforge_get_prd`, `prdforge_get_sections`.
+
+### `prdforge bulk`
+
+```bash
+prdforge bulk ideas.csv                    # Generate PRDs from CSV (name, prompt columns)
+prdforge bulk ideas.json --dry-run        # JSON array of { name, prompt }; --dry-run to preview
+prdforge bulk ideas.csv --delay 5000      # Delay between each generation (ms)
+```
+
+### `prdforge config`
+
+```bash
+prdforge config list                       # Show all config values
+prdforge config set outputDir ./exports    # Change export directory
+prdforge config set defaultFormat json     # Change default export format
+prdforge config get outputDir
+```
+
+## Agent / MCP Usage
+
+The CLI is designed to work with AI agents and automation workflows:
+
+```bash
+# Example: Agent generates a PRD, pipes markdown to Claude Code
+prdforge prd create --name "Scheduler" --prompt "$PROMPT" --json | \
+  jq -r '.project.id' | \
+  xargs -I{} prdforge export {} --stdout > CLAUDE.md
+
+# Example: Bulk PRD generation from a list of ideas
+cat ideas.txt | while read idea; do
+  prdforge prd create --name "$(echo $idea | cut -c1-30)" --prompt "$idea"
+done
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PRDFORGE_API_KEY` | Your API key (overrides stored key) |
+| `PRDFORGE_API_URL` | Custom API base URL (for self-hosted) |
+
+## Sync with Main App
+
+See [`SYNC.md`](./SYNC.md) for notes on how this CLI stays in sync with the PRDForge web app and API.
+
+## License
+
+MIT

package/bin/prdforge

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/index.js";

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "prdforge",
+  "version": "0.1.0",
+  "description": "Official CLI for PRDForge — generate and manage PRDs from your terminal or AI agents",
+  "main": "src/index.js",
+  "bin": {
+    "prdforge": "bin/prdforge"
+  },
+  "type": "module",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "test": "node --test src/**/*.test.js",
+    "link": "npm link",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "prdforge",
+    "prd",
+    "product",
+    "requirements",
+    "ai",
+    "cli",
+    "agent",
+    "mcp"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    ".env.example"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "conf": "^13.0.0",
+    "dotenv": "^16.4.5",
+    "inquirer": "^10.2.2",
+    "marked": "^14.1.2",
+    "marked-terminal": "^7.1.0",
+    "node-fetch": "^3.3.2",
+    "ora": "^8.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  }
+}

package/src/api/client.js

@@ -0,0 +1,138 @@
+import { getApiUrl, requireApiKey } from "../utils/config.js";
+
+/** User-facing messages for HTTP status codes (centralized for CLI and agents). */
+function messageForStatus(status, bodyMessage) {
+  if (bodyMessage && typeof bodyMessage === "string") return bodyMessage;
+  switch (status) {
+    case 401:
+      return "Invalid or expired API key. Run `prdforge auth login` or check your key at https://prdforge.app (Settings → CLI Keys).";
+    case 402:
+      return "Credits exhausted. Upgrade your plan or wait until next month. See https://prdforge.app/subscription";
+    case 403:
+      return "Access denied. This action requires a paid plan (Starter or Pro).";
+    case 404:
+      return "Project or resource not found.";
+    case 429:
+      return "Rate limit exceeded. Try again in a moment.";
+    default:
+      if (status >= 500) return "PRDForge service error. Try again later.";
+      return `Request failed (HTTP ${status}).`;
+  }
+}
+
+/**
+ * Make an authenticated request to the PRDForge API (Supabase Edge Functions).
+ * Throws an Error with user-facing message and .httpStatus for exit code handling.
+ */
+async function request(path, { method = "GET", body } = {}) {
+  const apiKey = requireApiKey();
+  const baseUrl = getApiUrl();
+  const url = `${baseUrl}${path}`;
+
+  const headers = {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${apiKey}`,
+    "x-prdforge-cli": "1",
+  };
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch (e) {
+    const err = new Error("Could not reach PRDForge. Check your connection and API URL.");
+    err.httpStatus = 0;
+    throw err;
+  }
+
+  if (!res.ok) {
+    let bodyMessage;
+    try {
+      const errJson = await res.json();
+      bodyMessage = errJson.error || errJson.message;
+    } catch {
+      bodyMessage = null;
+    }
+    const err = new Error(messageForStatus(res.status, bodyMessage));
+    err.httpStatus = res.status;
+    throw err;
+  }
+
+  return res.json();
+}
+
+/** Use for exit code: 2 = auth error, 1 = other. */
+export function isAuthError(err) {
+  return err?.httpStatus === 401 || err?.httpStatus === 403;
+}
+
+// ─── Projects ────────────────────────────────────────────────────────────────
+
+export const projects = {
+  list: () => request("/prdforge-api/projects"),
+  get: (id) => request(`/prdforge-api/projects/${id}`),
+  create: (name, description) =>
+    request("/prdforge-api/projects", {
+      method: "POST",
+      body: { name, description },
+    }),
+  delete: (id) => request(`/prdforge-api/projects/${id}`, { method: "DELETE" }),
+};
+
+// ─── PRD Generation ───────────────────────────────────────────────────────────
+
+export const prd = {
+  generate: (projectId, prompt, modelId) =>
+    request("/prdforge-ai", {
+      method: "POST",
+      body: {
+        action: "generate_from_prompt",
+        payload: { project_id: projectId, prompt },
+        ...(modelId ? { model_id: modelId } : {}),
+      },
+    }),
+
+  update: (projectId, prompt, modelId) =>
+    request("/prdforge-ai", {
+      method: "POST",
+      body: {
+        action: "smart_update",
+        payload: { project_id: projectId, prompt },
+        ...(modelId ? { model_id: modelId } : {}),
+      },
+    }),
+
+  getSections: (projectId) => request(`/prdforge-api/projects/${projectId}/sections`),
+
+  regenerateStale: (projectId, modelId) =>
+    request("/prdforge-ai", {
+      method: "POST",
+      body: {
+        action: "regenerate_stale",
+        payload: { project_id: projectId },
+        ...(modelId ? { model_id: modelId } : {}),
+      },
+    }),
+};
+
+// ─── Export ───────────────────────────────────────────────────────────────────
+
+export const exports_ = {
+  export: (projectId, format) =>
+    request(`/prdforge-api/projects/${projectId}/export`, {
+      method: "POST",
+      body: { format },
+    }),
+};
+
+// ─── Auth ────────────────────────────────────────────────────────────────────
+
+export const auth = {
+  validate: (apiKey) =>
+    fetch(`${getApiUrl()}/prdforge-api/auth/validate`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+    }).then((r) => r.json()),
+};

package/src/api/client.test.js

@@ -0,0 +1,34 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { isAuthError } from "./client.js";
+
+describe("client", () => {
+  describe("isAuthError", () => {
+    it("returns true for 401", () => {
+      const err = new Error("Unauthorized");
+      err.httpStatus = 401;
+      assert.strictEqual(isAuthError(err), true);
+    });
+
+    it("returns true for 403", () => {
+      const err = new Error("Forbidden");
+      err.httpStatus = 403;
+      assert.strictEqual(isAuthError(err), true);
+    });
+
+    it("returns false for 404", () => {
+      const err = new Error("Not found");
+      err.httpStatus = 404;
+      assert.strictEqual(isAuthError(err), false);
+    });
+
+    it("returns false when httpStatus is missing", () => {
+      assert.strictEqual(isAuthError(new Error("Network")), false);
+    });
+
+    it("returns false for null/undefined", () => {
+      assert.strictEqual(isAuthError(null), false);
+      assert.strictEqual(isAuthError(undefined), false);
+    });
+  });
+});

package/src/commands/auth.js

@@ -0,0 +1,60 @@
+import { Command } from "commander";
+import { config, getApiKey } from "../utils/config.js";
+import { success, error, info, dim, header } from "../utils/output.js";
+
+export function authCommand() {
+  const cmd = new Command("auth").description("Manage authentication and API keys");
+
+  cmd
+    .command("login")
+    .description("Set your PRDForge API key")
+    .option("-k, --key <key>", "API key (or set PRDFORGE_API_KEY env var)")
+    .action(async (opts) => {
+      let key = opts.key;
+
+      if (!key) {
+        const { default: inquirer } = await import("inquirer");
+        const { apiKey } = await inquirer.prompt([
+          {
+            type: "password",
+            name: "apiKey",
+            message: "Enter your PRDForge API key:",
+            validate: (v) => v.length > 10 || "Key too short",
+          },
+        ]);
+        key = apiKey;
+      }
+
+      config.set("apiKey", key);
+      success("API key saved. You are now authenticated.");
+      dim("  Key stored in: " + config.path);
+      info("Run 'prdforge prd list' to see your projects.");
+    });
+
+  cmd
+    .command("logout")
+    .description("Remove stored API key")
+    .action(() => {
+      config.delete("apiKey");
+      success("Logged out — API key removed.");
+    });
+
+  cmd
+    .command("status")
+    .description("Show current authentication status")
+    .action(() => {
+      header("Auth Status");
+      const key = getApiKey();
+      if (key) {
+        success("Authenticated");
+        dim(`  Key: ${key.slice(0, 8)}${"*".repeat(Math.max(0, key.length - 8))}`);
+        dim(`  Config: ${config.path}`);
+      } else {
+        error("Not authenticated");
+        info("Run 'prdforge auth login' to set your API key.");
+        info("Get your key at: https://prdforge.netlify.app/dashboard (Settings → API Keys)");
+      }
+    });
+
+  return cmd;
+}

package/src/commands/bulk.js

@@ -0,0 +1,126 @@
+import { Command } from "commander";
+import { readFileSync } from "fs";
+import { projects, prd, isAuthError } from "../api/client.js";
+import { success, error, info, dim } from "../utils/output.js";
+
+function parseCSV(content) {
+  const lines = content.trim().split(/\r?\n/).filter(Boolean);
+  if (lines.length === 0) return [];
+  const header = lines[0].split(",").map((h) => h.trim().toLowerCase());
+  const nameIdx = header.indexOf("name");
+  const promptIdx = header.indexOf("prompt");
+  const descIdx = header.indexOf("description");
+  if (nameIdx === -1 || (promptIdx === -1 && descIdx === -1)) {
+    throw new Error("CSV must have columns: name, and prompt or description");
+  }
+  const promptCol = promptIdx >= 0 ? promptIdx : descIdx;
+  const rows = [];
+  for (let i = 1; i < lines.length; i++) {
+    const values = lines[i].split(",").map((v) => v.trim());
+    const name = values[nameIdx] ?? "";
+    const prompt = values[promptCol] ?? "";
+    if (name) rows.push({ name, prompt });
+  }
+  return rows;
+}
+
+function parseJSON(content) {
+  const data = JSON.parse(content);
+  const arr = Array.isArray(data) ? data : [data];
+  return arr.map((row) => {
+    const name = row.name ?? row.title ?? "";
+    const prompt = row.prompt ?? row.description ?? "";
+    return { name, prompt };
+  });
+}
+
+export function bulkCommand() {
+  const cmd = new Command("bulk")
+    .description("Generate many PRDs from a CSV or JSON file (one PRD per row/item)")
+    .argument("<file>", "Path to .csv or .json file")
+    .option("--delay <ms>", "Delay in ms between each PRD generation (default: 2000)", "2000")
+    .option("--dry-run", "Only parse the file and show what would be created")
+    .option("-m, --model <modelId>", "AI model ID to use for generation")
+    .action(async (file, opts) => {
+      const { default: ora } = await import("ora");
+      let raw;
+      try {
+        raw = readFileSync(file, "utf8");
+      } catch (e) {
+        error(`Cannot read file: ${file}`);
+        process.exit(1);
+      }
+
+      const ext = file.replace(/^.*\./, "").toLowerCase();
+      let rows;
+      try {
+        if (ext === "csv") {
+          rows = parseCSV(raw);
+        } else if (ext === "json") {
+          rows = parseJSON(raw);
+        } else {
+          error("File must be .csv or .json");
+          process.exit(1);
+        }
+      } catch (e) {
+        error(e.message);
+        process.exit(1);
+      }
+
+      if (rows.length === 0) {
+        info("No rows to process.");
+        return;
+      }
+
+      if (opts.dryRun) {
+        info(`Dry run: would create ${rows.length} PRD(s):`);
+        rows.forEach((r, i) => dim(`  ${i + 1}. ${r.name}: ${(r.prompt || "").slice(0, 50)}…`));
+        return;
+      }
+
+      const delayMs = Math.max(0, parseInt(opts.delay, 10) || 2000);
+      const results = [];
+      for (let i = 0; i < rows.length; i++) {
+        const { name, prompt } = rows[i];
+        const spinner = ora(`[${i + 1}/${rows.length}] Creating "${name}"…`).start();
+        try {
+          const project = await projects.create(name, prompt || "");
+          spinner.text = `[${i + 1}/${rows.length}] Generating PRD for "${name}"…`;
+          await prd.generate(project.id, prompt || "", opts.model);
+          spinner.succeed(`"${name}" created (${project.id.slice(0, 8)}…)`);
+          results.push({ name, id: project.id });
+        } catch (err) {
+          spinner.fail(`"${name}" failed`);
+          error(err.message);
+          if (isAuthError(err)) {
+            process.exit(2);
+          }
+          results.push({ name, error: err.message });
+        }
+        if (i < rows.length - 1 && delayMs > 0) {
+          await new Promise((r) => setTimeout(r, delayMs));
+        }
+      }
+
+      success(`Bulk run complete: ${results.filter((r) => !r.error).length} created, ${results.filter((r) => r.error).length} failed.`);
+    });
+
+  cmd.addHelpText(
+    "after",
+    `
+File formats:
+  CSV: header row with "name" and "prompt" (or "description"). Example:
+    name,prompt
+    My App,A task manager for remote teams
+    API,REST API for payments
+
+  JSON: array of objects with "name" and "prompt" (or "description"). Example:
+    [{"name":"My App","prompt":"A task manager"},{"name":"API","prompt":"REST API"}]
+
+Examples:
+  prdforge bulk ideas.csv
+  prdforge bulk ideas.json --delay 5000 --dry-run
+`
+  );
+  return cmd;
+}

package/src/commands/config.js

@@ -0,0 +1,58 @@
+import { Command } from "commander";
+import { config } from "../utils/config.js";
+import { success, error, info, header, table } from "../utils/output.js";
+
+const CONFIGURABLE_KEYS = ["apiUrl", "defaultFormat", "defaultProject", "outputDir"];
+
+export function configCommand() {
+  const cmd = new Command("config").description("Manage CLI configuration");
+
+  cmd
+    .command("list")
+    .description("Show all current configuration values")
+    .action(() => {
+      header("Configuration");
+      table(
+        ["Key", "Value"],
+        CONFIGURABLE_KEYS.map((k) => [k, String(config.get(k) || "")])
+      );
+      info(`Config file: ${config.path}`);
+    });
+
+  cmd
+    .command("set <key> <value>")
+    .description("Set a configuration value")
+    .action((key, value) => {
+      if (!CONFIGURABLE_KEYS.includes(key)) {
+        error(`Unknown key: ${key}`);
+        info(`Valid keys: ${CONFIGURABLE_KEYS.join(", ")}`);
+        process.exit(1);
+      }
+      config.set(key, value);
+      success(`${key} = ${value}`);
+    });
+
+  cmd
+    .command("get <key>")
+    .description("Get a configuration value")
+    .action((key) => {
+      console.log(config.get(key) ?? "");
+    });
+
+  cmd
+    .command("reset")
+    .description("Reset all configuration to defaults")
+    .action(async () => {
+      const { default: inquirer } = await import("inquirer");
+      const { confirm } = await inquirer.prompt([
+        { type: "confirm", name: "confirm", message: "Reset all config? (API key will be kept)", default: false },
+      ]);
+      if (!confirm) return;
+      const key = config.get("apiKey");
+      config.clear();
+      if (key) config.set("apiKey", key);
+      success("Configuration reset to defaults.");
+    });
+
+  return cmd;
+}

package/src/commands/export.js

@@ -0,0 +1,67 @@
+import { Command } from "commander";
+import { writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { exports_, isAuthError } from "../api/client.js";
+import { config } from "../utils/config.js";
+import { success, error, info, dim } from "../utils/output.js";
+
+/** API supports markdown and json only. See SYNC.md for adding new formats. */
+const FORMATS = ["markdown", "json"];
+
+export function exportCommand() {
+  const cmd = new Command("export").description("Export a PRD in various formats");
+
+  cmd
+    .argument("<projectId>", "Project ID to export")
+    .option("-f, --format <format>", `Export format: ${FORMATS.join(", ")}`, "markdown")
+    .option("-o, --output <path>", "Output file path (default: ./prd-exports/<id>.<ext>)")
+    .option("--stdout", "Print to stdout instead of saving to file")
+    .action(async (projectId, opts) => {
+      const { default: ora } = await import("ora");
+
+      if (!FORMATS.includes(opts.format)) {
+        error(`Unknown format: ${opts.format}. Valid options: ${FORMATS.join(", ")}`);
+        process.exit(1);
+      }
+
+      const spinner = ora(`Exporting as ${opts.format}…`).start();
+      try {
+        const result = await exports_.export(projectId, opts.format);
+        spinner.stop();
+
+        const content =
+          opts.format === "json"
+            ? JSON.stringify(result.data ?? result, null, 2)
+            : result.content ?? result.data ?? String(result);
+
+        if (opts.stdout) {
+          console.log(content);
+          return;
+        }
+
+        const ext = opts.format === "markdown" ? "md" : opts.format;
+        const outDir = config.get("outputDir");
+        mkdirSync(outDir, { recursive: true });
+        const filePath = opts.output || join(outDir, `${projectId.slice(0, 8)}.${ext}`);
+        writeFileSync(filePath, content, "utf8");
+
+        success(`Exported to: ${filePath}`);
+        dim(`  Format: ${opts.format}`);
+        info("Feed this file directly to Claude Code, Cursor, or any AI coding tool.");
+      } catch (err) {
+        spinner.fail("Export failed");
+        error(err.message);
+        process.exit(isAuthError(err) ? 2 : 1);
+      }
+    });
+
+  cmd.addHelpText(
+    "after",
+    `
+Examples:
+  prdforge export <projectId> -f markdown -o PRD.md
+  prdforge export <projectId> --format json --stdout
+`
+  );
+  return cmd;
+}

package/src/commands/generate.js

@@ -0,0 +1,117 @@
+import { Command } from "commander";
+import { writeFileSync, mkdirSync, existsSync, renameSync } from "fs";
+import { join } from "path";
+import { projects, prd, exports_, isAuthError } from "../api/client.js";
+import { success, error, info, dim } from "../utils/output.js";
+
+function timestamp() {
+  const d = new Date();
+  return [
+    d.getFullYear(),
+    String(d.getMonth() + 1).padStart(2, "0"),
+    String(d.getDate()).padStart(2, "0"),
+    String(d.getHours()).padStart(2, "0"),
+    String(d.getMinutes()).padStart(2, "0"),
+    String(d.getSeconds()).padStart(2, "0"),
+  ].join("-");
+}
+
+export function generateCommand() {
+  const cmd = new Command("generate")
+    .description("Generate a PRD and save it to your app folder (with optional backup of existing PRD.md)")
+    .option("-n, --name <name>", "Project name (for new PRD)")
+    .option("-p, --prompt <prompt>", "Product idea or update prompt (or set PRDFORGE_PROMPT)")
+    .option("--project <id>", "Existing project ID (for update or refresh)")
+    .option("--refresh", "Regenerate all stale stages, then save")
+    .option("-d, --dir <path>", "App folder to write PRD.md (default: current directory)", process.cwd())
+    .option("-o, --output <path>", "Output filename (default: PRD.md)", "PRD.md")
+    .option("--no-backup", "Do not backup existing PRD.md before overwriting")
+    .option("-m, --model <modelId>", "AI model ID to use")
+    .option("--json", "Output raw JSON instead of writing file")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  prdforge generate -n "My App" -p "A todo app with due dates and tags"
+  prdforge generate --project <id> -p "Add OAuth section"
+  prdforge generate --project <id> --refresh
+  prdforge generate -n "API" -p "REST API for payments" -d ./my-app -o PRD.md
+`
+    );
+
+  cmd.action(async (opts) => {
+    const { default: ora } = await import("ora");
+    const prompt = opts.prompt ?? process.env.PRDFORGE_PROMPT ?? "";
+
+    const isRefresh = !!opts.project && !!opts.refresh;
+    const isUpdate = !!opts.project && !opts.refresh && prompt !== "";
+    const isNew = !!opts.name && prompt !== "";
+
+    if (!isNew && !isUpdate && !isRefresh) {
+      if (opts.name) {
+        error("Provide -p/--prompt or set PRDFORGE_PROMPT to generate a new PRD.");
+      } else {
+        error("Use -n/--name with -p/--prompt for a new PRD, or --project <id> with -p/--prompt or --refresh.");
+      }
+      process.exit(1);
+    }
+
+    let projectId;
+    let content;
+
+    try {
+      if (isNew) {
+        const spinner = ora("Creating project…").start();
+        const project = await projects.create(opts.name, prompt);
+        projectId = project.id;
+        spinner.text = "Generating PRD (this may take ~30–60s)…";
+        await prd.generate(projectId, prompt, opts.model);
+        spinner.succeed("PRD generated!");
+      } else if (isUpdate) {
+        projectId = opts.project;
+        const spinner = ora("Analysing and merging update…").start();
+        await prd.update(projectId, prompt, opts.model);
+        spinner.succeed("PRD updated!");
+      } else {
+        projectId = opts.project;
+        const spinner = ora("Regenerating stale stages…").start();
+        await prd.regenerateStale(projectId, opts.model);
+        spinner.succeed("Stale stages refreshed!");
+      }
+
+      const spinner = ora("Exporting markdown…").start();
+      const result = await exports_.export(projectId, "markdown");
+      spinner.stop();
+      content =
+        result.content ?? result.data ?? (typeof result === "string" ? result : JSON.stringify(result, null, 2));
+    } catch (err) {
+      if (opts.json && err.message) {
+        console.error(JSON.stringify({ error: err.message, httpStatus: err.httpStatus }));
+      } else {
+        error(err.message);
+      }
+      process.exit(isAuthError(err) ? 2 : 1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify({ project_id: projectId, content }, null, 2));
+      return;
+    }
+
+    const dir = opts.dir || process.cwd();
+    const outputPath = join(dir, opts.output || "PRD.md");
+    mkdirSync(dir, { recursive: true });
+
+    if (existsSync(outputPath) && opts.backup !== false) {
+      const backupPath = `${outputPath}.backup.${timestamp()}`;
+      renameSync(outputPath, backupPath);
+      info(`Backed up existing file to ${backupPath}`);
+    }
+
+    writeFileSync(outputPath, content, "utf8");
+    success(`PRD saved to ${outputPath}`);
+    dim("  Use this file with Cursor, Claude Code, or any AI coding tool.");
+  });
+
+  return cmd;
+}

package/src/commands/mcp.js

@@ -0,0 +1,93 @@
+import { Command } from "commander";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { projects, prd, exports_ } from "../api/client.js";
+import { requireApiKey } from "../utils/config.js";
+
+export function mcpCommand() {
+  const cmd = new Command("mcp").description("MCP (Model Context Protocol) server for PRDForge");
+
+  cmd
+    .command("serve")
+    .description("Run the MCP server (stdio). Use with Cursor or other MCP clients.")
+    .action(async () => {
+      // Ensure API key is available before starting (fail fast)
+      requireApiKey();
+
+      const mcpServer = new McpServer({
+        name: "prdforge",
+        version: "0.1.0",
+      });
+
+      mcpServer.registerTool(
+        "prdforge_list_projects",
+        {
+          description: "List all PRDForge projects for the authenticated user",
+          inputSchema: {},
+        },
+        async () => {
+          try {
+            const data = await projects.list();
+            const text =
+              Array.isArray(data) && data.length > 0
+                ? JSON.stringify(data.map((p) => ({ id: p.id, name: p.name, updated_at: p.updated_at })), null, 2)
+                : "No projects yet.";
+            return { content: [{ type: "text", text }] };
+          } catch (err) {
+            return { content: [{ type: "text", text: err.message }], isError: true };
+          }
+        }
+      );
+
+      mcpServer.registerTool(
+        "prdforge_get_prd",
+        {
+          description: "Export a PRD project as markdown by project ID",
+          inputSchema: {
+            project_id: z.string().describe("PRDForge project ID (UUID)"),
+          },
+        },
+        async ({ project_id }) => {
+          try {
+            const result = await exports_.export(project_id, "markdown");
+            const content =
+              result.content ?? result.data ?? (typeof result === "string" ? result : JSON.stringify(result, null, 2));
+            return { content: [{ type: "text", text: content }] };
+          } catch (err) {
+            return { content: [{ type: "text", text: err.message }], isError: true };
+          }
+        }
+      );
+
+      mcpServer.registerTool(
+        "prdforge_get_sections",
+        {
+          description: "Get PRD sections for a project (optionally filter by section_type)",
+          inputSchema: {
+            project_id: z.string().describe("PRDForge project ID (UUID)"),
+            section_type: z.string().optional().describe("Optional section type filter (e.g. feature_list)"),
+          },
+        },
+        async ({ project_id, section_type }) => {
+          try {
+            const sections = await prd.getSections(project_id);
+            const filtered = section_type
+              ? sections.filter((s) => s.section_type === section_type)
+              : sections;
+            const text = JSON.stringify(filtered, null, 2);
+            return { content: [{ type: "text", text }] };
+          } catch (err) {
+            return { content: [{ type: "text", text: err.message }], isError: true };
+          }
+        }
+      );
+
+      const transport = new StdioServerTransport();
+      await mcpServer.connect(transport);
+      // Log to stderr so stdout stays clean for JSON-RPC
+      console.error("PRDForge MCP server running on stdio. Press Ctrl+C to stop.");
+    });
+
+  return cmd;
+}

package/src/commands/prd.js

@@ -0,0 +1,178 @@
+import { Command } from "commander";
+import { prd, projects, isAuthError } from "../api/client.js";
+import { success, error, info, dim, header, table, printPRDSection } from "../utils/output.js";
+
+export function prdCommand() {
+  const cmd = new Command("prd").description("Generate, view, and update PRDs");
+
+  // prdforge prd list
+  cmd
+    .command("list")
+    .description("List all your PRD projects")
+    .option("--json", "Output raw JSON")
+    .action(async (opts) => {
+      const { default: ora } = await import("ora");
+      const spinner = ora("Fetching projects…").start();
+      try {
+        const data = await projects.list();
+        spinner.stop();
+        if (opts.json) {
+          console.log(JSON.stringify(data, null, 2));
+          return;
+        }
+        header("Your PRD Projects");
+        if (!data?.length) {
+          info("No projects yet. Run 'prdforge prd create' to start.");
+          return;
+        }
+        table(
+          ["ID", "Name", "Stages", "Updated"],
+          data.map((p) => [
+            p.id.slice(0, 8) + "…",
+            p.name,
+            `${p.completed_stages || 0}/9`,
+            new Date(p.updated_at).toLocaleDateString(),
+          ])
+        );
+      } catch (err) {
+        spinner.fail("Failed");
+        error(err.message);
+        process.exit(isAuthError(err) ? 2 : 1);
+      }
+    });
+
+  // prdforge prd get <id>
+  cmd
+    .command("get <projectId>")
+    .description("Show all PRD sections for a project")
+    .option("--section <type>", "Show a specific section type")
+    .option("--json", "Output raw JSON")
+    .action(async (projectId, opts) => {
+      const { default: ora } = await import("ora");
+      const spinner = ora("Loading PRD…").start();
+      try {
+        const sections = await prd.getSections(projectId);
+        spinner.stop();
+        if (opts.json) {
+          console.log(JSON.stringify(sections, null, 2));
+          return;
+        }
+        const filtered = opts.section
+          ? sections.filter((s) => s.section_type === opts.section)
+          : sections;
+        header(`PRD Sections (${filtered.length})`);
+        filtered.forEach(printPRDSection);
+      } catch (err) {
+        spinner.fail("Failed");
+        error(err.message);
+        process.exit(isAuthError(err) ? 2 : 1);
+      }
+    });
+
+  // prdforge prd create
+  cmd
+    .command("create")
+    .description("Create a new PRD project from a prompt")
+    .requiredOption("-n, --name <name>", "Project name")
+    .option("-p, --prompt <prompt>", "Product idea or description")
+    .option("-m, --model <modelId>", "AI model ID to use")
+    .option("--json", "Output raw JSON")
+    .action(async (opts) => {
+      const { default: ora } = await import("ora");
+      let prompt = opts.prompt;
+
+      if (!prompt) {
+        const { default: inquirer } = await import("inquirer");
+        const ans = await inquirer.prompt([
+          {
+            type: "editor",
+            name: "prompt",
+            message: "Describe your product idea (opens your $EDITOR):",
+          },
+        ]);
+        prompt = ans.prompt;
+      }
+
+      const spinner = ora("Creating project…").start();
+      try {
+        const project = await projects.create(opts.name, prompt);
+        spinner.text = "Generating PRD (this takes ~30–60s)…";
+        const result = await prd.generate(project.id, prompt, opts.model);
+        spinner.succeed("PRD generated!");
+        if (opts.json) {
+          console.log(JSON.stringify({ project, result }, null, 2));
+        } else {
+          success(`Project "${opts.name}" created`);
+          dim(`  ID: ${project.id}`);
+          info(`View in browser: https://prdforge.netlify.app/workspace/${project.id}`);
+        }
+      } catch (err) {
+        spinner.fail("Failed");
+        error(err.message);
+        process.exit(isAuthError(err) ? 2 : 1);
+      }
+    });
+
+  // prdforge prd update <id>
+  cmd
+    .command("update <projectId>")
+    .description("Intelligently merge an update into an existing PRD")
+    .option("-p, --prompt <prompt>", "What to update or add")
+    .option("-m, --model <modelId>", "AI model ID to use")
+    .option("--json", "Output raw JSON")
+    .action(async (projectId, opts) => {
+      const { default: ora } = await import("ora");
+      let prompt = opts.prompt;
+
+      if (!prompt) {
+        const { default: inquirer } = await import("inquirer");
+        const ans = await inquirer.prompt([
+          {
+            type: "editor",
+            name: "prompt",
+            message: "Describe the update (opens your $EDITOR):",
+          },
+        ]);
+        prompt = ans.prompt;
+      }
+
+      const spinner = ora("Analysing and merging update…").start();
+      try {
+        const result = await prd.update(projectId, prompt, opts.model);
+        spinner.succeed("PRD updated!");
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          success(`Smart merge complete`);
+          if (result.summary) dim(`  Summary: ${result.summary}`);
+          if (result.sectionsUpdated != null) dim(`  Sections updated: ${result.sectionsUpdated}`);
+          if (result.cascadeTriggered) info("  Downstream stages (modules, tasks, etc.) were regenerated.");
+        }
+      } catch (err) {
+        spinner.fail("Failed");
+        error(err.message);
+        process.exit(isAuthError(err) ? 2 : 1);
+      }
+    });
+
+  // prdforge prd refresh <id>
+  cmd
+    .command("refresh <projectId>")
+    .description("Regenerate all stale stages for a project")
+    .option("-m, --model <modelId>", "AI model ID to use")
+    .action(async (projectId, opts) => {
+      const { default: ora } = await import("ora");
+      const spinner = ora("Regenerating stale stages…").start();
+      try {
+        const result = await prd.regenerateStale(projectId, opts.model);
+        spinner.succeed("All stale stages refreshed!");
+        if (result?.summary) dim(`  ${result.summary}`);
+      } catch (err) {
+        spinner.fail("Failed");
+        error(err.message);
+        process.exit(isAuthError(err) ? 2 : 1);
+      }
+    });
+
+  return cmd;
+}

package/src/commands/watch.js

@@ -0,0 +1,65 @@
+import { Command } from "commander";
+import { writeFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { projects, exports_, isAuthError } from "../api/client.js";
+import { config } from "../utils/config.js";
+import { success, error, info, dim } from "../utils/output.js";
+
+const DEFAULT_INTERVAL_SEC = 30;
+const DEFAULT_OUTPUT = "PRD.md";
+
+export function watchCommand() {
+  const cmd = new Command("watch")
+    .description("Watch a PRD project and re-export markdown when it changes (live sync during development)")
+    .argument("<projectId>", "Project ID to watch")
+    .option("-o, --output <path>", "Output file path (default: PRD.md)", DEFAULT_OUTPUT)
+    .option("-i, --interval <seconds>", "Poll interval in seconds", String(DEFAULT_INTERVAL_SEC))
+    .action(async (projectId, opts) => {
+      const intervalSec = Math.max(5, parseInt(opts.interval, 10) || DEFAULT_INTERVAL_SEC);
+      const outputPath = opts.output || DEFAULT_OUTPUT;
+
+      let lastUpdatedAt = null;
+      let firstRun = true;
+
+      const exportOnce = async () => {
+        try {
+          const project = await projects.get(projectId);
+          const updatedAt = project?.updated_at ?? null;
+          if (firstRun) {
+            firstRun = false;
+            lastUpdatedAt = updatedAt;
+          } else if (updatedAt === lastUpdatedAt) {
+            return;
+          }
+          lastUpdatedAt = updatedAt;
+
+          const result = await exports_.export(projectId, "markdown");
+          const content =
+            result.content ?? result.data ?? (typeof result === "string" ? result : JSON.stringify(result, null, 2));
+          const fullPath = join(process.cwd(), outputPath);
+          mkdirSync(dirname(fullPath), { recursive: true });
+          writeFileSync(fullPath, content, "utf8");
+          success(`Exported to ${fullPath}`);
+          dim(`  Updated at: ${updatedAt ? new Date(updatedAt).toISOString() : "—"}`);
+        } catch (err) {
+          error(err.message);
+          if (isAuthError(err)) process.exit(2);
+          // Don't exit on transient errors; next poll will retry
+        }
+      };
+
+      info(`Watching project ${projectId.slice(0, 8)}… (every ${intervalSec}s). Press Ctrl+C to stop.`);
+      await exportOnce();
+      const timer = setInterval(exportOnce, intervalSec * 1000);
+
+      const shutdown = () => {
+        clearInterval(timer);
+        info("Stopped watching.");
+        process.exit(0);
+      };
+      process.on("SIGINT", shutdown);
+      process.on("SIGTERM", shutdown);
+    });
+
+  return cmd;
+}

package/src/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { authCommand } from "./commands/auth.js";
+import { prdCommand } from "./commands/prd.js";
+import { exportCommand } from "./commands/export.js";
+import { generateCommand } from "./commands/generate.js";
+import { configCommand } from "./commands/config.js";
+import { watchCommand } from "./commands/watch.js";
+import { mcpCommand } from "./commands/mcp.js";
+import { bulkCommand } from "./commands/bulk.js";
+
+const LOGO = `
+\x1b[1m\x1b[36m  PRDForge CLI\x1b[0m  \x1b[2mv0.1.0\x1b[0m
+  \x1b[90mThe planning layer for AI-first development\x1b[0m
+`;
+
+const program = new Command();
+
+program
+  .name("prdforge")
+  .description("PRDForge CLI — generate, manage, and export PRDs from your terminal or AI agents")
+  .version("0.1.0", "-v, --version")
+  .addHelpText("beforeAll", LOGO)
+  .hook("preAction", async () => {
+    // Load .env from cwd if present
+    try {
+      const { config: dotenv } = await import("dotenv");
+      dotenv();
+    } catch {}
+  });
+
+program.addCommand(authCommand());
+program.addCommand(generateCommand());
+program.addCommand(prdCommand());
+program.addCommand(exportCommand(), { isDefault: false });
+program.addCommand(watchCommand());
+program.addCommand(mcpCommand());
+program.addCommand(bulkCommand());
+program.addCommand(configCommand());
+
+// Friendly help for unknown commands
+program.on("command:*", (cmds) => {
+  console.error(`\x1b[31m✖\x1b[0m Unknown command: ${cmds[0]}`);
+  console.log("Run \x1b[36mprdforge --help\x1b[0m for a list of commands.");
+  process.exit(1);
+});
+
+// Show help when run with no arguments
+if (process.argv.length === 2) {
+  program.help();
+}
+
+program.parseAsync(process.argv);

package/src/utils/config.js

@@ -0,0 +1,31 @@
+import Conf from "conf";
+
+export const config = new Conf({
+  projectName: "prdforge",
+  schema: {
+    apiKey: { type: "string", default: "" },
+    apiUrl: { type: "string", default: "https://jnlkzcmeiksqljnbtfhb.supabase.co/functions/v1" },
+    defaultFormat: { type: "string", default: "markdown" },
+    defaultProject: { type: "string", default: "" },
+    outputDir: { type: "string", default: "./prd-exports" },
+  },
+});
+
+export function getApiKey() {
+  return process.env.PRDFORGE_API_KEY || config.get("apiKey");
+}
+
+export function getApiUrl() {
+  return process.env.PRDFORGE_API_URL || config.get("apiUrl");
+}
+
+export function requireApiKey() {
+  const key = getApiKey();
+  if (!key) {
+    console.error(
+      "\x1b[31m✖\x1b[0m No API key set. Run \x1b[36mprdforge auth login\x1b[0m to authenticate."
+    );
+    process.exit(1);
+  }
+  return key;
+}

package/src/utils/config.test.js

@@ -0,0 +1,40 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import { getApiKey, getApiUrl } from "./config.js";
+
+describe("config", () => {
+  const origApiKey = process.env.PRDFORGE_API_KEY;
+  const origApiUrl = process.env.PRDFORGE_API_URL;
+
+  afterEach(() => {
+    if (origApiKey !== undefined) process.env.PRDFORGE_API_KEY = origApiKey;
+    else delete process.env.PRDFORGE_API_KEY;
+    if (origApiUrl !== undefined) process.env.PRDFORGE_API_URL = origApiUrl;
+    else delete process.env.PRDFORGE_API_URL;
+  });
+
+  describe("getApiKey", () => {
+    it("returns PRDFORGE_API_KEY when set", () => {
+      process.env.PRDFORGE_API_KEY = "env-key-12345";
+      assert.strictEqual(getApiKey(), "env-key-12345");
+    });
+
+    it("returns a string when PRDFORGE_API_KEY is unset", () => {
+      delete process.env.PRDFORGE_API_KEY;
+      assert.strictEqual(typeof getApiKey(), "string");
+    });
+  });
+
+  describe("getApiUrl", () => {
+    it("returns PRDFORGE_API_URL when set", () => {
+      process.env.PRDFORGE_API_URL = "https://custom.example.com/v1";
+      assert.strictEqual(getApiUrl(), "https://custom.example.com/v1");
+    });
+
+    it("returns a string when PRDFORGE_API_URL is unset", () => {
+      delete process.env.PRDFORGE_API_URL;
+      assert.strictEqual(typeof getApiUrl(), "string");
+      assert.ok(getApiUrl().length > 0);
+    });
+  });
+});

package/src/utils/output.js

@@ -0,0 +1,61 @@
+import Table from "cli-table3";
+
+const C = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+  magenta: "\x1b[35m",
+  gray: "\x1b[90m",
+};
+
+export const color = C;
+
+export function success(msg) {
+  console.log(`${C.green}✔${C.reset} ${msg}`);
+}
+
+export function error(msg) {
+  console.error(`${C.red}✖${C.reset} ${msg}`);
+}
+
+export function warn(msg) {
+  console.warn(`${C.yellow}⚠${C.reset} ${msg}`);
+}
+
+export function info(msg) {
+  console.log(`${C.blue}ℹ${C.reset} ${msg}`);
+}
+
+export function dim(msg) {
+  console.log(`${C.gray}${msg}${C.reset}`);
+}
+
+export function header(title) {
+  const line = "─".repeat(Math.min(process.stdout.columns || 60, 60));
+  console.log(`\n${C.bold}${C.cyan}${title}${C.reset}`);
+  console.log(`${C.gray}${line}${C.reset}`);
+}
+
+export function table(columns, rows) {
+  const t = new Table({
+    head: columns.map((c) => `${C.bold}${C.cyan}${c}${C.reset}`),
+    style: { border: ["gray"], head: [] },
+  });
+  rows.forEach((r) => t.push(r));
+  console.log(t.toString());
+}
+
+export function json(obj) {
+  console.log(JSON.stringify(obj, null, 2));
+}
+
+export function printPRDSection(section) {
+  console.log(`\n${C.bold}${C.blue}## ${section.title}${C.reset}`);
+  console.log(`${C.gray}Type: ${section.section_type}${C.reset}`);
+  console.log(`\n${section.content}\n`);
+}