pp-sumble

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/sales-and-crm/sumble/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/". -->

# Sumble — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `sumble-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 sumble --cli-only
   ```
2. Verify: `sumble-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/sumble/cmd/sumble-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

Reach for this CLI when an agent or operator needs to prospect or enrich leads through Sumble while keeping credit spend under tight control. It is the right tool when cost predictability matters: previewing spend, enforcing a budget, and reusing a local cache instead of re-billing. It is also the only programmatic way to read the Sumble credit balance, which the REST API does not expose.

## Unique Capabilities

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

### Credit economy
- **`cost-estimate`** — See exactly how many credits a billed Sumble call will cost before you run it.

  _Reach for this before any find/enrich/brief call so you never spend credits blind; the estimate is exact, not heuristic._

  ```bash
  sumble-pp-cli cost-estimate organizations.find --rows 25
  ```
- **`balance`** — Show remaining Sumble credits and recent burn without spending any.

  _Use this to check headroom before a batch of billed calls — it is the only programmatic way to read the balance._

  ```bash
  sumble-pp-cli balance --json
  ```
- **`budget`** — Set a credit ceiling so any call whose estimate exceeds it is refused before it dials.

  _Set this once at the start of an autonomous session; billed commands then self-abort with a nonzero exit instead of overspending._

  ```bash
  sumble-pp-cli budget set 500
  ```
- **`spend`** — Break down credits spent over time by endpoint and by day.

  _Use this to find what is eating credits (usually people enrich and intelligence briefs) and adjust the workflow._

  ```bash
  sumble-pp-cli spend --since 2026-05-01 --by endpoint
  ```

### Local-cache leverage
- **`stale`** — List cached organizations, people, and jobs older than Sumble's freshness window.

  _Run before a refresh pass to re-bill only stale rows instead of the whole cache._

  ```bash
  sumble-pp-cli stale --older-than 24h --json
  ```
- **`stack-diff`** — Compare two cached organizations' technology stacks — shared and unique technologies.

  _Use this for competitive teardown or to find a prospect's gaps versus a reference account, without spending credits._

  ```bash
  sumble-pp-cli stack-diff stripe.com adyen.com
  ```

### Cheap-path workflows
- **`reconcile`** — Resolve a CSV of company names/URLs to Sumble IDs via the cheap match endpoint, then report which still need a billed enrich.

  _Use this to attach Sumble IDs to a CRM export at minimal cost before deciding which accounts justify a full enrich._

  ```bash
  sumble-pp-cli reconcile accounts.csv --json
  ```

## Command Reference

**contact-lists** — Manage saved contact (people) lists

- `sumble-pp-cli contact-lists add` — Add people to a saved contact list by id (free)
- `sumble-pp-cli contact-lists create` — Create a new contact list (free)
- `sumble-pp-cli contact-lists get` — Get the people in a saved contact list (1 credit per person returned)
- `sumble-pp-cli contact-lists list` — List your saved contact lists (1 credit per list returned)

**organization-lists** — Manage saved organization lists

- `sumble-pp-cli organization-lists add` — Add organizations to a saved list by id or slug (free)
- `sumble-pp-cli organization-lists create` — Create a new organization list (free)
- `sumble-pp-cli organization-lists get` — Get the organizations in a saved list (1 credit per organization returned)
- `sumble-pp-cli organization-lists list` — List your saved organization lists (1 credit per list returned)

**organizations** — Find, enrich, and match organizations by technographic and firmographic criteria

- `sumble-pp-cli organizations enrich` — Enrich one organization's technology stack with job/people/team signals (5 credits per technology found)
- `sumble-pp-cli organizations find` — Find organizations matching technology/category/firmographic filters (5 credits per row returned)
- `sumble-pp-cli organizations intelligence-brief` — AI-generated intelligence brief for an organization (50 credits when complete; 202 while pending is free)
- `sumble-pp-cli organizations match` — Resolve up to 1000 company names/URLs/locations to Sumble organizations (1 credit per matched org; unmatched free)

**people** — Find, traverse, and enrich people at organizations

- `sumble-pp-cli people enrich` — Reveal a person's email (10 credits) and/or phone (80 credits); cached or unavailable reveals are free
- `sumble-pp-cli people find` — Find people at an organization by job function/level/country (1 credit per person)
- `sumble-pp-cli people find-related-people` — Find people above/below a person in the org chart (1 credit per person)

**postings** — Find job postings and the people behind them — Sumble's hiring-signal layer

- `sumble-pp-cli postings find` — Find job postings by technology/category/country (2 credits per job, 3 with descriptions)
- `sumble-pp-cli postings find-related-people` — Find people associated with a job posting (1 credit per person)
- `sumble-pp-cli postings get` — Get a single job posting with its full description (1 credit)

**technologies** — Search Sumble's technology taxonomy

- `sumble-pp-cli technologies` — Search technologies by name; returns canonical slugs (1 credit only if at least one match, else free)


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
sumble-pp-cli which "<capability in your own words>"
```

`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query.

## Recipes


### Cost-safe ICP pull

```bash
sumble-pp-cli cost-estimate organizations.find --rows 50
```

Preview the spend before running the billed 'organizations find'; pair with 'budget set 300' to hard-cap it.

### Narrow a verbose org payload for an agent

```bash
sumble-pp-cli organizations find --filters-technologies '["databricks"]' --limit 50 --agent --select name,domain,account_score
```

organizations/find returns large rows; --select keeps only the fields the agent needs (the array is unwrapped, so paths are bare field names) and --agent emits compact structured output.

### Find buying-committee people

```bash
sumble-pp-cli people find --organization-domain stripe.com --filters-job-functions '["Engineer"]' --filters-job-levels '["VP","Director"]'
```

1 credit per person; cost-estimate people.find --rows N previews the spend first.

### Free CRM reconciliation before enrich

```bash
sumble-