@wavyx/pdcli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `pdcli` are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/); versions follow
 [SemVer](https://semver.org/).
 
+## [0.4.0] - 2026-06-04
+
+### Added
+
+- `deal bulk-update` — update many deals at once by `--ids`, a Pipedrive
+  saved `--filter`, or ids piped on stdin. Paced sequentially inside the
+  rate-limit burst window, confirms before writing (`--yes` to skip),
+  `--dry-run` previews targets, partial failures are listed per deal and
+  exit 1.
+- `person import` / `org import` — bulk-create from CSV. Headers map to
+  fields, including custom fields by human name with option-label
+  resolution; `--dry-run` validates every row without writing.
+
+### Changed
+
+- CI actions bumped to checkout/setup-node v5.
+
 ## [0.3.0] - 2026-06-04
 
 ### Added

package/README.md

@@ -1,5 +1,9 @@
 # pdcli
 
+[![CI](https://github.com/wavyx/pdcli/actions/workflows/ci.yml/badge.svg)](https://github.com/wavyx/pdcli/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/wavyx/pdcli/branch/main/graph/badge.svg)](https://codecov.io/gh/wavyx/pdcli)
+[![npm](https://img.shields.io/npm/v/%40wavyx%2Fpdcli)](https://www.npmjs.com/package/@wavyx/pdcli)
+
 Command-line interface for [Pipedrive](https://www.pipedrive.com/) — fast, scriptable, built for terminals, CI pipelines, and AI agents.
 
 > Not affiliated with or endorsed by Pipedrive.
@@ -55,6 +59,16 @@ pdcli deal create --title "Sized" --field "Deal Size=Large" --field "Score=4.5"
 pdcli deal update 42 --body '{"probability":75}'   # raw JSON escape hatch
 ```
 
+## Bulk
+
+```bash
+pdcli deal bulk-update --filter 9 --stage 5            # saved filter → stage move
+pdcli deal bulk-update --ids 1,2,3 --status won --yes
+pdcli deal list --status open --jq '.[].id' | pdcli deal bulk-update --owner 42
+pdcli person import people.csv --dry-run               # CSV headers map to fields,
+pdcli person import people.csv                         # custom fields by name
+```
+
 ## Files, webhooks, backup
 
 ```bash

package/oclif.manifest.json

@@ -1724,6 +1724,191 @@
         "status.js"
       ]
     },
+    "deal:bulk-update": {
+      "aliases": [],
+      "args": {},
+      "description": "Update many deals at once (by --ids, a saved --filter, or ids piped on stdin)",
+      "examples": [
+        "<%= config.bin %> deal bulk-update --ids 1,2,3 --stage 5",
+        "<%= config.bin %> deal bulk-update --filter 9 --status won",
+        "<%= config.bin %> deal list --status open --jq '.[].id' | <%= config.bin %> deal bulk-update --owner 42",
+        "<%= config.bin %> deal bulk-update --filter 9 --stage 5 --dry-run"
+      ],
+      "flags": {
+        "output": {
+          "char": "o",
+          "description": "Output format",
+          "helpGroup": "GLOBAL",
+          "name": "output",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "table",
+            "json",
+            "yaml",
+            "csv"
+          ],
+          "type": "option"
+        },
+        "jq": {
+          "description": "jq expression to filter JSON output",
+          "helpGroup": "GLOBAL",
+          "name": "jq",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "fields": {
+          "description": "Comma-separated fields to display",
+          "helpGroup": "GLOBAL",
+          "name": "fields",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "profile": {
+          "description": "Named auth profile to use",
+          "env": "PDCLI_PROFILE",
+          "helpGroup": "GLOBAL",
+          "name": "profile",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "no-color": {
+          "description": "Disable color output",
+          "helpGroup": "GLOBAL",
+          "name": "no-color",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "verbose": {
+          "description": "Show detailed API request/response on errors",
+          "helpGroup": "GLOBAL",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "no-retry": {
+          "description": "Disable automatic retry on rate limits and 5xx errors",
+          "helpGroup": "GLOBAL",
+          "name": "no-retry",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "timeout": {
+          "description": "Request timeout in milliseconds",
+          "helpGroup": "GLOBAL",
+          "name": "timeout",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "limit": {
+          "description": "Maximum number of items to return (lists)",
+          "helpGroup": "GLOBAL",
+          "name": "limit",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "ids": {
+          "description": "Comma-separated deal IDs",
+          "exclusive": [
+            "filter"
+          ],
+          "name": "ids",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "filter": {
+          "description": "Pipedrive saved filter ID to select deals",
+          "exclusive": [
+            "ids"
+          ],
+          "name": "filter",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "stage": {
+          "description": "Move to stage ID",
+          "name": "stage",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "pipeline": {
+          "description": "Move to pipeline ID",
+          "name": "pipeline",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "status": {
+          "description": "Set status",
+          "name": "status",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "open",
+            "won",
+            "lost"
+          ],
+          "type": "option"
+        },
+        "owner": {
+          "description": "Assign owner (user) ID",
+          "name": "owner",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "field": {
+          "description": "Custom/standard field as \"Name=Value\" (repeatable)",
+          "name": "field",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "body": {
+          "description": "Raw JSON body to merge (flags win)",
+          "name": "body",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "dry-run": {
+          "description": "List the targets without updating anything",
+          "name": "dry-run",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Skip the confirmation prompt",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "deal:bulk-update",
+      "pluginAlias": "@wavyx/pdcli",
+      "pluginName": "@wavyx/pdcli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "deal",
+        "bulk-update.js"
+      ]
+    },
     "deal:create": {
       "aliases": [],
       "args": {},
@@ -5542,6 +5727,128 @@
         "get.js"
       ]
     },
+    "org:import": {
+      "aliases": [],
+      "args": {
+        "file": {
+          "description": "CSV file path",
+          "name": "file",
+          "required": true
+        }
+      },
+      "description": "Bulk-create organizations from a CSV (headers map to fields, custom fields by name)",
+      "examples": [
+        "<%= config.bin %> org import orgs.csv",
+        "<%= config.bin %> org import orgs.csv --dry-run"
+      ],
+      "flags": {
+        "output": {
+          "char": "o",
+          "description": "Output format",
+          "helpGroup": "GLOBAL",
+          "name": "output",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "table",
+            "json",
+            "yaml",
+            "csv"
+          ],
+          "type": "option"
+        },
+        "jq": {
+          "description": "jq expression to filter JSON output",
+          "helpGroup": "GLOBAL",
+          "name": "jq",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "fields": {
+          "description": "Comma-separated fields to display",
+          "helpGroup": "GLOBAL",
+          "name": "fields",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "profile": {
+          "description": "Named auth profile to use",
+          "env": "PDCLI_PROFILE",
+          "helpGroup": "GLOBAL",
+          "name": "profile",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "no-color": {
+          "description": "Disable color output",
+          "helpGroup": "GLOBAL",
+          "name": "no-color",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "verbose": {
+          "description": "Show detailed API request/response on errors",
+          "helpGroup": "GLOBAL",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "no-retry": {
+          "description": "Disable automatic retry on rate limits and 5xx errors",
+          "helpGroup": "GLOBAL",
+          "name": "no-retry",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "timeout": {
+          "description": "Request timeout in milliseconds",
+          "helpGroup": "GLOBAL",
+          "name": "timeout",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "limit": {
+          "description": "Maximum number of items to return (lists)",
+          "helpGroup": "GLOBAL",
+          "name": "limit",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "dry-run": {
+          "description": "Validate every row without creating anything",
+          "name": "dry-run",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Skip the confirmation prompt",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "org:import",
+      "pluginAlias": "@wavyx/pdcli",
+      "pluginName": "@wavyx/pdcli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "org",
+        "import.js"
+      ]
+    },
     "org:list": {
       "aliases": [],
       "args": {},
@@ -6169,6 +6476,128 @@
         "get.js"
       ]
     },
+    "person:import": {
+      "aliases": [],
+      "args": {
+        "file": {
+          "description": "CSV file path",
+          "name": "file",
+          "required": true
+        }
+      },
+      "description": "Bulk-create persons from a CSV (headers map to fields, custom fields by name)",
+      "examples": [
+        "<%= config.bin %> person import people.csv",
+        "<%= config.bin %> person import people.csv --dry-run"
+      ],
+      "flags": {
+        "output": {
+          "char": "o",
+          "description": "Output format",
+          "helpGroup": "GLOBAL",
+          "name": "output",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "table",
+            "json",
+            "yaml",
+            "csv"
+          ],
+          "type": "option"
+        },
+        "jq": {
+          "description": "jq expression to filter JSON output",
+          "helpGroup": "GLOBAL",
+          "name": "jq",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "fields": {
+          "description": "Comma-separated fields to display",
+          "helpGroup": "GLOBAL",
+          "name": "fields",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "profile": {
+          "description": "Named auth profile to use",
+          "env": "PDCLI_PROFILE",
+          "helpGroup": "GLOBAL",
+          "name": "profile",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "no-color": {
+          "description": "Disable color output",
+          "helpGroup": "GLOBAL",
+          "name": "no-color",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "verbose": {
+          "description": "Show detailed API request/response on errors",
+          "helpGroup": "GLOBAL",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "no-retry": {
+          "description": "Disable automatic retry on rate limits and 5xx errors",
+          "helpGroup": "GLOBAL",
+          "name": "no-retry",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "timeout": {
+          "description": "Request timeout in milliseconds",
+          "helpGroup": "GLOBAL",
+          "name": "timeout",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "limit": {
+          "description": "Maximum number of items to return (lists)",
+          "helpGroup": "GLOBAL",
+          "name": "limit",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "dry-run": {
+          "description": "Validate every row without creating anything",
+          "name": "dry-run",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Skip the confirmation prompt",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "person:import",
+      "pluginAlias": "@wavyx/pdcli",
+      "pluginName": "@wavyx/pdcli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "person",
+        "import.js"
+      ]
+    },
     "person:list": {
       "aliases": [],
       "args": {},
@@ -8329,19 +8758,12 @@
         "update.js"
       ]
     },
-    "stage:get": {
+    "user:me": {
       "aliases": [],
-      "args": {
-        "id": {
-          "description": "Stage ID",
-          "name": "id",
-          "required": true
-        }
-      },
-      "description": "Get a stage by ID",
+      "args": {},
+      "description": "Show the authenticated user",
       "examples": [
-        "<%= config.bin %> stage get 5",
-        "<%= config.bin %> stage get 5 --output json"
+        "<%= config.bin %> user me"
       ],
       "flags": {
         "output": {
@@ -8424,7 +8846,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "stage:get",
+      "id": "user:me",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -8434,17 +8856,23 @@
       "relativePath": [
         "src",
         "commands",
-        "stage",
-        "get.js"
+        "user",
+        "me.js"
       ]
     },
-    "stage:list": {
+    "stage:get": {
       "aliases": [],
-      "args": {},
-      "description": "List stages",
+      "args": {
+        "id": {
+          "description": "Stage ID",
+          "name": "id",
+          "required": true
+        }
+      },
+      "description": "Get a stage by ID",
       "examples": [
-        "<%= config.bin %> stage list",
-        "<%= config.bin %> stage list --pipeline 1 --output json"
+        "<%= config.bin %> stage get 5",
+        "<%= config.bin %> stage get 5 --output json"
       ],
       "flags": {
         "output": {
@@ -8523,18 +8951,11 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "pipeline": {
-          "description": "Filter by pipeline ID",
-          "name": "pipeline",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "stage:list",
+      "id": "stage:get",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -8545,15 +8966,16 @@
         "src",
         "commands",
         "stage",
-        "list.js"
+        "get.js"
       ]
     },
-    "user:me": {
+    "stage:list": {
       "aliases": [],
       "args": {},
-      "description": "Show the authenticated user",
+      "description": "List stages",
       "examples": [
-        "<%= config.bin %> user me"
+        "<%= config.bin %> stage list",
+        "<%= config.bin %> stage list --pipeline 1 --output json"
       ],
       "flags": {
         "output": {
@@ -8632,11 +9054,18 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "pipeline": {
+          "description": "Filter by pipeline ID",
+          "name": "pipeline",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "user:me",
+      "id": "stage:list",
       "pluginAlias": "@wavyx/pdcli",
       "pluginName": "@wavyx/pdcli",
       "pluginType": "core",
@@ -8646,8 +9075,8 @@
       "relativePath": [
         "src",
         "commands",
-        "user",
-        "me.js"
+        "stage",
+        "list.js"
       ]
     },
     "webhook:create": {
@@ -9051,5 +9480,5 @@
       ]
     }
   },
-  "version": "0.3.0"
+  "version": "0.4.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavyx/pdcli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "publishConfig": {
     "access": "public"
   },

package/src/commands/deal/bulk-update.js

@@ -0,0 +1,131 @@
+import { Flags } from '@oclif/core'
+import chalk from 'chalk'
+import ora from 'ora'
+import BaseCommand from '../../base-command.js'
+import { resolveTargets, bulkRun } from '../../lib/bulk.js'
+import { buildWriteBody } from '../../lib/input.js'
+import { defsForFields } from '../../lib/entity-view.js'
+import { confirmAction } from '../../lib/confirm.js'
+import { CliError } from '../../lib/errors.js'
+
+export default class DealBulkUpdateCommand extends BaseCommand {
+  static description =
+    'Update many deals at once (by --ids, a saved --filter, or ids piped on stdin)'
+
+  static examples = [
+    '<%= config.bin %> deal bulk-update --ids 1,2,3 --stage 5',
+    '<%= config.bin %> deal bulk-update --filter 9 --status won',
+    "<%= config.bin %> deal list --status open --jq '.[].id' | <%= config.bin %> deal bulk-update --owner 42",
+    '<%= config.bin %> deal bulk-update --filter 9 --stage 5 --dry-run',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    ids: Flags.string({
+      description: 'Comma-separated deal IDs',
+      exclusive: ['filter'],
+    }),
+    filter: Flags.integer({
+      description: 'Pipedrive saved filter ID to select deals',
+      exclusive: ['ids'],
+    }),
+    stage: Flags.integer({ description: 'Move to stage ID' }),
+    pipeline: Flags.integer({ description: 'Move to pipeline ID' }),
+    status: Flags.string({
+      description: 'Set status',
+      options: ['open', 'won', 'lost'],
+    }),
+    owner: Flags.integer({ description: 'Assign owner (user) ID' }),
+    field: Flags.string({
+      multiple: true,
+      description: 'Custom/standard field as "Name=Value" (repeatable)',
+    }),
+    body: Flags.string({ description: 'Raw JSON body to merge (flags win)' }),
+    'dry-run': Flags.boolean({
+      description: 'List the targets without updating anything',
+      default: false,
+    }),
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(DealBulkUpdateCommand)
+
+    const body = buildWriteBody({
+      typed: {
+        stage_id: flags.stage,
+        pipeline_id: flags.pipeline,
+        status: flags.status,
+        owner_id: flags.owner,
+      },
+      fields: flags.field,
+      rawBody: flags.body,
+      defs: await defsForFields(this, 'deal', flags.field),
+    })
+
+    if (Object.keys(body).length === 0) {
+      throw new CliError(
+        'Nothing to update — pass at least one change flag, --field, or --body',
+        { exitCode: 64 },
+      )
+    }
+
+    const targets = await resolveTargets(
+      { ids: flags.ids, filter: flags.filter },
+      this.apiClient,
+      '/api/v2/deals',
+    )
+
+    if (flags['dry-run']) {
+      this.log(
+        `Would update ${chalk.bold(targets.length)} deals: ${targets.join(', ')}`,
+      )
+      this.log(chalk.dim(`Change: ${JSON.stringify(body)}`))
+      return
+    }
+
+    const ok = await confirmAction(
+      `Update ${targets.length} deals with ${JSON.stringify(body)}?`,
+      flags.yes,
+    )
+    if (!ok) {
+      throw new CliError('Aborted', { exitCode: 1 })
+    }
+
+    const spinner = ora(`Updating ${targets.length} deals...`).start()
+    let summary
+    try {
+      summary = await bulkRun(
+        targets,
+        (id) => this.apiClient.patch(`/api/v2/deals/${id}`, { body }),
+        {
+          onProgress: (done, total) => {
+            spinner.text = `Updating deals ${done}/${total}`
+          },
+        },
+      )
+    } finally {
+      spinner.stop()
+    }
+
+    this.log(
+      chalk.green(
+        `Updated ${summary.succeeded.length}/${targets.length} deals`,
+      ),
+    )
+
+    if (summary.failed.length > 0) {
+      for (const { item, error } of summary.failed) {
+        this.log(chalk.red(`  ✘ deal ${item}: ${error}`))
+      }
+      throw new CliError(
+        `${summary.failed.length} of ${targets.length} updates failed`,
+        { exitCode: 1 },
+      )
+    }
+  }
+}

package/src/commands/org/import.js

@@ -0,0 +1,109 @@
+import { readFileSync } from 'node:fs'
+import { Args, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import ora from 'ora'
+import BaseCommand from '../../base-command.js'
+import { parseCsv } from '../../lib/csv-parse.js'
+import { prepareImportBodies } from '../../lib/import.js'
+import { bulkRun } from '../../lib/bulk.js'
+import { getFields } from '../../lib/fields.js'
+import { confirmAction } from '../../lib/confirm.js'
+import { CliError } from '../../lib/errors.js'
+
+const SPECIAL_COLUMNS = {
+  name: (typed, value) => {
+    typed.name = value
+  },
+  owner_id: (typed, value) => {
+    typed.owner_id = Number(value)
+  },
+}
+
+export default class OrgImportCommand extends BaseCommand {
+  static description =
+    'Bulk-create organizations from a CSV (headers map to fields, custom fields by name)'
+
+  static examples = [
+    '<%= config.bin %> org import orgs.csv',
+    '<%= config.bin %> org import orgs.csv --dry-run',
+  ]
+
+  static args = {
+    file: Args.string({ required: true, description: 'CSV file path' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    'dry-run': Flags.boolean({
+      description: 'Validate every row without creating anything',
+      default: false,
+    }),
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(OrgImportCommand)
+
+    const { headers, rows } = parseCsv(readFileSync(args.file, 'utf8'))
+    if (!headers.some((h) => h.toLowerCase() === 'name')) {
+      throw new CliError('CSV must include a "name" column', { exitCode: 64 })
+    }
+
+    const needsDefs = headers.some((h) => !(h.toLowerCase() in SPECIAL_COLUMNS))
+    const bodies = prepareImportBodies({
+      headers,
+      rows,
+      specialColumns: SPECIAL_COLUMNS,
+      defs: needsDefs ? await getFields(this.apiClient, 'org') : [],
+    })
+
+    if (flags['dry-run']) {
+      this.log(chalk.green(`${bodies.length} rows valid — nothing created`))
+      return
+    }
+
+    const ok = await confirmAction(
+      `Create ${bodies.length} organizations from ${args.file}?`,
+      flags.yes,
+    )
+    if (!ok) {
+      throw new CliError('Aborted', { exitCode: 1 })
+    }
+
+    const spinner = ora(`Importing ${bodies.length} organizations...`).start()
+    let summary
+    try {
+      summary = await bulkRun(
+        bodies,
+        (body) => this.apiClient.post('/api/v2/organizations', { body }),
+        {
+          onProgress: (done, total) => {
+            spinner.text = `Importing organizations ${done}/${total}`
+          },
+        },
+      )
+    } finally {
+      spinner.stop()
+    }
+
+    this.log(
+      chalk.green(
+        `Imported ${summary.succeeded.length}/${bodies.length} organizations`,
+      ),
+    )
+
+    if (summary.failed.length > 0) {
+      for (const { item, error } of summary.failed) {
+        this.log(chalk.red(`  ✘ ${item.name ?? '(unnamed)'}: ${error}`))
+      }
+      throw new CliError(
+        `${summary.failed.length} of ${bodies.length} rows failed`,
+        { exitCode: 1 },
+      )
+    }
+  }
+}

package/src/commands/person/import.js

@@ -0,0 +1,118 @@
+import { readFileSync } from 'node:fs'
+import { Args, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import ora from 'ora'
+import BaseCommand from '../../base-command.js'
+import { parseCsv } from '../../lib/csv-parse.js'
+import { prepareImportBodies } from '../../lib/import.js'
+import { bulkRun } from '../../lib/bulk.js'
+import { getFields } from '../../lib/fields.js'
+import { confirmAction } from '../../lib/confirm.js'
+import { CliError } from '../../lib/errors.js'
+
+const SPECIAL_COLUMNS = {
+  name: (typed, value) => {
+    typed.name = value
+  },
+  email: (typed, value) => {
+    typed.emails = [{ value, primary: true }]
+  },
+  phone: (typed, value) => {
+    typed.phones = [{ value, primary: true }]
+  },
+  org_id: (typed, value) => {
+    typed.org_id = Number(value)
+  },
+  owner_id: (typed, value) => {
+    typed.owner_id = Number(value)
+  },
+}
+
+export default class PersonImportCommand extends BaseCommand {
+  static description =
+    'Bulk-create persons from a CSV (headers map to fields, custom fields by name)'
+
+  static examples = [
+    '<%= config.bin %> person import people.csv',
+    '<%= config.bin %> person import people.csv --dry-run',
+  ]
+
+  static args = {
+    file: Args.string({ required: true, description: 'CSV file path' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    'dry-run': Flags.boolean({
+      description: 'Validate every row without creating anything',
+      default: false,
+    }),
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(PersonImportCommand)
+
+    const { headers, rows } = parseCsv(readFileSync(args.file, 'utf8'))
+    if (!headers.some((h) => h.toLowerCase() === 'name')) {
+      throw new CliError('CSV must include a "name" column', { exitCode: 64 })
+    }
+
+    const needsDefs = headers.some((h) => !(h.toLowerCase() in SPECIAL_COLUMNS))
+    const bodies = prepareImportBodies({
+      headers,
+      rows,
+      specialColumns: SPECIAL_COLUMNS,
+      defs: needsDefs ? await getFields(this.apiClient, 'person') : [],
+    })
+
+    if (flags['dry-run']) {
+      this.log(chalk.green(`${bodies.length} rows valid — nothing created`))
+      return
+    }
+
+    const ok = await confirmAction(
+      `Create ${bodies.length} persons from ${args.file}?`,
+      flags.yes,
+    )
+    if (!ok) {
+      throw new CliError('Aborted', { exitCode: 1 })
+    }
+
+    const spinner = ora(`Importing ${bodies.length} persons...`).start()
+    let summary
+    try {
+      summary = await bulkRun(
+        bodies,
+        (body) => this.apiClient.post('/api/v2/persons', { body }),
+        {
+          onProgress: (done, total) => {
+            spinner.text = `Importing persons ${done}/${total}`
+          },
+        },
+      )
+    } finally {
+      spinner.stop()
+    }
+
+    this.log(
+      chalk.green(
+        `Imported ${summary.succeeded.length}/${bodies.length} persons`,
+      ),
+    )
+
+    if (summary.failed.length > 0) {
+      for (const { item, error } of summary.failed) {
+        this.log(chalk.red(`  ✘ ${item.name ?? '(unnamed)'}: ${error}`))
+      }
+      throw new CliError(
+        `${summary.failed.length} of ${bodies.length} rows failed`,
+        { exitCode: 1 },
+      )
+    }
+  }
+}

package/src/lib/bulk.js

@@ -0,0 +1,106 @@
+import createDebug from 'debug'
+import { CliError } from './errors.js'
+
+const debug = createDebug('pd:bulk')
+
+/**
+ * Resolve the target ids for a bulk operation from exactly one selector:
+ * --ids "1,2,3", a Pipedrive saved filter (--filter <id>), or piped stdin
+ * (newline-separated ids, a JSON array of ids, or JSON objects with an id).
+ * @param {object} selectors
+ * @param {string} [selectors.ids]
+ * @param {number} [selectors.filter]
+ * @param {NodeJS.ReadStream} [selectors.stdin] defaults to process.stdin
+ * @param {ReturnType<import('./client.js').createClient>} client
+ * @param {string} listPath v2 list endpoint supporting filter_id (e.g. /api/v2/deals)
+ * @returns {Promise<number[]>}
+ */
+export async function resolveTargets(
+  { ids, filter, stdin = process.stdin },
+  client,
+  listPath,
+) {
+  if (ids) {
+    return ids.split(',').map(parseId)
+  }
+
+  if (filter != null) {
+    debug('resolving targets from filter %d', filter)
+    const targets = []
+    for await (const item of client.pageV2(listPath, {
+      filter_id: filter,
+      limit: 500,
+    })) {
+      targets.push(item.id)
+    }
+    return targets
+  }
+
+  if (!stdin.isTTY) {
+    const chunks = []
+    for await (const chunk of stdin) chunks.push(chunk)
+    const text = Buffer.concat(chunks).toString('utf8').trim()
+    if (text.startsWith('[')) {
+      const parsed = JSON.parse(text)
+      return parsed.map((entry) =>
+        typeof entry === 'object' ? entry.id : parseId(String(entry)),
+      )
+    }
+    return text.split('\n').map(parseId)
+  }
+
+  throw new CliError(
+    'No targets — pass --ids, --filter, or pipe ids on stdin',
+    { exitCode: 64 },
+  )
+}
+
+function parseId(raw) {
+  const id = Number(raw.trim())
+  if (!Number.isInteger(id)) {
+    throw new CliError(`Invalid id "${raw.trim()}" — expected an integer`, {
+      exitCode: 64,
+    })
+  }
+  return id
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Run an async operation per item, sequentially with a pacing gap so bulk
+ * writes stay inside Pipedrive's 2-second burst window (writes cost 10
+ * tokens each; the client's 429 backoff covers anything that slips through).
+ * Per-item failures are collected, never thrown.
+ * @template T
+ * @param {T[]} items
+ * @param {(item: T) => Promise<unknown>} operation
+ * @param {object} [options]
+ * @param {number} [options.gapMs] delay between requests (default 200)
+ * @param {(done: number, total: number) => void} [options.onProgress]
+ * @returns {Promise<{ succeeded: { item: T, result: unknown }[], failed: { item: T, error: string }[] }>}
+ */
+export async function bulkRun(
+  items,
+  operation,
+  { gapMs = 200, onProgress } = {},
+) {
+  const succeeded = []
+  const failed = []
+
+  for (const [index, item] of items.entries()) {
+    if (index > 0 && gapMs > 0) await sleep(gapMs)
+    try {
+      const result = await operation(item)
+      succeeded.push({ item, result })
+    } catch (err) {
+      debug('bulk item %o failed: %s', item, err.message)
+      failed.push({ item, error: err.message })
+    }
+    onProgress?.(index + 1, items.length)
+  }
+
+  return { succeeded, failed }
+}

package/src/lib/csv-parse.js

@@ -0,0 +1,88 @@
+import { CliError } from './errors.js'
+
+/**
+ * Minimal RFC 4180 CSV parser (quoted fields, escaped quotes, embedded
+ * commas/newlines, CRLF). First record is the header row.
+ * @param {string} text
+ * @returns {{ headers: string[], rows: string[][] }}
+ */
+export function parseCsv(text) {
+  const records = []
+  let record = []
+  let field = ''
+  let inQuotes = false
+  let i = 0
+
+  while (i < text.length) {
+    const char = text[i]
+
+    if (inQuotes) {
+      if (char === '"') {
+        if (text[i + 1] === '"') {
+          field += '"'
+          i += 2
+          continue
+        }
+        inQuotes = false
+        i++
+        continue
+      }
+      field += char
+      i++
+      continue
+    }
+
+    if (char === '"') {
+      inQuotes = true
+      i++
+      continue
+    }
+    if (char === ',') {
+      record.push(field)
+      field = ''
+      i++
+      continue
+    }
+    if (char === '\n' || char === '\r') {
+      if (char === '\r' && text[i + 1] === '\n') i++
+      record.push(field)
+      field = ''
+      if (record.length > 1 || record[0] !== '') records.push(record)
+      record = []
+      i++
+      continue
+    }
+    field += char
+    i++
+  }
+
+  if (inQuotes) {
+    throw new CliError('Unterminated quoted field in CSV', { exitCode: 65 })
+  }
+  if (field !== '' || record.length > 0) {
+    // A tail record only reaches here when non-empty (a bare trailing
+    // newline never starts a record), so push unconditionally.
+    record.push(field)
+    records.push(record)
+  }
+
+  if (records.length === 0) {
+    throw new CliError('CSV file is empty', { exitCode: 65 })
+  }
+
+  const [headers, ...rows] = records
+
+  return {
+    headers,
+    rows: rows.map((row, index) => {
+      if (row.length > headers.length) {
+        throw new CliError(
+          `CSV row ${index + 2} has ${row.length} cells but the header has ${headers.length}`,
+          { exitCode: 65 },
+        )
+      }
+      while (row.length < headers.length) row.push('')
+      return row
+    }),
+  }
+}

package/src/lib/import.js

@@ -0,0 +1,49 @@
+import { buildWriteBody } from './input.js'
+import { CliError } from './errors.js'
+
+/**
+ * Turn parsed CSV rows into write bodies. Special columns (matched
+ * case-insensitively) build typed values; every other header resolves
+ * through the entity's field definitions — names, hash keys, and option
+ * labels included. Empty cells are skipped.
+ * @param {object} options
+ * @param {string[]} options.headers
+ * @param {string[][]} options.rows
+ * @param {Record<string, (typed: object, value: string) => void>} [options.specialColumns]
+ * @param {object[]} [options.defs] field definitions for non-special headers
+ * @returns {object[]} one request body per row
+ */
+export function prepareImportBodies({
+  headers,
+  rows,
+  specialColumns = {},
+  defs,
+}) {
+  const specials = Object.fromEntries(
+    Object.entries(specialColumns).map(([k, v]) => [k.toLowerCase(), v]),
+  )
+
+  return rows.map((row, index) => {
+    const typed = {}
+    const fields = []
+
+    headers.forEach((header, i) => {
+      const value = row[i]
+      if (value === '') return
+      const special = specials[header.toLowerCase()]
+      if (special) {
+        special(typed, value)
+        return
+      }
+      fields.push(`${header}=${value}`)
+    })
+
+    try {
+      return buildWriteBody({ typed, fields, defs })
+    } catch (err) {
+      throw new CliError(`CSV row ${index + 2}: ${err.message}`, {
+        exitCode: 65,
+      })
+    }
+  })
+}