Every Sumble v6 feature, plus the credit-awareness the API itself won't give you: cost estimates before every billed call, a running balance, a budget guard, and a local SQLite cache so you never pay twice.
Sumble is usage-based, and the bare API gives you no way to see a balance, preview a call's cost, or avoid re-billing data you already pulled. This CLI fixes all three: cost-estimate previews spend before you pay, balance and spend track every credit from a local ledger, budget refuses calls over a ceiling, and sync caches organizations, people, postings, and technologies so stack-diff and stale run offline for zero credits.
Printed by @cpard.
Quick Start
# Confirm SUMBLE_API_KEY is set and the API is reachable before spending anything.
sumble-pp-cli doctor
# Cheap (1 credit) lookup of the canonical technology slug to filter on.
sumble-pp-cli technologies --query kafka
# See the credit cost (~125) before you pay it; run 'budget set <n>' first to hard-cap it.
sumble-pp-cli cost-estimate organizations.find --rows 25
# Billed call (5 credits/row); results are cached locally so reads are free afterward.
sumble-pp-cli organizations find --filters-technologies '["kafka"]' --limit 25
# Check remaining credits after the call.
sumble-pp-cli balance
# List cached entities worth re-billing; runs offline for zero credits.
sumble-pp-cli stale --older-than 24h
Unique Features
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.
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.
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.
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.
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.
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.
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.
sumble-pp-cli reconcile accounts.csv --json
Usage
Run sumble-pp-cli --help for the full command reference and flag list.
Commands
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 freesumble-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)
Output Formats
# Human-readable table (default in terminal, JSON when piped)
sumble-pp-cli contact-lists list
# JSON for scripting and agents
sumble-pp-cli contact-lists list --json
# Filter to specific fields
sumble-pp-cli contact-lists list --json --select id,name,status
# Dry run — show the request without sending
sumble-pp-cli contact-lists list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
sumble-pp-cli contact-lists list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
sumble-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/sumble-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
SUMBLE_API_KEY | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
sumble-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $SUMBLE_API_KEY
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- Calls fail with HTTP 422 'Field required' — find/enrich endpoints require a filters object; pass at least one of --filters-technologies, --filters-technology-categories, or --filters-query (array fields take a JSON array, e.g. --filters-technologies '["kafka"]').
- HTTP 429 rate limited — Sumble caps at ~10 requests/second aggregate; the client backs off automatically, but lower --limit or batch fewer commands if it persists.
- balance shows a stale or zero value — balance reads the last billed response; run any cheap billed call (e.g. technologies find) or sync to refresh the ledger.
- A call was refused with a budget error — raise or clear the ceiling with 'budget set ' / 'budget clear'.
Generated by CLI Printing Press