pipedrive-checker

CLI tool to check open-deal hygiene metrics in Pipedrive.

Current release: v0.2.0a1. See CHANGELOG.md for release notes.

OpenAPI endpoints used

Based on Pipedrive OpenAPI v1 spec (https://developers.pipedrive.com/docs/api/v1/openapi.yaml):

• GET /deals with status=open to retrieve open deals (includes activities_count, last_activity_date, next_activity_date per deal).
• GET /stages to determine the latest stages per funnel (configurable with --stages).
• GET /pipelines to show funnel names in output.

Requirements

• Python 3.11+
• uv

Setup

Install dependencies and register a global terminal command:

bash scripts/install.sh

This makes pipedrive-checker callable from your terminal. The tool is installed in editable mode, so any source change is immediately reflected without reinstalling. If ~/.local/bin is missing from PATH, the installer will prompt to update your shell config automatically.

Usage

Set your token in environment variable PIPEDRIVE_API_TOKEN:

export PIPEDRIVE_API_TOKEN="your_token_here"

If the variable is not exported, the CLI also tries to read PIPEDRIVE_API_TOKEN from a local .env file.

Run the command:

pipedrive-checker deals_check

Show extended list of non-conforming late-stage deals by funnel:

pipedrive-checker deals_check --extended

Use a custom number of latest stages for the funnel checks:

pipedrive-checker deals_check --stages 3

Alternative (without global install):

uv run pipedrive-checker deals_check

The CLI prints two Rich tables:

1. Late-stage deals summary (scoped to the same N stages selected with --stages):

   • Open deals (total)
   • Open deals in last N stages
   • Open deals in last N stages with no activities
   • % of late-stage deals with no activities

2. Funnel late-stage quality metrics (per funnel, same N-stage scope):

   • Number of open deals in the selected late stages
   • % without probability
   • % without expected close date
   • % with past expected close date
   • % without activities with expected close date set in the future

With --extended, the CLI also prints all non-conforming late-stage deals by funnel, including deal owner and issue details.

If --stages is greater than the number of stages in any funnel, the command exits with an error.

Logging

The CLI writes logs to logs/pipedrive_checker.log with rotation. Storage policy is bounded to under 1MB total (450KB x 2 files max).

Alpha distribution

Build package artifacts:

uv build

Install locally from the built wheel (example):

uv tool install --force dist/pipedrive_checker-0.2.0a1-py3-none-any.whl

Validation

bash scripts/validate.sh