pdcli

Command-line interface for Pipedrive — fast, scriptable, built for terminals, CI pipelines, and AI agents.

Not affiliated with or endorsed by Pipedrive.

Install

npm install -g @wavyx/pdcli

Authenticate

pdcli auth login            # personal API token (app.pipedrive.com/settings/api)
pdcli auth login --oauth    # OAuth 2.0 via your own Developer Hub app
pdcli auth status

Credentials live only in your OS keychain — never in plaintext on disk. OAuth access tokens refresh automatically. CI/scripts can use env vars instead: PDCLI_COMPANY_DOMAIN=acme PDCLI_API_TOKEN=... pdcli deal list

Read

pdcli deal list --status open --limit 20
pdcli deal get 42
pdcli person list --org 7 --jq '.[].id'
pdcli activity list --todo
pdcli lead list
pdcli note list --deal 42
pdcli pipeline list && pdcli stage list --pipeline 1
pdcli search "acme"
pdcli field list deal           # custom fields with their hash keys
pdcli user list                 # resolve owner IDs to names
pdcli deal history 42           # field-change audit trail: who changed what, when

Output everywhere: --output table|json|yaml|csv, --jq '<expr>', --fields id,name.

Write

pdcli deal create --title "Acme renewal" --value 5000 --currency EUR --stage 3
pdcli deal update 42 --status won
pdcli activity create --subject "Follow up" --type call --due-date 2026-06-10 --deal 42
pdcli product create --name "Consulting" --price 150 --currency EUR
pdcli lead convert <id> --wait  # promote a lead to a deal; --wait polls the async job
pdcli deal delete 42            # asks first; --yes to skip

Custom fields by human name — labels and option IDs resolve automatically:

pdcli deal create --title "Sized" --field "Deal Size=Large" --field "Score=4.5"
pdcli deal update 42 --body '{"probability":75}'   # raw JSON escape hatch
pdcli field create deal --name "Budget" --type double   # manage the field schema itself

Line items & relations

pdcli deal product add 42 --product 10 --price 150 --quantity 4   # attach a product to a deal
pdcli deal product list 42                                        # lines, with server-computed sums
pdcli deal participant add 42 --person 10                         # add to the buying committee
pdcli deal follower add 42 --user 5                               # follow a deal/person/org
pdcli org relationship add --type parent --owner 1481 --linked 1480  # org hierarchy

Bulk

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

Idempotent writes

Match-or-create, safe to re-run. More than one match refuses (exit 65) — never guesses which record to write.

pdcli person upsert [email protected] --by email --field "Tier=Gold"   # create or PATCH only what changed
pdcli deal upsert "Acme expansion" --by title --body '{"value":5000}'
pdcli org upsert "D-42" --by "External ID" --field "Status=Active" --dry-run  # preview
pdcli person import contacts.csv --upsert --match-on email   # CSV: per-row create-or-update

Analytics & housekeeping

pdcli deal summary --status open         # server-side per-currency totals, weighted, count
pdcli metrics velocity --period 90d      # the Sales Velocity Equation, in your terminal
pdcli funnel --pipeline 1                # stage-to-stage conversion
pdcli funnel --exact                     # mine real stage transitions per deal (one call each)
pdcli metrics coverage --target 500000   # weighted pipeline vs quota — the 3x coverage rule
pdcli metrics aging --pipeline 1         # days-in-stage bucketed, per-stage p90 dwell flag
pdcli metrics slippage --min-pushes 2    # open deals whose close date keeps getting pushed
pdcli pipeline health                    # per-stage value, weighted value, stale, no-next-step
pdcli audit                              # 11 data-hygiene checks (duplicates, stale, gaps)
pdcli audit --strict                     # exit 1 on must-severity findings — wire into CI
pdcli person merge 123 --into 456        # fold a duplicate into the survivor (deletes 123)

Files, webhooks, backup

pdcli file upload ./contract.pdf --deal 42
pdcli file download 15 --out ./contract.pdf
pdcli webhook create --url https://ci.example.com/hook --event-action create --event-object deal
pdcli backup --dir ./pipedrive-backup    # full account → JSON tree, --resume to continue

Anything else

pdcli api GET /api/v2/pipelines          # raw, host-locked to YOUR domain
pdcli api POST /api/v2/deals --body '{"title":"Raw deal"}'
pdcli alias set wd "deal list --status won"   # save a shortcut, then run: pdcli wd
pdcli doctor                             # diagnose auth/keychain/connectivity

• --output table|json|yaml|csv everywhere; table in a TTY, JSON when piped.
• Deterministic sysexits exit codes for scripting.
• Docs: wavyx.github.io/pdcli — guides, cookbook, AI-agent quickstart, llms.txt.
• Full reference: docs/commands.md (generated from the CLI manifest).

License

MIT