@payload-cc/payload-collection-cli 1.2.0 → 1.3.1

package/README.md

@@ -1,8 +1,35 @@
 # payload-collection-cli
 
-Functional CLI for Payload 3.0 collection management.
+[![CI](https://github.com/payload-cc/payload-collection-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/payload-cc/payload-collection-cli/actions/workflows/ci.yml)
+[![NPM Version](https://img.shields.io/npm/v/@payload-cc/payload-collection-cli)](https://www.npmjs.com/package/@payload-cc/payload-collection-cli)
+[![License](https://img.shields.io/github/license/payload-cc/payload-collection-cli)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-VitePress-blue)](https://payload-cc.github.io/payload-collection-cli/)
 
-Allows for magical, easy-to-use bulk imports, updates, deletions and operations on Payload CMS collections using simple JSONLines or JSON files, with automatic relation resolution.
+**The missing CLI for Payload 3.0. Manage collections without writing boilerplate scripts.**
+
+<p align="center">
+  <img src="docs/public/logo.png" alt="Payload Collection CLI Logo" width="200"/>
+</p>
+
+<p align="center">
+  🚀 <strong><a href="https://payload-cc.github.io/payload-collection-cli/">Official Guide</a></strong>
+  &nbsp;&nbsp;•&nbsp;&nbsp;
+  🤖 <strong><a href="https://payload-cc.github.io/payload-collection-cli/ai.html">AI Context Page</a></strong>
+</p>
+
+---
+
+## Why?
+
+Payload 3.0 is powerful, but performing simple data operations often requires writing one-off scripts. **payload-collection-cli** turns your terminal into a direct interface for your collections, supporting intelligent relation lookups by name/slug instead of cryptic IDs.
+
+## Features
+
+- ⚡️ **Zero Scripting:** Run CRUD operations directly from your terminal.
+- 🔍 **Relation Lookup:** Resolve relationships using `name`, `email`, or `slug`.
+- 📄 **Batch Processing:** Support for both JSON strings and JSONLines (`.jsonl`) files.
+- ⚙️ **Configurable:** Define your lookup logic in a simple external config.
+- 🛡 **Native Performance:** Uses Local API to ensure all Hooks and Validations run.
 
 ## Installation
 
@@ -17,7 +44,7 @@ You can immediately start using the commands without any configuration for basic
 
 **Command Syntax**:
 ```bash
-npx @payload-cc/payload-collection-cli [-c config-file] <collection-slug> <operation> <file or string>
+npx @payload-cc/payload-collection-cli [options] <collection-slug> <operation> <file or string>
 ```
 
 **Examples**:
@@ -39,33 +66,8 @@ npx @payload-cc/payload-collection-cli -c ./my-map.config.ts users upsert data.j
 - `upsert`: Update if existing, create if not.
 
 ## Specifications & FAQ
-For detailed behavior specifications (such as how identifier lookups work strictly during upserts, updates, and deletes), please refer to the [Specifications & FAQ](docs/references/specs_detail.md).
-
-## Configuration (Optional)
-
-### Relation Mappings (`payload-collection-cli.config.ts`)
-By default, Payload relations require you to provide target document IDs (e.g., ObjectIDs or numeric IDs). The CLI can magically resolve these relations by searching for human-readable fields instead.
-
-**Example Scenario**:
-Assume your `posts` collection has a relationship field named `author` that references the `users` collection. Instead of manually finding and hard-coding the user's database ID, you want to simply provide their email address.
-
-Create a `payload-collection-cli.config.ts` in your Payload project root (or pass it via `-c`) to define the `lookupField` for the `users` collection:
-
-```typescript
-export const cliConfig = {
-  mappings: {
-    users: {
-      lookupField: 'email',
-      onNotFound: 'error',
-    },
-    posts: {
-      lookupField: 'slug'
-    }
-  }
-}
-```
 
-Now, when you supply an `author: "user@example.com"` property to a `posts` collection insertion, the CLI will intercept this relationship, look up the `users` collection by the `email` field, and automatically replace the email string with the actual database ID before inserting!
+For detailed configuration options (including `package.json` defaults, relation mappings, `onNotFound` behaviors, and cross-file imports), please refer to the [Specifications & FAQ](docs/references/specs_detail.md).
 
 ## Development & CI/CD
 

package/dist/bin.cjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/bin.ts
+var import_payload = require("payload");
+var import_jiti = require("jiti");
+var import_path2 = __toESM(require("path"), 1);
+var import_fs2 = __toESM(require("fs"), 1);
+var import_yargs = __toESM(require("yargs/yargs"), 1);
+var import_helpers = require("yargs/helpers");
+var import_zod = require("zod");
+
+// src/executor.ts
+var import_fs = __toESM(require("fs"), 1);
+var import_readline = __toESM(require("readline"), 1);
+var import_path = __toESM(require("path"), 1);
+
+// src/resolver.ts
+async function resolveRelations(payload, collectionSlug, data, config) {
+  const collection = payload.collections[collectionSlug];
+  if (!collection) throw new Error(`Collection "${collectionSlug}" not found.`);
+  const resolved = { ...data };
+  const mappingConfig = config.mappings[collectionSlug];
+  if (mappingConfig?.defaults) {
+    for (const [k, v] of Object.entries(mappingConfig.defaults)) {
+      if (resolved[k] === void 0 || resolved[k] === null) {
+        resolved[k] = v;
+      }
+    }
+  }
+  for (const field of collection.config.fields) {
+    if (field.type === "relationship" && resolved[field.name]) {
+      const relationTo = Array.isArray(field.relationTo) ? field.relationTo[0] : field.relationTo;
+      const mapping = config.mappings[relationTo];
+      if (!mapping) continue;
+      const rawValue = resolved[field.name];
+      const isArray = Array.isArray(rawValue);
+      const values = isArray ? rawValue : [rawValue];
+      const resolvedIds = [];
+      for (const val of values) {
+        if (typeof val === "string" && val.length < 24) {
+          const found = await payload.find({
+            collection: relationTo,
+            where: { [mapping.lookupField]: { equals: val } },
+            limit: 1
+          });
+          if (found.docs.length > 0) {
+            resolvedIds.push(found.docs[0].id);
+          } else if (mapping.onNotFound === "create") {
+            const created = await payload.create({
+              collection: relationTo,
+              data: { [mapping.lookupField]: val }
+            });
+            resolvedIds.push(created.id);
+          } else if (mapping.onNotFound === "error") {
+            throw new Error(`Relation not found: ${relationTo} (${mapping.lookupField}=${val})`);
+          } else {
+            resolvedIds.push(val);
+          }
+        } else {
+          resolvedIds.push(val);
+        }
+      }
+      resolved[field.name] = isArray ? resolvedIds : resolvedIds[0];
+    }
+  }
+  return resolved;
+}
+
+// src/executor.ts
+async function processSingle(payload, collection, action, data, config) {
+  const mapping = config.mappings[collection];
+  const lookupField = mapping?.lookupField || "id";
+  const resolved = await resolveRelations(payload, collection, data, config);
+  switch (action) {
+    case "create":
+      console.log(`\u{1F4DD} [executor] Creating record in "${collection}" with resolved data:`, JSON.stringify(resolved, null, 2));
+      return await payload.create({ collection, data: resolved });
+    case "upsert":
+      if (data[lookupField] === void 0) {
+        throw new Error(`[upsert] Missing lookup field '${lookupField}' in data. Cannot perform upsert.`);
+      }
+      const existingUpsert = await payload.find({
+        collection,
+        where: { [lookupField]: { equals: data[lookupField] } }
+      });
+      if (existingUpsert.docs.length > 0) {
+        return await payload.update({ collection, id: existingUpsert.docs[0].id, data: resolved });
+      }
+      return await payload.create({ collection, data: resolved });
+    case "update":
+      if (data[lookupField] === void 0) {
+        throw new Error(`[update] Missing lookup field '${lookupField}' in data. Cannot perform update.`);
+      }
+      return await payload.update({
+        collection,
+        where: { [lookupField]: { equals: data[lookupField] } },
+        data: resolved
+      });
+    case "delete":
+      const delVal = typeof data === "object" ? data[lookupField] : data;
+      if (delVal === void 0) {
+        throw new Error(`[delete] Missing lookup field '${lookupField}' in action. Cannot perform delete.`);
+      }
+      return await payload.delete({
+        collection,
+        where: { [lookupField]: { equals: delVal } }
+      });
+    default:
+      throw new Error(`Unsupported action: ${action}`);
+  }
+}
+async function execute(payload, collection, action, input, config) {
+  if (input.endsWith(".jsonl")) {
+    const filePath = import_path.default.resolve(process.cwd(), input);
+    const rl = import_readline.default.createInterface({ input: import_fs.default.createReadStream(filePath) });
+    for await (const line of rl) {
+      if (line.trim()) await processSingle(payload, collection, action, JSON.parse(line), config);
+    }
+    return { status: "bulk success" };
+  }
+  return await processSingle(payload, collection, action, JSON.parse(input), config);
+}
+
+// src/bin.ts
+var jiti = (0, import_jiti.createJiti)(importMetaUrl);
+var MappingConfigSchema = import_zod.z.object({
+  lookupField: import_zod.z.string().default("id"),
+  onNotFound: import_zod.z.enum(["error", "ignore", "create"]).default("error"),
+  defaults: import_zod.z.record(import_zod.z.string(), import_zod.z.any()).optional()
+});
+var CLIConfigSchema = import_zod.z.object({
+  mappings: import_zod.z.record(import_zod.z.string(), MappingConfigSchema).default({})
+});
+async function run() {
+  console.log("\u{1F3C1} Starting CLI...");
+  const root = process.cwd();
+  const argv = await (0, import_yargs.default)((0, import_helpers.hideBin)(process.argv)).usage("Usage: $0 [options] <collection-slug> <operation> <file or string>").options({
+    "config-file": {
+      alias: "c",
+      type: "string",
+      describe: "Path to a configuration file (named export required)."
+    },
+    "config-json": {
+      alias: "j",
+      type: "string",
+      describe: "Inline JSON string for configuration."
+    },
+    "config-export-name": {
+      alias: "n",
+      type: "string",
+      describe: "The name of the export to use from the configuration file.",
+      default: "cliConfig"
+    }
+  }).pkgConf("payload-collection-cli").demandCommand(3, "Collection slug, operation, and input are required.").help().parseSync();
+  console.log("\u{1F4CA} Parsed arguments:", JSON.stringify(argv, null, 2));
+  const { configFile, configJson, configExportName, _: [collection, action, input] } = argv;
+  let rawConfig = { mappings: {} };
+  if (configJson) {
+    try {
+      rawConfig = typeof configJson === "string" ? JSON.parse(configJson) : configJson;
+    } catch (err) {
+      console.error("\u274C Error: Failed to parse inline JSON config:", err);
+      process.exit(1);
+    }
+  } else if (configFile) {
+    const customConfigPath = import_path2.default.resolve(root, configFile);
+    if (!import_fs2.default.existsSync(customConfigPath)) {
+      console.error(`\u274C Error: Config file not found at ${customConfigPath}`);
+      process.exit(1);
+    }
+    const imported = await jiti.import(customConfigPath);
+    if (imported[configExportName]) {
+      rawConfig = imported[configExportName];
+    } else {
+      console.error(`\u274C Error: Named export "${configExportName}" not found in ${configFile}`);
+      process.exit(1);
+    }
+  }
+  const validation = CLIConfigSchema.safeParse(rawConfig);
+  if (!validation.success) {
+    console.error("\u274C Error: Invalid configuration structure:");
+    validation.error.issues.forEach((issue) => {
+      console.error(`  - [${issue.path.join(".")}] ${issue.message}`);
+    });
+    process.exit(1);
+  }
+  const cliConfig = validation.data;
+  const configPath = [
+    import_path2.default.resolve(root, "src/payload.config.ts"),
+    import_path2.default.resolve(root, "payload.config.ts")
+  ].find((p) => import_fs2.default.existsSync(p));
+  if (!configPath) {
+    console.error("\u274C Error: payload.config.ts not found.");
+    process.exit(1);
+  }
+  console.log(`\u{1F4D6} Loading payload config from: ${configPath}`);
+  const { default: payloadConfig } = await jiti.import(configPath);
+  const payload = await (0, import_payload.getPayload)({ config: payloadConfig });
+  console.log("\u2705 Connected to Payload");
+  try {
+    const result = await execute(payload, collection, action, input, cliConfig);
+    console.log("\u2728 Operation successful");
+  } catch (err) {
+    console.error("\u274C Error:", err.message);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+run().catch((err) => {
+  console.error("\u274C Fatal Error:", err.message);
+  process.exit(1);
+});

package/dist/bin.js

@@ -1,192 +1,91 @@
 #!/usr/bin/env node
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-
-// node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
-var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
-var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+import {
+  execute
+} from "./chunk-IU4EF26D.js";
 
 // src/bin.ts
-var import_payload = require("payload");
-var import_jiti = require("jiti");
-var import_path2 = __toESM(require("path"));
-
-// src/executor.ts
-var import_fs = __toESM(require("fs"));
-var import_readline = __toESM(require("readline"));
-var import_path = __toESM(require("path"));
-
-// src/resolver.ts
-async function resolveRelations(payload, collectionSlug, data, config) {
-  const collection = payload.collections[collectionSlug];
-  if (!collection) throw new Error(`Collection "${collectionSlug}" not found.`);
-  const resolved = { ...data };
-  const mappingConfig = config.mappings[collectionSlug];
-  if (mappingConfig?.defaults) {
-    for (const [k, v] of Object.entries(mappingConfig.defaults)) {
-      if (resolved[k] === void 0 || resolved[k] === null) {
-        resolved[k] = v;
-      }
-    }
-  }
-  for (const field of collection.config.fields) {
-    if (field.type === "relationship" && resolved[field.name]) {
-      const relationTo = Array.isArray(field.relationTo) ? field.relationTo[0] : field.relationTo;
-      const mapping = config.mappings[relationTo];
-      if (!mapping) continue;
-      const rawValue = resolved[field.name];
-      const isArray = Array.isArray(rawValue);
-      const values = isArray ? rawValue : [rawValue];
-      const resolvedIds = [];
-      for (const val of values) {
-        if (typeof val === "string" && val.length < 24) {
-          const found = await payload.find({
-            collection: relationTo,
-            where: { [mapping.lookupField]: { equals: val } },
-            limit: 1
-          });
-          if (found.docs.length > 0) {
-            resolvedIds.push(found.docs[0].id);
-          } else if (mapping.onNotFound === "create") {
-            const created = await payload.create({
-              collection: relationTo,
-              data: { [mapping.lookupField]: val }
-            });
-            resolvedIds.push(created.id);
-          } else if (mapping.onNotFound === "error") {
-            throw new Error(`Relation not found: ${relationTo} (${mapping.lookupField}=${val})`);
-          } else {
-            resolvedIds.push(val);
-          }
-        } else {
-          resolvedIds.push(val);
-        }
-      }
-      resolved[field.name] = isArray ? resolvedIds : resolvedIds[0];
+import { getPayload } from "payload";
+import { createJiti } from "jiti";
+import path from "path";
+import fs from "fs";
+import yargs from "yargs/yargs";
+import { hideBin } from "yargs/helpers";
+import { z } from "zod";
+var jiti = createJiti(import.meta.url);
+var MappingConfigSchema = z.object({
+  lookupField: z.string().default("id"),
+  onNotFound: z.enum(["error", "ignore", "create"]).default("error"),
+  defaults: z.record(z.string(), z.any()).optional()
+});
+var CLIConfigSchema = z.object({
+  mappings: z.record(z.string(), MappingConfigSchema).default({})
+});
+async function run() {
+  console.log("\u{1F3C1} Starting CLI...");
+  const root = process.cwd();
+  const argv = await yargs(hideBin(process.argv)).usage("Usage: $0 [options] <collection-slug> <operation> <file or string>").options({
+    "config-file": {
+      alias: "c",
+      type: "string",
+      describe: "Path to a configuration file (named export required)."
+    },
+    "config-json": {
+      alias: "j",
+      type: "string",
+      describe: "Inline JSON string for configuration."
+    },
+    "config-export-name": {
+      alias: "n",
+      type: "string",
+      describe: "The name of the export to use from the configuration file.",
+      default: "cliConfig"
     }
-  }
-  return resolved;
-}
-
-// src/executor.ts
-async function processSingle(payload, collection, action, data, config) {
-  const mapping = config.mappings[collection];
-  const lookupField = mapping?.lookupField || "id";
-  const resolved = await resolveRelations(payload, collection, data, config);
-  switch (action) {
-    case "create":
-      return await payload.create({ collection, data: resolved });
-    case "upsert":
-      if (data[lookupField] === void 0) {
-        throw new Error(`[upsert] Missing lookup field '${lookupField}' in data. Cannot perform upsert.`);
-      }
-      const existingUpsert = await payload.find({
-        collection,
-        where: { [lookupField]: { equals: data[lookupField] } }
-      });
-      if (existingUpsert.docs.length > 0) {
-        return await payload.update({ collection, id: existingUpsert.docs[0].id, data: resolved });
-      }
-      return await payload.create({ collection, data: resolved });
-    case "update":
-      if (data[lookupField] === void 0) {
-        throw new Error(`[update] Missing lookup field '${lookupField}' in data. Cannot perform update.`);
-      }
-      return await payload.update({
-        collection,
-        where: { [lookupField]: { equals: data[lookupField] } },
-        data: resolved
-      });
-    case "delete":
-      const delVal = typeof data === "object" ? data[lookupField] : data;
-      if (delVal === void 0) {
-        throw new Error(`[delete] Missing lookup field '${lookupField}' in action. Cannot perform delete.`);
-      }
-      return await payload.delete({
-        collection,
-        where: { [lookupField]: { equals: delVal } }
-      });
-    default:
-      throw new Error(`Unsupported action: ${action}`);
-  }
-}
-async function execute(payload, collection, action, input, config) {
-  if (input.endsWith(".jsonl")) {
-    const filePath = import_path.default.resolve(process.cwd(), input);
-    const rl = import_readline.default.createInterface({ input: import_fs.default.createReadStream(filePath) });
-    for await (const line of rl) {
-      if (line.trim()) await processSingle(payload, collection, action, JSON.parse(line), config);
+  }).pkgConf("payload-collection-cli").demandCommand(3, "Collection slug, operation, and input are required.").help().parseSync();
+  console.log("\u{1F4CA} Parsed arguments:", JSON.stringify(argv, null, 2));
+  const { configFile, configJson, configExportName, _: [collection, action, input] } = argv;
+  let rawConfig = { mappings: {} };
+  if (configJson) {
+    try {
+      rawConfig = typeof configJson === "string" ? JSON.parse(configJson) : configJson;
+    } catch (err) {
+      console.error("\u274C Error: Failed to parse inline JSON config:", err);
+      process.exit(1);
     }
-    return { status: "bulk success" };
-  }
-  return await processSingle(payload, collection, action, JSON.parse(input), config);
-}
-
-// src/bin.ts
-var jiti = (0, import_jiti.createJiti)(importMetaUrl);
-async function run() {
-  const args = process.argv.slice(2);
-  let configOptIdx = args.indexOf("-c");
-  if (configOptIdx === -1) configOptIdx = args.indexOf("--config");
-  let cliConfig = { mappings: {} };
-  if (configOptIdx !== -1) {
-    if (args.length <= configOptIdx + 1) {
-      console.error("\u274C Error: Missing option after --config parameter.");
+  } else if (configFile) {
+    const customConfigPath = path.resolve(root, configFile);
+    if (!fs.existsSync(customConfigPath)) {
+      console.error(`\u274C Error: Config file not found at ${customConfigPath}`);
       process.exit(1);
     }
-    const val = args[configOptIdx + 1];
-    args.splice(configOptIdx, 2);
-    if (val.trim().startsWith("{")) {
-      try {
-        cliConfig = JSON.parse(val);
-      } catch (err) {
-        console.error("\u274C Error: Failed to parse inline JSON config:", err);
-        process.exit(1);
-      }
+    const imported = await jiti.import(customConfigPath);
+    if (imported[configExportName]) {
+      rawConfig = imported[configExportName];
     } else {
-      const customConfigPath = import_path2.default.resolve(process.cwd(), val);
-      if (!require("fs").existsSync(customConfigPath)) {
-        console.error(`\u274C Error: Config file not found at ${customConfigPath}`);
-        process.exit(1);
-      }
-      const imported = await jiti.import(customConfigPath);
-      cliConfig = imported.cliConfig || imported.default || cliConfig;
+      console.error(`\u274C Error: Named export "${configExportName}" not found in ${configFile}`);
+      process.exit(1);
     }
   }
-  const [collection, action, input] = args;
-  const root = process.cwd();
-  if (!collection || !action || !input) {
-    console.log("Usage: payload-collection-cli [-c path] <collection> <action> <json|file.jsonl>");
+  const validation = CLIConfigSchema.safeParse(rawConfig);
+  if (!validation.success) {
+    console.error("\u274C Error: Invalid configuration structure:");
+    validation.error.issues.forEach((issue) => {
+      console.error(`  - [${issue.path.join(".")}] ${issue.message}`);
+    });
     process.exit(1);
   }
+  const cliConfig = validation.data;
   const configPath = [
-    import_path2.default.resolve(root, "src/payload.config.ts"),
-    import_path2.default.resolve(root, "payload.config.ts")
-  ].find((p) => require("fs").existsSync(p));
-  if (!configPath) throw new Error("payload.config.ts not found.");
+    path.resolve(root, "src/payload.config.ts"),
+    path.resolve(root, "payload.config.ts")
+  ].find((p) => fs.existsSync(p));
+  if (!configPath) {
+    console.error("\u274C Error: payload.config.ts not found.");
+    process.exit(1);
+  }
+  console.log(`\u{1F4D6} Loading payload config from: ${configPath}`);
   const { default: payloadConfig } = await jiti.import(configPath);
-  const payload = await (0, import_payload.getPayload)({ config: payloadConfig });
+  const payload = await getPayload({ config: payloadConfig });
+  console.log("\u2705 Connected to Payload");
   try {
     const result = await execute(payload, collection, action, input, cliConfig);
     console.log("\u2728 Operation successful");
@@ -196,4 +95,7 @@ async function run() {
   }
   process.exit(0);
 }
-run();
+run().catch((err) => {
+  console.error("\u274C Fatal Error:", err.message);
+  process.exit(1);
+});

package/dist/{chunk-RIXWYITK.mjs → chunk-IU4EF26D.js}

@@ -1,10 +1,3 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
 // src/resolver.ts
 async function resolveRelations(payload, collectionSlug, data, config) {
   const collection = payload.collections[collectionSlug];
@@ -67,6 +60,7 @@ async function processSingle(payload, collection, action, data, config) {
   const resolved = await resolveRelations(payload, collection, data, config);
   switch (action) {
     case "create":
+      console.log(`\u{1F4DD} [executor] Creating record in "${collection}" with resolved data:`, JSON.stringify(resolved, null, 2));
       return await payload.create({ collection, data: resolved });
     case "upsert":
       if (data[lookupField] === void 0) {
@@ -115,7 +109,6 @@ async function execute(payload, collection, action, input, config) {
 }
 
 export {
-  __require,
   resolveRelations,
   execute
 };

package/dist/index.cjs

@@ -0,0 +1,151 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  execute: () => execute,
+  resolveRelations: () => resolveRelations
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/resolver.ts
+async function resolveRelations(payload, collectionSlug, data, config) {
+  const collection = payload.collections[collectionSlug];
+  if (!collection) throw new Error(`Collection "${collectionSlug}" not found.`);
+  const resolved = { ...data };
+  const mappingConfig = config.mappings[collectionSlug];
+  if (mappingConfig?.defaults) {
+    for (const [k, v] of Object.entries(mappingConfig.defaults)) {
+      if (resolved[k] === void 0 || resolved[k] === null) {
+        resolved[k] = v;
+      }
+    }
+  }
+  for (const field of collection.config.fields) {
+    if (field.type === "relationship" && resolved[field.name]) {
+      const relationTo = Array.isArray(field.relationTo) ? field.relationTo[0] : field.relationTo;
+      const mapping = config.mappings[relationTo];
+      if (!mapping) continue;
+      const rawValue = resolved[field.name];
+      const isArray = Array.isArray(rawValue);
+      const values = isArray ? rawValue : [rawValue];
+      const resolvedIds = [];
+      for (const val of values) {
+        if (typeof val === "string" && val.length < 24) {
+          const found = await payload.find({
+            collection: relationTo,
+            where: { [mapping.lookupField]: { equals: val } },
+            limit: 1
+          });
+          if (found.docs.length > 0) {
+            resolvedIds.push(found.docs[0].id);
+          } else if (mapping.onNotFound === "create") {
+            const created = await payload.create({
+              collection: relationTo,
+              data: { [mapping.lookupField]: val }
+            });
+            resolvedIds.push(created.id);
+          } else if (mapping.onNotFound === "error") {
+            throw new Error(`Relation not found: ${relationTo} (${mapping.lookupField}=${val})`);
+          } else {
+            resolvedIds.push(val);
+          }
+        } else {
+          resolvedIds.push(val);
+        }
+      }
+      resolved[field.name] = isArray ? resolvedIds : resolvedIds[0];
+    }
+  }
+  return resolved;
+}
+
+// src/executor.ts
+var import_fs = __toESM(require("fs"), 1);
+var import_readline = __toESM(require("readline"), 1);
+var import_path = __toESM(require("path"), 1);
+async function processSingle(payload, collection, action, data, config) {
+  const mapping = config.mappings[collection];
+  const lookupField = mapping?.lookupField || "id";
+  const resolved = await resolveRelations(payload, collection, data, config);
+  switch (action) {
+    case "create":
+      console.log(`\u{1F4DD} [executor] Creating record in "${collection}" with resolved data:`, JSON.stringify(resolved, null, 2));
+      return await payload.create({ collection, data: resolved });
+    case "upsert":
+      if (data[lookupField] === void 0) {
+        throw new Error(`[upsert] Missing lookup field '${lookupField}' in data. Cannot perform upsert.`);
+      }
+      const existingUpsert = await payload.find({
+        collection,
+        where: { [lookupField]: { equals: data[lookupField] } }
+      });
+      if (existingUpsert.docs.length > 0) {
+        return await payload.update({ collection, id: existingUpsert.docs[0].id, data: resolved });
+      }
+      return await payload.create({ collection, data: resolved });
+    case "update":
+      if (data[lookupField] === void 0) {
+        throw new Error(`[update] Missing lookup field '${lookupField}' in data. Cannot perform update.`);
+      }
+      return await payload.update({
+        collection,
+        where: { [lookupField]: { equals: data[lookupField] } },
+        data: resolved
+      });
+    case "delete":
+      const delVal = typeof data === "object" ? data[lookupField] : data;
+      if (delVal === void 0) {
+        throw new Error(`[delete] Missing lookup field '${lookupField}' in action. Cannot perform delete.`);
+      }
+      return await payload.delete({
+        collection,
+        where: { [lookupField]: { equals: delVal } }
+      });
+    default:
+      throw new Error(`Unsupported action: ${action}`);
+  }
+}
+async function execute(payload, collection, action, input, config) {
+  if (input.endsWith(".jsonl")) {
+    const filePath = import_path.default.resolve(process.cwd(), input);
+    const rl = import_readline.default.createInterface({ input: import_fs.default.createReadStream(filePath) });
+    for await (const line of rl) {
+      if (line.trim()) await processSingle(payload, collection, action, JSON.parse(line), config);
+    }
+    return { status: "bulk success" };
+  }
+  return await processSingle(payload, collection, action, JSON.parse(input), config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  execute,
+  resolveRelations
+});

package/dist/{index.d.mts → index.d.cts}

@@ -3,11 +3,11 @@ import { Payload } from 'payload';
 
 interface MappingConfig {
     lookupField: string;
-    onNotFound?: 'error' | 'ignore' | 'create';
+    onNotFound: 'error' | 'ignore' | 'create';
     defaults?: Record<string, any>;
 }
 interface CLIConfig {
-    mappings: Record<string, MappingConfig>;
+    mappings: Record<string, MappingConfig | undefined>;
 }
 type Action = 'create' | 'update' | 'delete' | 'find' | 'upsert';
 interface CommandArgs {

package/dist/index.d.ts

@@ -3,11 +3,11 @@ import { Payload } from 'payload';
 
 interface MappingConfig {
     lookupField: string;
-    onNotFound?: 'error' | 'ignore' | 'create';
+    onNotFound: 'error' | 'ignore' | 'create';
     defaults?: Record<string, any>;
 }
 interface CLIConfig {
-    mappings: Record<string, MappingConfig>;
+    mappings: Record<string, MappingConfig | undefined>;
 }
 type Action = 'create' | 'update' | 'delete' | 'find' | 'upsert';
 interface CommandArgs {

package/dist/index.js

@@ -1,150 +1,8 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  execute: () => execute,
-  resolveRelations: () => resolveRelations
-});
-module.exports = __toCommonJS(index_exports);
-
-// src/resolver.ts
-async function resolveRelations(payload, collectionSlug, data, config) {
-  const collection = payload.collections[collectionSlug];
-  if (!collection) throw new Error(`Collection "${collectionSlug}" not found.`);
-  const resolved = { ...data };
-  const mappingConfig = config.mappings[collectionSlug];
-  if (mappingConfig?.defaults) {
-    for (const [k, v] of Object.entries(mappingConfig.defaults)) {
-      if (resolved[k] === void 0 || resolved[k] === null) {
-        resolved[k] = v;
-      }
-    }
-  }
-  for (const field of collection.config.fields) {
-    if (field.type === "relationship" && resolved[field.name]) {
-      const relationTo = Array.isArray(field.relationTo) ? field.relationTo[0] : field.relationTo;
-      const mapping = config.mappings[relationTo];
-      if (!mapping) continue;
-      const rawValue = resolved[field.name];
-      const isArray = Array.isArray(rawValue);
-      const values = isArray ? rawValue : [rawValue];
-      const resolvedIds = [];
-      for (const val of values) {
-        if (typeof val === "string" && val.length < 24) {
-          const found = await payload.find({
-            collection: relationTo,
-            where: { [mapping.lookupField]: { equals: val } },
-            limit: 1
-          });
-          if (found.docs.length > 0) {
-            resolvedIds.push(found.docs[0].id);
-          } else if (mapping.onNotFound === "create") {
-            const created = await payload.create({
-              collection: relationTo,
-              data: { [mapping.lookupField]: val }
-            });
-            resolvedIds.push(created.id);
-          } else if (mapping.onNotFound === "error") {
-            throw new Error(`Relation not found: ${relationTo} (${mapping.lookupField}=${val})`);
-          } else {
-            resolvedIds.push(val);
-          }
-        } else {
-          resolvedIds.push(val);
-        }
-      }
-      resolved[field.name] = isArray ? resolvedIds : resolvedIds[0];
-    }
-  }
-  return resolved;
-}
-
-// src/executor.ts
-var import_fs = __toESM(require("fs"));
-var import_readline = __toESM(require("readline"));
-var import_path = __toESM(require("path"));
-async function processSingle(payload, collection, action, data, config) {
-  const mapping = config.mappings[collection];
-  const lookupField = mapping?.lookupField || "id";
-  const resolved = await resolveRelations(payload, collection, data, config);
-  switch (action) {
-    case "create":
-      return await payload.create({ collection, data: resolved });
-    case "upsert":
-      if (data[lookupField] === void 0) {
-        throw new Error(`[upsert] Missing lookup field '${lookupField}' in data. Cannot perform upsert.`);
-      }
-      const existingUpsert = await payload.find({
-        collection,
-        where: { [lookupField]: { equals: data[lookupField] } }
-      });
-      if (existingUpsert.docs.length > 0) {
-        return await payload.update({ collection, id: existingUpsert.docs[0].id, data: resolved });
-      }
-      return await payload.create({ collection, data: resolved });
-    case "update":
-      if (data[lookupField] === void 0) {
-        throw new Error(`[update] Missing lookup field '${lookupField}' in data. Cannot perform update.`);
-      }
-      return await payload.update({
-        collection,
-        where: { [lookupField]: { equals: data[lookupField] } },
-        data: resolved
-      });
-    case "delete":
-      const delVal = typeof data === "object" ? data[lookupField] : data;
-      if (delVal === void 0) {
-        throw new Error(`[delete] Missing lookup field '${lookupField}' in action. Cannot perform delete.`);
-      }
-      return await payload.delete({
-        collection,
-        where: { [lookupField]: { equals: delVal } }
-      });
-    default:
-      throw new Error(`Unsupported action: ${action}`);
-  }
-}
-async function execute(payload, collection, action, input, config) {
-  if (input.endsWith(".jsonl")) {
-    const filePath = import_path.default.resolve(process.cwd(), input);
-    const rl = import_readline.default.createInterface({ input: import_fs.default.createReadStream(filePath) });
-    for await (const line of rl) {
-      if (line.trim()) await processSingle(payload, collection, action, JSON.parse(line), config);
-    }
-    return { status: "bulk success" };
-  }
-  return await processSingle(payload, collection, action, JSON.parse(input), config);
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
+import {
   execute,
   resolveRelations
-});
+} from "./chunk-IU4EF26D.js";
+export {
+  execute,
+  resolveRelations
+};

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@payload-cc/payload-collection-cli",
-  "version": "1.2.0",
+  "version": "1.3.1",
+  "type": "module",
   "description": "Functional CLI for Payload 3.0 collection management",
   "repository": {
     "type": "git",
@@ -23,7 +24,10 @@
     "build": "tsup src/index.ts src/bin.ts --format cjs,esm --dts --clean --shims && chmod +x dist/bin.js",
     "release": "pnpm build && pnpm publish --access public",
     "test": "vitest run tests/*",
-    "test:e2e": "vitest run e2e-tests/scenarios/ --no-file-parallelism"
+    "test:e2e": "vitest run e2e-tests/scenarios/ --no-file-parallelism --test-timeout 300000",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "keywords": [
     "payload",
@@ -37,13 +41,17 @@
     "payload": "^3.0.0"
   },
   "dependencies": {
-    "jiti": "^2.6.1"
+    "jiti": "^2.6.1",
+    "yargs": "^18.0.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
-    "payload": "^3.79.1",
+    "@types/yargs": "^17.0.35",
+    "payload": "^3.80.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
+    "vitepress": "^1.6.4",
     "vitest": "^4.1.0"
   }
 }

package/dist/bin.mjs

@@ -1,63 +0,0 @@
-#!/usr/bin/env node
-import {
-  __require,
-  execute
-} from "./chunk-RIXWYITK.mjs";
-
-// src/bin.ts
-import { getPayload } from "payload";
-import { createJiti } from "jiti";
-import path from "path";
-var jiti = createJiti(import.meta.url);
-async function run() {
-  const args = process.argv.slice(2);
-  let configOptIdx = args.indexOf("-c");
-  if (configOptIdx === -1) configOptIdx = args.indexOf("--config");
-  let cliConfig = { mappings: {} };
-  if (configOptIdx !== -1) {
-    if (args.length <= configOptIdx + 1) {
-      console.error("\u274C Error: Missing option after --config parameter.");
-      process.exit(1);
-    }
-    const val = args[configOptIdx + 1];
-    args.splice(configOptIdx, 2);
-    if (val.trim().startsWith("{")) {
-      try {
-        cliConfig = JSON.parse(val);
-      } catch (err) {
-        console.error("\u274C Error: Failed to parse inline JSON config:", err);
-        process.exit(1);
-      }
-    } else {
-      const customConfigPath = path.resolve(process.cwd(), val);
-      if (!__require("fs").existsSync(customConfigPath)) {
-        console.error(`\u274C Error: Config file not found at ${customConfigPath}`);
-        process.exit(1);
-      }
-      const imported = await jiti.import(customConfigPath);
-      cliConfig = imported.cliConfig || imported.default || cliConfig;
-    }
-  }
-  const [collection, action, input] = args;
-  const root = process.cwd();
-  if (!collection || !action || !input) {
-    console.log("Usage: payload-collection-cli [-c path] <collection> <action> <json|file.jsonl>");
-    process.exit(1);
-  }
-  const configPath = [
-    path.resolve(root, "src/payload.config.ts"),
-    path.resolve(root, "payload.config.ts")
-  ].find((p) => __require("fs").existsSync(p));
-  if (!configPath) throw new Error("payload.config.ts not found.");
-  const { default: payloadConfig } = await jiti.import(configPath);
-  const payload = await getPayload({ config: payloadConfig });
-  try {
-    const result = await execute(payload, collection, action, input, cliConfig);
-    console.log("\u2728 Operation successful");
-  } catch (err) {
-    console.error("\u274C Error:", err.message);
-    process.exit(1);
-  }
-  process.exit(0);
-}
-run();

package/dist/index.mjs

@@ -1,8 +0,0 @@
-import {
-  execute,
-  resolveRelations
-} from "./chunk-RIXWYITK.mjs";
-export {
-  execute,
-  resolveRelations
-};