chatgpt-exporter 1.0.0

package/README.md

@@ -0,0 +1,135 @@
+# ChatGPT Exporter
+
+A CLI tool to back up your ChatGPT conversations as JSON files and convert them to readable Markdown.
+
+## Prerequisites
+
+You need **Node.js 20+** installed on your machine.
+
+- **macOS:** `brew install node` (requires [Homebrew](https://brew.sh/))
+- **Windows/Linux:** download from [nodejs.org](https://nodejs.org/) instead
+- Verify with: `node -v`
+
+## Quick start
+
+No installation needed — just run it with `npx`:
+
+```bash
+npx chatgpt-exporter backup --token "eyJhbG..."
+```
+
+## Getting your ChatGPT access token
+
+This tool needs a ChatGPT access token from your browser session. Here's how to get it:
+
+1. Open [chatgpt.com](https://chatgpt.com) and make sure you're logged in
+2. In the same browser, go to: **[chatgpt.com/api/auth/session](https://chatgpt.com/api/auth/session)**
+3. You'll see a JSON response — copy the value of `accessToken` (the long string starting with `eyJhbG...`)
+
+> **Tip:** The token expires after a while. If you get an authentication error, just grab a fresh one.
+
+You can pass the token directly or set it as an environment variable so you don't have to paste it every time:
+
+```bash
+export CHATGPT_TOKEN="eyJhbG..."
+```
+
+## Usage
+
+### 1. Back up conversations
+
+Downloads all your conversations (including projects) as JSON files:
+
+```bash
+npx chatgpt-exporter backup --token "eyJhbG..."
+```
+
+This creates a `chatgpt-export/` folder with JSON files and their Markdown equivalents:
+
+```
+chatgpt-export/
+  conversations/
+    index.json
+    <conversation-id>.json
+    <conversation-id>.md
+    ...
+  projects/
+    <Project_Name>/
+      conversations/
+        index.json
+        <conversation-id>.json
+        <conversation-id>.md
+        ...
+  metadata.json
+```
+
+**Options:**
+
+| Flag                  | Description                                | Default            |
+| --------------------- | ------------------------------------------ | ------------------ |
+| `-t, --token <token>` | Access token (or use `CHATGPT_TOKEN` env)  | —                  |
+| `-o, --output <dir>`  | Output directory                           | `./chatgpt-export` |
+| `--incremental`       | Only download new or updated conversations | `false`            |
+| `--project <name>`    | Only backup a specific project             | all                |
+| `--concurrency <n>`   | Parallel downloads                         | `3`                |
+| `--delay <ms>`        | Delay between API requests                 | `500`              |
+| `-v, --verbose`       | Show detailed error messages               | `false`            |
+
+**Incremental backups** (recommended after the first full export):
+
+```bash
+npx chatgpt-exporter backup --token "eyJhbG..." --incremental
+```
+
+### 2. List conversations
+
+Preview your conversations without downloading them:
+
+```bash
+npx chatgpt-exporter list --token "eyJhbG..."
+```
+
+Add `--json` to get machine-readable output, or `--project <name>` to filter by project.
+
+### 3. List projects
+
+See all your ChatGPT projects:
+
+```bash
+npx chatgpt-exporter projects --token "eyJhbG..."
+```
+
+## Typical workflow
+
+```bash
+# First time: full export (includes markdown conversion)
+npx chatgpt-exporter backup --token "eyJhbG..."
+
+# Later: only fetch what changed
+npx chatgpt-exporter backup --token "eyJhbG..." --incremental
+```
+
+## Troubleshooting
+
+**"Authentication failed"** — Your token has expired. Grab a fresh one from [chatgpt.com/api/auth/session](https://chatgpt.com/api/auth/session).
+
+**"Rate limit"** — ChatGPT is throttling requests. The tool retries automatically, but you can increase the delay: `--delay 1000`.
+
+**Empty or short Markdown files** — This is normal for short conversations. The tool skips system messages and internal tool calls (like PDF parsing), so a conversation where you uploaded a file and got one response will produce a small `.md` with just your question and the answer.
+
+## Development
+
+To work on the tool locally:
+
+```bash
+git clone <repo-url>
+cd chatgpt-exporter
+npm install
+npm run build
+```
+
+Run from source during development:
+
+```bash
+npm run dev -- backup --token "eyJhbG..."
+```

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,1088 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { Command } from "commander";
+
+// src/cli/commands/backup.ts
+import chalk2 from "chalk";
+import ora from "ora";
+
+// src/api/client.ts
+import crypto from "crypto";
+
+// src/api/endpoints.ts
+var BASE_URL = "https://chatgpt.com";
+var ENDPOINTS = {
+  SESSION: "/api/auth/session",
+  CONVERSATIONS: "/backend-api/conversations",
+  CONVERSATION: (id) => `/backend-api/conversation/${id}`,
+  PROJECTS_SIDEBAR: "/backend-api/gizmos/snorlax/sidebar",
+  PROJECT_CONVERSATIONS: (gizmoId) => `/backend-api/gizmos/${gizmoId}/conversations`
+};
+
+// src/api/types.ts
+import { z } from "zod";
+var SessionSchema = z.looseObject({
+  accessToken: z.string(),
+  user: z.looseObject({
+    id: z.string(),
+    name: z.string().optional(),
+    email: z.string().optional(),
+    image: z.string().optional()
+  }).optional(),
+  expires: z.string().optional()
+});
+var ConversationItemSchema = z.looseObject({
+  id: z.string(),
+  title: z.string().nullable(),
+  create_time: z.string().or(z.number()).nullable(),
+  update_time: z.string().or(z.number()).nullable(),
+  mapping: z.record(z.string(), z.unknown()).nullable().optional(),
+  current_node: z.string().nullable().optional(),
+  conversation_template_id: z.string().nullable().optional(),
+  gizmo_id: z.string().nullable().optional(),
+  is_archived: z.boolean().optional(),
+  workspace_id: z.string().nullable().optional()
+});
+var ConversationsResponseSchema = z.looseObject({
+  items: z.array(ConversationItemSchema),
+  total: z.number(),
+  limit: z.number(),
+  offset: z.number(),
+  has_missing_conversations: z.boolean().optional()
+});
+var MessageContentSchema = z.looseObject({
+  content_type: z.string(),
+  parts: z.array(z.unknown()).optional(),
+  text: z.string().optional()
+});
+var MessageSchema = z.looseObject({
+  id: z.string(),
+  author: z.looseObject({
+    role: z.string(),
+    name: z.string().nullable().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional()
+  }),
+  create_time: z.number().nullable().optional(),
+  update_time: z.number().nullable().optional(),
+  content: MessageContentSchema.optional(),
+  status: z.string().optional(),
+  end_turn: z.boolean().nullable().optional(),
+  weight: z.number().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  recipient: z.string().optional()
+});
+var MappingNodeSchema = z.looseObject({
+  id: z.string(),
+  message: MessageSchema.nullable().optional(),
+  parent: z.string().nullable().optional(),
+  children: z.array(z.string()).optional()
+});
+var ConversationDetailSchema = z.looseObject({
+  id: z.string().optional(),
+  title: z.string().nullable(),
+  create_time: z.number().nullable(),
+  update_time: z.number().nullable(),
+  mapping: z.record(z.string(), MappingNodeSchema),
+  moderation_results: z.array(z.unknown()).optional(),
+  current_node: z.string().nullable().optional(),
+  conversation_id: z.string().optional(),
+  is_archived: z.boolean().optional()
+});
+var ProjectGizmoSchema = z.looseObject({
+  id: z.string(),
+  display: z.looseObject({
+    name: z.string(),
+    theme: z.unknown().optional()
+  }),
+  created_at: z.string().optional(),
+  updated_at: z.string().optional(),
+  last_interacted_at: z.string().nullable().optional(),
+  num_interactions: z.number().optional(),
+  is_archived: z.boolean().optional(),
+  gizmo_type: z.string().optional()
+});
+var SidebarItemSchema = z.looseObject({
+  gizmo: ProjectGizmoSchema
+});
+var ProjectsSidebarResponseSchema = z.looseObject({
+  items: z.array(SidebarItemSchema),
+  cursor: z.string().nullable().optional()
+});
+var ProjectConversationsResponseSchema = z.looseObject({
+  items: z.array(ConversationItemSchema),
+  cursor: z.string().nullable().optional()
+});
+var AuthenticationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends Error {
+  retryAfter;
+  constructor(message, retryAfter) {
+    super(message);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var NetworkError = class extends Error {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "NetworkError";
+    this.statusCode = statusCode;
+  }
+};
+
+// src/utils/retry.ts
+var defaultOptions = {
+  maxRetries: 5,
+  baseDelay: 1e3,
+  maxDelay: 6e4
+};
+function calculateDelay(attempt, baseDelay, maxDelay) {
+  const exponentialDelay = baseDelay * Math.pow(2, attempt);
+  const jitter = Math.random() * 0.3 * exponentialDelay;
+  return Math.min(exponentialDelay + jitter, maxDelay);
+}
+async function withRetry(fn, options = {}) {
+  const opts = { ...defaultOptions, ...options };
+  let lastError;
+  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt === opts.maxRetries) {
+        break;
+      }
+      if (lastError.name === "AuthenticationError" || lastError.name === "NetworkError" && lastError.statusCode === 404) {
+        throw lastError;
+      }
+      const delay = calculateDelay(attempt, opts.baseDelay, opts.maxDelay);
+      opts.onRetry?.(lastError, attempt + 1, delay);
+      await sleep(delay);
+    }
+  }
+  throw lastError;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/api/client.ts
+var BROWSER_HEADERS = {
+  "Content-Type": "application/json",
+  "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+  "Accept": "application/json",
+  "Accept-Language": "en-US,en;q=0.9",
+  "Referer": "https://chatgpt.com/",
+  "Origin": "https://chatgpt.com",
+  "Sec-Ch-Ua": '"Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"',
+  "Sec-Ch-Ua-Mobile": "?0",
+  "Sec-Ch-Ua-Platform": '"macOS"',
+  "Sec-Fetch-Dest": "empty",
+  "Sec-Fetch-Mode": "cors",
+  "Sec-Fetch-Site": "same-origin"
+};
+var ChatGPTClient = class {
+  accessToken;
+  verbose;
+  deviceId;
+  constructor(accessToken, options = {}) {
+    this.accessToken = accessToken;
+    this.verbose = options.verbose ?? false;
+    this.deviceId = crypto.randomUUID();
+  }
+  getHeaders() {
+    return {
+      ...BROWSER_HEADERS,
+      Authorization: `Bearer ${this.accessToken}`,
+      "Oai-Device-Id": this.deviceId,
+      "Oai-Language": "en-US"
+    };
+  }
+  async initialize() {
+    const response = await fetch(`${BASE_URL}/backend-api/conversations?offset=0&limit=1`, {
+      headers: this.getHeaders()
+    });
+    if (!response.ok) {
+      const body = await response.text().catch(() => "(no body)");
+      if (this.verbose) {
+        console.error(`Auth check failed: HTTP ${response.status}`);
+        console.error(`Response body: ${body.slice(0, 500)}`);
+      }
+      if (response.status === 401 || response.status === 403) {
+        throw new AuthenticationError(
+          `Access token rejected (HTTP ${response.status}). ${this.verbose ? "" : "Re-run with --verbose to see the full response."}`
+        );
+      }
+      throw new NetworkError(`Failed to verify token: ${response.status}`, response.status);
+    }
+    if (this.verbose) {
+      console.log("Successfully authenticated");
+    }
+  }
+  async fetch(endpoint, options = {}) {
+    if (!this.accessToken) {
+      throw new AuthenticationError("Client not initialized. Call initialize() first.");
+    }
+    const { method = "GET", body, parseResponse } = options;
+    return withRetry(
+      async () => {
+        const response = await fetch(`${BASE_URL}${endpoint}`, {
+          method,
+          headers: this.getHeaders(),
+          body: body ? JSON.stringify(body) : void 0
+        });
+        if (!response.ok) {
+          if (response.status === 401 || response.status === 403) {
+            throw new AuthenticationError("Access token expired or invalid.");
+          }
+          if (response.status === 429) {
+            const retryAfter = response.headers.get("retry-after");
+            throw new RateLimitError(
+              "Rate limited by API",
+              retryAfter ? parseInt(retryAfter, 10) * 1e3 : void 0
+            );
+          }
+          throw new NetworkError(
+            `Request failed: ${response.status} ${response.statusText}`,
+            response.status
+          );
+        }
+        const data = await response.json();
+        return parseResponse ? parseResponse(data) : data;
+      },
+      {
+        onRetry: (error, attempt, delay) => {
+          if (this.verbose) {
+            console.log(`Retry ${attempt}: ${error.message} (waiting ${Math.round(delay / 1e3)}s)`);
+          }
+        }
+      }
+    );
+  }
+};
+
+// src/api/pagination.ts
+async function* fetchAllConversations(client, options = {}) {
+  const { limit = 28, delay = 500, onProgress } = options;
+  let offset = 0;
+  let total = Infinity;
+  let fetched = 0;
+  while (offset < total) {
+    const response = await client.fetch(
+      `${ENDPOINTS.CONVERSATIONS}?offset=${offset}&limit=${limit}&order=updated`,
+      {
+        parseResponse: (data) => ConversationsResponseSchema.parse(data)
+      }
+    );
+    total = response.total;
+    for (const item of response.items) {
+      yield item;
+      fetched++;
+    }
+    onProgress?.(fetched, total);
+    offset += limit;
+    if (offset < total && delay > 0) {
+      await sleep(delay);
+    }
+  }
+}
+async function countConversations(client) {
+  const response = await client.fetch(
+    `${ENDPOINTS.CONVERSATIONS}?offset=0&limit=1`,
+    {
+      parseResponse: (data) => ConversationsResponseSchema.parse(data)
+    }
+  );
+  return response.total;
+}
+async function fetchAllProjects(client, options = {}) {
+  const { delay = 500 } = options;
+  const allItems = [];
+  let cursor = null;
+  do {
+    const url = cursor ? `${ENDPOINTS.PROJECTS_SIDEBAR}?cursor=${encodeURIComponent(cursor)}` : ENDPOINTS.PROJECTS_SIDEBAR;
+    const response = await client.fetch(url, {
+      parseResponse: (data) => ProjectsSidebarResponseSchema.parse(data)
+    });
+    allItems.push(...response.items);
+    cursor = response.cursor;
+    if (cursor && delay > 0) {
+      await sleep(delay);
+    }
+  } while (cursor);
+  return allItems;
+}
+async function* fetchProjectConversations(client, gizmoId, options = {}) {
+  const { delay = 500, onProgress } = options;
+  let cursor = "0";
+  let fetched = 0;
+  while (cursor !== null && cursor !== void 0) {
+    const url = `${ENDPOINTS.PROJECT_CONVERSATIONS(gizmoId)}?cursor=${encodeURIComponent(cursor)}`;
+    const response = await client.fetch(url, {
+      parseResponse: (data) => ProjectConversationsResponseSchema.parse(data)
+    });
+    for (const item of response.items) {
+      yield item;
+      fetched++;
+    }
+    cursor = response.cursor;
+    onProgress?.(fetched, fetched);
+    if (cursor && delay > 0) {
+      await sleep(delay);
+    }
+  }
+}
+
+// src/services/backup-service.ts
+var BackupService = class {
+  client;
+  storage;
+  constructor(client, storage) {
+    this.client = client;
+    this.storage = storage;
+  }
+  async listConversations(options) {
+    const conversations = [];
+    for await (const conversation of fetchAllConversations(this.client, {
+      delay: options.delay,
+      onProgress: options.onListProgress
+    })) {
+      conversations.push(conversation);
+    }
+    return conversations;
+  }
+  async getConversationCount() {
+    return countConversations(this.client);
+  }
+  async listProjects() {
+    return fetchAllProjects(this.client);
+  }
+  async listProjectConversations(gizmoId, options = {}) {
+    const conversations = [];
+    for await (const conversation of fetchProjectConversations(this.client, gizmoId, {
+      delay: options.delay,
+      onProgress: options.onListProgress
+    })) {
+      conversations.push(conversation);
+    }
+    return conversations;
+  }
+  async resolveProjectId(nameOrId) {
+    const projects = await this.listProjects();
+    const match = projects.find(
+      (p) => p.gizmo.id === nameOrId || p.gizmo.display.name.toLowerCase() === nameOrId.toLowerCase()
+    );
+    if (!match) {
+      const available = projects.map((p) => p.gizmo.display.name).join(", ");
+      throw new Error(
+        `Project "${nameOrId}" not found. Available projects: ${available || "(none)"}`
+      );
+    }
+    return { gizmoId: match.gizmo.id, name: match.gizmo.display.name };
+  }
+  async downloadConversation(id) {
+    return this.client.fetch(ENDPOINTS.CONVERSATION(id), {
+      parseResponse: (data) => ConversationDetailSchema.parse(data)
+    });
+  }
+  async backup(options) {
+    const {
+      concurrency,
+      delay,
+      incremental,
+      verbose,
+      projectGizmoId,
+      onListProgress,
+      onDownloadProgress,
+      onError
+    } = options;
+    await this.storage.initialize();
+    await this.storage.appendLog("Starting backup...");
+    const conversations = projectGizmoId ? await this.listProjectConversations(projectGizmoId, { delay, onListProgress }) : await this.listConversations({ delay, onListProgress });
+    await this.storage.saveIndex(conversations);
+    const errors = [];
+    let downloaded = 0;
+    let skipped = 0;
+    let failed = 0;
+    let completed = 0;
+    const toDownload = [];
+    for (const conv of conversations) {
+      if (incremental) {
+        const existingUpdateTime = await this.storage.getExistingConversationUpdateTime(conv.id);
+        const convUpdateTime = typeof conv.update_time === "number" ? conv.update_time : conv.update_time ? new Date(conv.update_time).getTime() / 1e3 : null;
+        if (existingUpdateTime !== null && convUpdateTime !== null && existingUpdateTime >= convUpdateTime) {
+          skipped++;
+          completed++;
+          onDownloadProgress?.(completed, conversations.length, conv.title ?? conv.id);
+          continue;
+        }
+      }
+      toDownload.push(conv);
+    }
+    const downloadQueue = [...toDownload];
+    const inProgress = /* @__PURE__ */ new Set();
+    const processOne = async (conv) => {
+      try {
+        const detail = await this.downloadConversation(conv.id);
+        await this.storage.saveConversation(conv.id, detail);
+        downloaded++;
+        if (verbose) {
+          await this.storage.appendLog(`Downloaded: ${conv.id} - ${conv.title ?? "Untitled"}`);
+        }
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        errors.push({ conversationId: conv.id, error: errorMessage });
+        failed++;
+        onError?.(conv.id, error);
+        await this.storage.appendLog(`Failed: ${conv.id} - ${errorMessage}`);
+      } finally {
+        completed++;
+        onDownloadProgress?.(completed, conversations.length, conv.title ?? conv.id);
+      }
+    };
+    while (downloadQueue.length > 0 || inProgress.size > 0) {
+      while (inProgress.size < concurrency && downloadQueue.length > 0) {
+        const conv = downloadQueue.shift();
+        const promise = processOne(conv).then(() => {
+          inProgress.delete(promise);
+        });
+        inProgress.add(promise);
+        if (downloadQueue.length > 0 && delay > 0) {
+          await sleep(delay);
+        }
+      }
+      if (inProgress.size > 0) {
+        await Promise.race(inProgress);
+      }
+    }
+    const metadata = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      totalConversations: conversations.length,
+      successfulDownloads: downloaded,
+      failedDownloads: failed,
+      errors
+    };
+    await this.storage.saveMetadata(metadata);
+    await this.storage.appendLog(`Backup completed: ${downloaded} downloaded, ${skipped} skipped, ${failed} failed`);
+    return {
+      totalConversations: conversations.length,
+      downloaded,
+      skipped,
+      failed,
+      errors
+    };
+  }
+};
+
+// src/services/markdown-service.ts
+import fs from "fs/promises";
+import path from "path";
+function extractTextFromParts(parts) {
+  const pieces = [];
+  for (const part of parts) {
+    if (typeof part === "string") {
+      pieces.push(part);
+    } else if (part && typeof part === "object") {
+      const obj = part;
+      if (obj.content_type === "image_asset_pointer") {
+        const pointer = obj.asset_pointer;
+        pieces.push(`![image](${pointer ?? "unknown"})`);
+      }
+    }
+  }
+  return pieces.join("\n");
+}
+function getLinearThread(mapping, currentNode) {
+  if (currentNode && mapping[currentNode]) {
+    const path3 = [];
+    let nodeId = currentNode;
+    while (nodeId && mapping[nodeId]) {
+      path3.unshift(mapping[nodeId]);
+      nodeId = mapping[nodeId].parent;
+    }
+    return path3;
+  }
+  let root;
+  for (const node of Object.values(mapping)) {
+    if (node.parent === null || node.parent === void 0) {
+      root = node;
+      break;
+    }
+  }
+  if (!root) return [];
+  const thread = [root];
+  let current = root;
+  while (current.children && current.children.length > 0) {
+    const nextId = current.children[0];
+    const next = mapping[nextId];
+    if (!next) break;
+    thread.push(next);
+    current = next;
+  }
+  return thread;
+}
+function formatDate(timestamp) {
+  const date = new Date(timestamp * 1e3);
+  return date.toISOString().split("T")[0];
+}
+function formatRole(role) {
+  switch (role) {
+    case "user":
+      return "User";
+    case "assistant":
+      return "Assistant";
+    default:
+      return role.charAt(0).toUpperCase() + role.slice(1);
+  }
+}
+function convertConversation(detail) {
+  const lines = [];
+  const title = detail.title ?? "Untitled";
+  lines.push(`# ${title}`);
+  if (detail.create_time) {
+    lines.push(`*${formatDate(detail.create_time)}*`);
+  }
+  const thread = getLinearThread(
+    detail.mapping,
+    detail.current_node
+  );
+  let firstMessage = true;
+  for (const node of thread) {
+    const msg = node.message;
+    if (!msg) continue;
+    const role = msg.author.role;
+    if (role === "system" || role === "tool") continue;
+    if (msg.metadata?.is_visually_hidden_from_conversation) continue;
+    if (msg.weight === 0) continue;
+    let text = "";
+    if (msg.content) {
+      if (msg.content.parts && msg.content.parts.length > 0) {
+        text = extractTextFromParts(msg.content.parts);
+      } else if (msg.content.text) {
+        text = msg.content.text;
+      }
+    }
+    if (!text.trim()) continue;
+    if (firstMessage) {
+      lines.push("");
+      firstMessage = false;
+    } else {
+      lines.push("");
+      lines.push("---");
+      lines.push("");
+    }
+    lines.push(`**${formatRole(role)}:**`);
+    lines.push("");
+    lines.push(text);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+async function findJsonFiles(dir) {
+  const files = [];
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isFile() && entry.name.endsWith(".json") && entry.name !== "index.json") {
+        files.push(fullPath);
+      }
+    }
+  } catch {
+  }
+  return files;
+}
+async function collectAllJsonFiles(inputDir) {
+  const files = [];
+  const mainDir = path.join(inputDir, "conversations");
+  files.push(...await findJsonFiles(mainDir));
+  const projectsDir = path.join(inputDir, "projects");
+  try {
+    const projectEntries = await fs.readdir(projectsDir, { withFileTypes: true });
+    for (const entry of projectEntries) {
+      if (entry.isDirectory()) {
+        const projectConvDir = path.join(projectsDir, entry.name, "conversations");
+        files.push(...await findJsonFiles(projectConvDir));
+      }
+    }
+  } catch {
+  }
+  return files;
+}
+async function convertDirectory(inputDir) {
+  const jsonFiles = await collectAllJsonFiles(inputDir);
+  let converted = 0;
+  let errors = 0;
+  for (const jsonPath of jsonFiles) {
+    try {
+      const raw = await fs.readFile(jsonPath, "utf-8");
+      const detail = JSON.parse(raw);
+      const markdown = convertConversation(detail);
+      const mdPath = jsonPath.replace(/\.json$/, ".md");
+      await fs.writeFile(mdPath, markdown, "utf-8");
+      converted++;
+    } catch {
+      errors++;
+    }
+  }
+  return { converted, errors };
+}
+
+// src/services/storage-service.ts
+import fs2 from "fs/promises";
+import path2 from "path";
+var StorageService = class {
+  outputDir;
+  conversationsDir;
+  constructor(outputDir, projectName) {
+    this.outputDir = outputDir;
+    if (projectName) {
+      const safeName = projectName.replace(/[^a-zA-Z0-9_-]/g, "_");
+      this.conversationsDir = path2.join(outputDir, "projects", safeName, "conversations");
+    } else {
+      this.conversationsDir = path2.join(outputDir, "conversations");
+    }
+  }
+  async initialize() {
+    await fs2.mkdir(this.conversationsDir, { recursive: true });
+  }
+  async saveConversation(id, data) {
+    const filePath = path2.join(this.conversationsDir, `${id}.json`);
+    await fs2.writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
+  }
+  async saveIndex(conversations) {
+    const filePath = path2.join(this.conversationsDir, "index.json");
+    await fs2.writeFile(filePath, JSON.stringify(conversations, null, 2), "utf-8");
+  }
+  async saveMetadata(metadata) {
+    const filePath = path2.join(this.outputDir, "metadata.json");
+    await fs2.writeFile(filePath, JSON.stringify(metadata, null, 2), "utf-8");
+  }
+  async appendLog(message) {
+    const filePath = path2.join(this.outputDir, "backup.log");
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    await fs2.appendFile(filePath, `[${timestamp}] ${message}
+`, "utf-8");
+  }
+  async conversationExists(id) {
+    const filePath = path2.join(this.conversationsDir, `${id}.json`);
+    try {
+      await fs2.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async getExistingConversationUpdateTime(id) {
+    const filePath = path2.join(this.conversationsDir, `${id}.json`);
+    try {
+      const content = await fs2.readFile(filePath, "utf-8");
+      const data = JSON.parse(content);
+      return data.update_time ?? null;
+    } catch {
+      return null;
+    }
+  }
+  getConversationPath(id) {
+    return path2.join(this.conversationsDir, `${id}.json`);
+  }
+};
+
+// src/utils/progress.ts
+import cliProgress from "cli-progress";
+import chalk from "chalk";
+function createProgressBar(total, label) {
+  const bar = new cliProgress.SingleBar({
+    format: `${chalk.cyan(label)} |${chalk.cyan("{bar}")}| {percentage}% | {value}/{total}`,
+    barCompleteChar: "\u2588",
+    barIncompleteChar: "\u2591",
+    hideCursor: true,
+    gracefulExit: true
+  });
+  bar.start(total, 0);
+  return bar;
+}
+
+// src/cli/commands/backup.ts
+function runBackupWithProgress(service, spinner, options) {
+  let listProgressBar = null;
+  let downloadProgressBar = null;
+  let listingDone = false;
+  return service.backup({
+    ...options,
+    onListProgress: (fetched, totalList) => {
+      if (!listingDone) {
+        if (!listProgressBar) {
+          spinner.stop();
+          listProgressBar = createProgressBar(totalList, "Listing    ");
+        }
+        listProgressBar.setTotal(totalList);
+        listProgressBar.update(fetched);
+        if (fetched >= totalList) {
+          listProgressBar.stop();
+          listingDone = true;
+          console.log();
+        }
+      }
+    },
+    onDownloadProgress: (completed, totalDownload) => {
+      if (listingDone) {
+        if (!downloadProgressBar) {
+          downloadProgressBar = createProgressBar(totalDownload, "Downloading");
+        }
+        downloadProgressBar.update(completed);
+      }
+    },
+    onError: (id, error) => {
+      if (options.verbose) {
+        console.error(chalk2.red(`
+Failed to download ${id}: ${error.message}`));
+      }
+    }
+  }).then((result) => {
+    downloadProgressBar?.stop();
+    return result;
+  });
+}
+async function backupCommand(options) {
+  const { token, output, concurrency, delay, incremental, verbose, project } = options;
+  const client = new ChatGPTClient(token, { verbose });
+  const spinner = ora("Authenticating...").start();
+  try {
+    await client.initialize();
+    spinner.succeed("Authenticated");
+    console.log(chalk2.dim(`
+Backup settings:`));
+    console.log(chalk2.dim(`  Output: ${output}`));
+    console.log(chalk2.dim(`  Concurrency: ${concurrency}`));
+    console.log(chalk2.dim(`  Delay: ${delay}ms`));
+    console.log(chalk2.dim(`  Incremental: ${incremental}`));
+    if (project) {
+      console.log(chalk2.dim(`  Project: ${project}`));
+    }
+    console.log();
+    if (project) {
+      const baseService = new BackupService(client, new StorageService(output));
+      spinner.start("Resolving project...");
+      const { gizmoId, name } = await baseService.resolveProjectId(project);
+      spinner.succeed(`Project: ${name}`);
+      const storage = new StorageService(output, name);
+      const service = new BackupService(client, storage);
+      spinner.start(`Backing up project "${name}"...`);
+      const result = await runBackupWithProgress(service, spinner, {
+        concurrency,
+        delay,
+        incremental,
+        verbose,
+        projectGizmoId: gizmoId
+      });
+      printResult(result, output);
+      const md = await convertDirectory(output);
+      console.log(`Converted ${md.converted} conversations to markdown.`);
+      if (md.errors > 0) {
+        console.log(`Markdown conversion errors: ${chalk2.red(md.errors)}`);
+      }
+    } else {
+      let totalDownloaded = 0;
+      let totalSkipped = 0;
+      let totalFailed = 0;
+      let totalConversations = 0;
+      console.log(chalk2.bold("Main conversations\n"));
+      const mainStorage = new StorageService(output);
+      const mainService = new BackupService(client, mainStorage);
+      spinner.start("Fetching conversation list...");
+      const mainResult = await runBackupWithProgress(mainService, spinner, {
+        concurrency,
+        delay,
+        incremental,
+        verbose
+      });
+      totalDownloaded += mainResult.downloaded;
+      totalSkipped += mainResult.skipped;
+      totalFailed += mainResult.failed;
+      totalConversations += mainResult.totalConversations;
+      console.log();
+      console.log(`  Downloaded: ${chalk2.green(mainResult.downloaded)}, Skipped: ${chalk2.yellow(mainResult.skipped)}, Failed: ${chalk2.red(mainResult.failed)}`);
+      console.log();
+      spinner.start("Fetching projects...");
+      const projects = await mainService.listProjects();
+      spinner.succeed(`Found ${projects.length} projects`);
+      for (const proj of projects) {
+        const name = proj.gizmo.display.name;
+        const gizmoId = proj.gizmo.id;
+        console.log();
+        console.log(chalk2.bold(`Project: ${name}
+`));
+        const projStorage = new StorageService(output, name);
+        const projService = new BackupService(client, projStorage);
+        spinner.start(`Backing up "${name}"...`);
+        const projResult = await runBackupWithProgress(projService, spinner, {
+          concurrency,
+          delay,
+          incremental,
+          verbose,
+          projectGizmoId: gizmoId
+        });
+        totalDownloaded += projResult.downloaded;
+        totalSkipped += projResult.skipped;
+        totalFailed += projResult.failed;
+        totalConversations += projResult.totalConversations;
+        console.log();
+        console.log(`  Downloaded: ${chalk2.green(projResult.downloaded)}, Skipped: ${chalk2.yellow(projResult.skipped)}, Failed: ${chalk2.red(projResult.failed)}`);
+      }
+      console.log();
+      console.log(chalk2.green("\nBackup completed!"));
+      console.log(`  Total conversations: ${totalConversations}`);
+      console.log(`  Downloaded: ${chalk2.green(totalDownloaded)}`);
+      if (totalSkipped > 0) {
+        console.log(`  Skipped (unchanged): ${chalk2.yellow(totalSkipped)}`);
+      }
+      if (totalFailed > 0) {
+        console.log(`  Failed: ${chalk2.red(totalFailed)}`);
+      }
+      console.log(`
+Output directory: ${chalk2.cyan(output)}`);
+      const md = await convertDirectory(output);
+      console.log(`
+Converted ${md.converted} conversations to markdown.`);
+      if (md.errors > 0) {
+        console.log(`Markdown conversion errors: ${chalk2.red(md.errors)}`);
+      }
+    }
+  } catch (error) {
+    spinner.fail("Backup failed");
+    if (error instanceof Error) {
+      if (error.name === "AuthenticationError") {
+        console.error(chalk2.red(`
+Authentication failed: ${error.message}`));
+        console.error(chalk2.yellow("\nTo get a new access token:"));
+        console.error("  1. Open chatgpt.com in your browser and log in");
+        console.error("  2. Open DevTools (F12) \u2192 Network tab");
+        console.error("  3. Refresh the page or send a message");
+        console.error("  4. Find any request to /backend-api/*");
+        console.error('  5. Look in Request Headers for "Authorization: Bearer <token>"');
+        console.error('  6. Copy the token (starts with "eyJhbG...")');
+      } else {
+        console.error(chalk2.red(`
+Error: ${error.message}`));
+      }
+    }
+    process.exit(1);
+  }
+}
+function printResult(result, output) {
+  console.log();
+  console.log(chalk2.green("\nBackup completed!"));
+  console.log(`  Total conversations: ${result.totalConversations}`);
+  console.log(`  Downloaded: ${chalk2.green(result.downloaded)}`);
+  if (result.skipped > 0) {
+    console.log(`  Skipped (unchanged): ${chalk2.yellow(result.skipped)}`);
+  }
+  if (result.failed > 0) {
+    console.log(`  Failed: ${chalk2.red(result.failed)}`);
+    console.log(chalk2.dim(`  See ${output}/backup.log for details`));
+  }
+  console.log(`
+Output directory: ${chalk2.cyan(output)}`);
+}
+
+// src/cli/commands/list.ts
+import chalk3 from "chalk";
+import ora2 from "ora";
+async function listCommand(options) {
+  const { token, delay, verbose, json, project } = options;
+  const client = new ChatGPTClient(token, { verbose });
+  const storage = new StorageService("./chatgpt-export");
+  const service = new BackupService(client, storage);
+  const spinner = ora2("Authenticating...").start();
+  try {
+    await client.initialize();
+    let conversations;
+    if (project) {
+      spinner.text = "Resolving project...";
+      const { gizmoId, name } = await service.resolveProjectId(project);
+      spinner.text = `Fetching conversations from project "${name}"...`;
+      let lastReported = 0;
+      conversations = await service.listProjectConversations(gizmoId, {
+        delay,
+        onListProgress: (fetched, total) => {
+          if (fetched !== lastReported) {
+            spinner.text = `Fetching conversations from "${name}"... ${fetched}`;
+            lastReported = fetched;
+          }
+        }
+      });
+      spinner.succeed(`Found ${conversations.length} conversations in project "${name}"`);
+    } else {
+      spinner.text = "Fetching conversations...";
+      let lastReported = 0;
+      conversations = await service.listConversations({
+        delay,
+        onListProgress: (fetched, total) => {
+          if (fetched !== lastReported) {
+            spinner.text = `Fetching conversations... ${fetched}/${total}`;
+            lastReported = fetched;
+          }
+        }
+      });
+      spinner.succeed(`Found ${conversations.length} conversations`);
+    }
+    if (json) {
+      console.log(JSON.stringify(conversations, null, 2));
+    } else {
+      console.log();
+      for (const conv of conversations) {
+        const title = conv.title ?? chalk3.dim("(untitled)");
+        const date = conv.update_time ? new Date(
+          typeof conv.update_time === "number" ? conv.update_time * 1e3 : conv.update_time
+        ).toLocaleDateString() : "unknown date";
+        console.log(`${chalk3.cyan(conv.id)} ${title} ${chalk3.dim(`[${date}]`)}`);
+      }
+      console.log();
+      console.log(chalk3.green(`Total: ${conversations.length} conversations`));
+    }
+  } catch (error) {
+    spinner.fail("Failed to list conversations");
+    if (error instanceof Error) {
+      if (error.name === "AuthenticationError") {
+        console.error(chalk3.red(`
+Authentication failed: ${error.message}`));
+        console.error(chalk3.yellow("\nTo get a new access token:"));
+        console.error("  1. Open chatgpt.com in your browser and log in");
+        console.error("  2. Open DevTools (F12) \u2192 Network tab");
+        console.error("  3. Refresh the page or send a message");
+        console.error("  4. Find any request to /backend-api/*");
+        console.error('  5. Look in Request Headers for "Authorization: Bearer <token>"');
+        console.error('  6. Copy the token (starts with "eyJhbG...")');
+      } else {
+        console.error(chalk3.red(`
+Error: ${error.message}`));
+      }
+    }
+    process.exit(1);
+  }
+}
+
+// src/cli/commands/projects.ts
+import chalk4 from "chalk";
+import ora3 from "ora";
+async function projectsCommand(options) {
+  const { token, verbose, json } = options;
+  const client = new ChatGPTClient(token, { verbose });
+  const storage = new StorageService("./chatgpt-export");
+  const service = new BackupService(client, storage);
+  const spinner = ora3("Authenticating...").start();
+  try {
+    await client.initialize();
+    spinner.text = "Fetching projects...";
+    const projects = await service.listProjects();
+    spinner.succeed(`Found ${projects.length} projects`);
+    if (json) {
+      const output = projects.map((p) => ({
+        id: p.gizmo.id,
+        name: p.gizmo.display.name,
+        num_interactions: p.gizmo.num_interactions,
+        last_interacted_at: p.gizmo.last_interacted_at,
+        is_archived: p.gizmo.is_archived
+      }));
+      console.log(JSON.stringify(output, null, 2));
+    } else {
+      console.log();
+      for (const project of projects) {
+        const gizmo = project.gizmo;
+        const name = gizmo.display.name;
+        const id = gizmo.id;
+        const lastInteracted = gizmo.last_interacted_at ? new Date(gizmo.last_interacted_at).toLocaleDateString() : "never";
+        console.log(
+          `${chalk4.cyan(id)} ${chalk4.bold(name)} ${chalk4.dim(`[last: ${lastInteracted}]`)}`
+        );
+      }
+      console.log();
+      console.log(chalk4.green(`Total: ${projects.length} projects`));
+    }
+  } catch (error) {
+    spinner.fail("Failed to list projects");
+    if (error instanceof Error) {
+      if (error.name === "AuthenticationError") {
+        console.error(chalk4.red(`
+Authentication failed: ${error.message}`));
+        console.error(chalk4.yellow("\nTo get a new access token:"));
+        console.error("  1. Open chatgpt.com in your browser and log in");
+        console.error("  2. Open DevTools (F12) \u2192 Network tab");
+        console.error("  3. Refresh the page or send a message");
+        console.error("  4. Find any request to /backend-api/*");
+        console.error('  5. Look in Request Headers for "Authorization: Bearer <token>"');
+        console.error('  6. Copy the token (starts with "eyJhbG...")');
+      } else {
+        console.error(chalk4.red(`
+Error: ${error.message}`));
+      }
+    }
+    process.exit(1);
+  }
+}
+
+// src/cli/index.ts
+function createCli() {
+  const program2 = new Command();
+  program2.name("chatgpt-exporter").description("Export your ChatGPT conversations").version("1.0.0").action(() => {
+    program2.help();
+  });
+  const getToken = (options) => {
+    const token = options.token ?? process.env.CHATGPT_TOKEN;
+    if (!token) {
+      console.error("Error: Access token required. Use --token or set CHATGPT_TOKEN env variable.");
+      console.error("\nTo get your access token:");
+      console.error("  1. Open chatgpt.com in your browser and log in");
+      console.error("  2. Open DevTools (F12) \u2192 Network tab");
+      console.error("  3. Refresh the page or send a message");
+      console.error("  4. Find any request to /backend-api/*");
+      console.error('  5. Look in Request Headers for "Authorization: Bearer <token>"');
+      console.error('  6. Copy the token (starts with "eyJhbG...")');
+      process.exit(1);
+    }
+    return token;
+  };
+  program2.command("backup").description("Download all conversations").option("-t, --token <token>", "Access token (or CHATGPT_TOKEN env)").option("-o, --output <dir>", "Output directory", "./chatgpt-export").option("--concurrency <n>", "Parallel downloads", (v) => parseInt(v, 10), 3).option("--delay <ms>", "Delay between requests in ms", (v) => parseInt(v, 10), 500).option("--incremental", "Only download new/updated conversations", false).option("--project <name-or-id>", "Only backup conversations from a specific project").option("-v, --verbose", "Verbose logging", false).action(async (options) => {
+    const token = getToken(options);
+    await backupCommand({
+      token,
+      output: options.output,
+      concurrency: options.concurrency,
+      delay: options.delay,
+      incremental: options.incremental,
+      verbose: options.verbose,
+      project: options.project
+    });
+  });
+  program2.command("list").description("List conversations without downloading").option("-t, --token <token>", "Access token (or CHATGPT_TOKEN env)").option("--delay <ms>", "Delay between requests in ms", (v) => parseInt(v, 10), 500).option("--project <name-or-id>", "List conversations from a specific project").option("-v, --verbose", "Verbose logging", false).option("--json", "Output as JSON", false).action(async (options) => {
+    const token = getToken(options);
+    await listCommand({
+      token,
+      delay: options.delay,
+      verbose: options.verbose,
+      json: options.json,
+      project: options.project
+    });
+  });
+  program2.command("projects").description("List all projects").option("-t, --token <token>", "Access token (or CHATGPT_TOKEN env)").option("-v, --verbose", "Verbose logging", false).option("--json", "Output as JSON", false).action(async (options) => {
+    const token = getToken(options);
+    await projectsCommand({
+      token,
+      verbose: options.verbose,
+      json: options.json
+    });
+  });
+  return program2;
+}
+
+// src/index.ts
+process.on("SIGINT", () => process.exit(130));
+var program = createCli();
+program.parse();

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "chatgpt-exporter",
+  "version": "1.0.0",
+  "description": "CLI tool to export ChatGPT conversations",
+  "license": "MIT",
+  "author": "Rodrigo Fernández",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "chatgpt-exporter": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FdezRomero/chatgpt-export.git"
+  },
+  "keywords": [
+    "chatgpt",
+    "backup",
+    "export",
+    "cli",
+    "markdown"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "cli-progress": "^3.12.0",
+    "commander": "^14.0.3",
+    "ora": "^9.3.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/cli-progress": "^3.11.5",
+    "@types/node": "^25.3.0",
+    "tsup": "^8.1.0",
+    "tsx": "^4.15.0",
+    "typescript": "^5.4.5"
+  }
+}