pp-gohighlevel

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/sales-and-crm/gohighlevel/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# GoHighLevel — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `gohighlevel-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install gohighlevel --cli-only
   ```
2. Verify: `gohighlevel-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/sales-and-crm/gohighlevel/cmd/gohighlevel-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Use this CLI when you run GoHighLevel as a daily operations system, especially across multiple sub-accounts. It is built for agency operators and brokerage directors who need terminal-fast contact lookups, cross-pipeline funnel views, dedup, and SQL-shaped queries across their CRM data. The local SQLite cache makes it the right choice for bulk ops (tag 5000 contacts), recurring reports (Monday L10 prep), and agent-driven workflows that would otherwise require dozens of API round-trips.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Local state that compounds
- **`opp stale`** — Find opportunities sitting in a stage longer than N days, using synthesized stage-entry timestamps from sync history.

  _When the user asks 'which recruits have been sitting in this stage too long', this is the only path that resolves it without re-running their custom dashboard script._

  ```bash
  gohighlevel-pp-cli opp stale --pipeline "Non-KW" --stage "Recruit Lead" --days 30 --json
  ```
- **`opp funnel`** — Stage-by-stage count and total monetary value for a pipeline, output as TSV ready to paste into a dashboard sheet.

  _Replaces the user's Monday L10 prep script with a one-liner; the agent can re-run it on demand with different pipeline filters._

  ```bash
  gohighlevel-pp-cli opp funnel --pipeline "Non-KW" --tsv
  ```
- **`sql`** — Run read-only SQL against the local SQLite mirror of contacts, opportunities, pipelines, stages, tags, custom_fields, conversations, messages, and appointments.

  _The cross-entity differentiator. Anything an agent wants to answer about the GHL data becomes one SQL statement instead of three paginated API calls assembled in Python._

  ```bash
  gohighlevel-pp-cli sql "SELECT name, COUNT(*) FROM opportunities GROUP BY pipelineStageId ORDER BY 2 DESC" --json
  ```
- **`contact dedup`** — Group contacts by lowercased email and E.164 phone, score by filled-field count and recency, emit a merge plan.

  _Replaces a 200-line Python script the operator runs weekly. Agents can preview the merge before any data changes._

  ```bash
  gohighlevel-pp-cli contact dedup --by email,phone --dry-run --json
  ```
- **`contact decay`** — Find opportunities in a stage whose contacts have had no inbound or outbound messages in N days.

  _Catches recruits going cold before they're lost. The operator's existing alert script becomes a one-liner the agent can re-run with different thresholds._

  ```bash
  gohighlevel-pp-cli contact decay --stage "Engaged" --idle-days 30 --json
  ```
- **`recruit hot`** — Rank recruits by a composite of production signals, engagement, and recruit-tag count.

  _Monday L10 prep, before Kymber asks. Agents can re-tune the threshold without re-running the entire Python pipeline._

  ```bash
  gohighlevel-pp-cli recruit hot --threshold 25 --tsv
  ```
- **`convo thread`** — Reconstruct a chronological SMS+email+call thread for a single contact from the local messages table.

  _Before any recruit outreach, the operator wants the whole conversation in one place. Agents can read the full history without four MCP calls._

  ```bash
  gohighlevel-pp-cli convo thread --contact [email protected] --json
  ```

### Service-specific guardrails
- **`field id`** — Translate human-readable custom field names into opaque GHL IDs, with did-you-mean suggestions on typos.

  _Pair `field id` with `sql` to query contacts by custom-field value without hardcoding 20-character GHL IDs; eliminates an entire class of broken-after-rename bugs._

  ```bash
  gohighlevel-pp-cli field id "Agent Affiliation"
  ```
- **`config use`** — Named profiles for each GHL sub-account (KWCP, THINK), with --location flag honored across every command.

  _Prevents the wrong-tenant footgun. Agents can be told 'use the kwcp profile' once at session start and never think about it again._

  ```bash
  gohighlevel-pp-cli config use kwcp && gohighlevel-pp-cli --location think opp funnel --pipeline "Non-KW"
  ```
- **`doctor`** — Validate the PIT token (auto-lowercases the prefix), ping the active location, and report local cache state.

  _First command to run when anything is acting funny. Agents can call it before complex flows to short-circuit a token or cache problem._

  ```bash
  gohighlevel-pp-cli doctor --json
  ```

### Agent-native plumbing
- **`contact bulk-tag`** — Apply or remove a tag across many contacts read from stdin, with chunked 100-at-a-time delivery and connection-drop retry.

  _The highest-leverage daily op for any agency — after every training, after every campaign, after every import. Without this the operator hand-rolls retry logic every time._

  ```bash
  cat emails.csv | gohighlevel-pp-cli contact bulk-tag --tag "Attended_2026-05-19" --dry-run
  ```

## HTTP Transport

This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.

## Command Reference

**calendars** — Manage calendars

- `gohighlevel-pp-cli calendars create` — Create
- `gohighlevel-pp-cli calendars create-appointment` — Create appointment
- `gohighlevel-pp-cli calendars delete-appointment` — Delete appointment
- `gohighlevel-pp-cli calendars get` — Get
- `gohighlevel-pp-cli calendars get-appointment` — Get appointment
- `gohighlevel-pp-cli calendars list` — List
- `gohighlevel-pp-cli calendars list-events` — List calendar events for a location
- `gohighlevel-pp-cli calendars update-appointment` — Update appointment

**contacts** — Manage contacts

- `gohighlevel-pp-cli contacts bulk-update-tags` — Bulk add/remove tags across many contacts
- `gohighlevel-pp-cli contacts create` — Create a contact
- `gohighlevel-pp-cli contacts delete` — Delete a contact
- `gohighlevel-pp-cli contacts find-duplicate` — Find duplicate contact by email or name
- `gohighlevel-pp-cli contacts get` — Get a contact by id
- `gohighlevel-pp-cli contacts search` — GHL's /contacts/search has a hard 100-page cap. Use the `startAfter` cursor returned in the response for pagination...
- `gohighlevel-pp-cli contacts update` — Update a contact
- `gohighlevel-pp-cli contacts upsert` — Upsert contact by email or phone

**conversations** — Manage conversations

- `gohighlevel-pp-cli conversations get` — Get
- `gohighlevel-pp-cli conversations search` — Search conversations (Version 2021-04-15)
- `gohighlevel-pp-cli conversations send-message` — Send an SMS, email, or other message

**locations** — Manage locations

- `gohighlevel-pp-