@zoominfo/gtm-ai-cli 1.1.0 → 2.1.0

package/README.md

@@ -1,8 +1,8 @@
 # GTM AI CLI
 
 A command-line interface for searching [ZoomInfo](https://www.zoominfo.com/) go-to-market (GTM) data. 
-Search and enrich companies and contacts, surface intent signals and news, manage GTM context, and pipe results 
-through your shell as JSON, JSONL, CSV, YAML, or a table.
+Search and enrich companies and contacts, surface intent / news / scoop signals, browse engagement history, 
+manage GTM context, and pipe results through your shell as JSON, JSONL, CSV, YAML, or a table.
 
 ## Installation
 
@@ -141,7 +141,7 @@ gtm lookup --field tech-products --vendor "HubSpot, Inc"
 gtm lookup --field metro-regions --fuzzy "san francisco"
 ```
 
-Valid `--field` names: `industries`, `metro-regions`, `states`, `countries`, `continents`, `management-levels`, `departments`, `job-functions`, `employee-count`, `revenue-ranges`, `company-types`, `company-rankings`, `intent-topics`, `scoop-topics`, `scoop-types`, `scoop-departments`, `news-categories`, `naics-codes`, `sic-codes`, `tech-vendors`, `tech-products`, `tech-categories`, `tech-skills`, `hashtags`, `buying-groups`, `board-members`, `years-of-experience`, `sub-unit-types`, `job-titles`.
+Valid `--field` names: `industries`, `metro-regions`, `states`, `countries`, `continents`, `management-levels`, `departments`, `job-functions`, `employee-count`, `revenue-ranges`, `funding-round-types`, `company-types`, `company-rankings`, `intent-topics`, `scoop-topics`, `scoop-types`, `scoop-departments`, `news-categories`, `naics-codes`, `sic-codes`, `tech-vendors`, `tech-products`, `tech-categories`, `tech-skills`, `hashtags`, `buying-groups`, `board-members`, `years-of-experience`, `sub-unit-types`, `job-titles`.
 
 ---
 
@@ -162,8 +162,9 @@ gtm companies search --type public --country "United States" --revenue-min 10000
 # Companies using a specific tech product (lookup product IDs first)
 gtm companies search --tech "5f1d1d5c123" --metro "MA - Boston" --employees "250to499,500to999"
 
-# Series A-B funded ($1M-$20M) software companies in the US
-gtm companies search --industry software --country "United States" --funding-min 1000 --funding-max 20000
+# US software companies whose most recent round was Series A or B
+# (use --any-funding-round to match any round in their history instead)
+gtm companies search --industry software --country "United States" --recent-funding-round "Series A,Series B"
 
 # By NAICS / SIC codes
 gtm companies search --naics "541511,541512"
@@ -183,6 +184,9 @@ gtm companies enrich --domain stripe.com --fields name description website reven
 
 # Bulk: up to 10 companies via JSON file
 # companies.json: [{ "domain": "stripe.com" }, { "companyId": "344589814" }]
+# Each entry takes the MCP keys (companyId, companyName, companyWebsite, domain, companyTicker,
+# ipAddress, companyCity, ...) or the flag names (id, name, website, ticker, ip).
+# Unsupported keys are rejected.
 gtm companies enrich --file companies.json
 ```
 
@@ -191,6 +195,9 @@ gtm companies enrich --file companies.json
 ```shell
 gtm companies similar --id 344589814
 gtm companies similar --name "Stripe"
+
+# Narrow to look-alikes that share attributes with the reference company
+gtm companies similar --id 344589814 --same-industry --same-country --page-size 50
 ```
 
 ---
@@ -215,8 +222,17 @@ gtm contacts search --management-level Manager --department "Engineering & Techn
 
 # Sales leaders with accuracy score ≥ 90
 gtm contacts search --management-level "VP Level Exec" --department Sales --accuracy-min 90
+
+# People who WORK in metro Boston (not just companies headquartered there) — --location-type
+# scopes the location filters to the person, the company HQ, or both
+gtm contacts search --job-title "CFO" --metro "MA - Boston" --location-type Person
+
+# Within 25 miles of a zip code
+gtm contacts search --management-level "C Level Exec" --zip 02110 --zip-radius 25
 ```
 
+`--location-type` accepts `Person`, `HQ`, `PersonOrHQ`, `PersonAndHQ`, or `PersonThenHQ` and requires at least one location filter (`--metro`, `--state`, `--country`, `--zip`). It's also available on `gtm intent search` and `gtm scoops search`.
+
 **Enrich.** Provide any valid identifier combination — `personId` (most accurate), `email`, `phone`, or `firstName + lastName + (company OR companyId)`:
 
 ```shell
@@ -231,6 +247,9 @@ gtm contacts enrich --email jane@acme.com --fields phone jobTitle managementLeve
 
 # Bulk: up to 10 contacts via JSON file
 # contacts.json: [{ "email": "a@b.com" }, { "personId": "1260398587" }]
+# Each entry takes the MCP keys (personId, email, phone, firstName, lastName, fullName,
+# companyName, companyId, jobTitle, ...) or the flag names (id, company).
+# Unsupported keys are rejected.
 gtm contacts enrich --file contacts.json
 ```
 
@@ -270,13 +289,7 @@ gtm intent search --topics "Mobile Apps" --signal-score-min 80 \
 gtm intent search --topics "AI Agents" --audience-strength-min B --audience-strength-max A
 ```
 
-**Enrich** — pull intent signals for a specific company:
-
-```shell
-gtm intent enrich --company-id 344589814 --topics "Cloud Applications" "Java"
-gtm intent enrich --name "ZoomInfo" --topics "AI Agents" --signal-score-min 70
-gtm intent enrich --website https://www.stripe.com --topics "Payments"
-```
+For intent signals on a *specific* company, use [`gtm signals`](#gtm-signals--per-company-intent--news--scoops) with `--types INTENT`.
 
 ---
 
@@ -299,31 +312,31 @@ gtm scoops search --scoop-types Layoffs --employees "10000plus" --published-star
 gtm scoops search --scoop-types "Product Launch" --description "artificial intelligence" --published-start 2026-04-01
 ```
 
-**Enrich** — get scoops for a specific company:
-
-```shell
-gtm scoops enrich --company-id 344589814 --scoop-types "New Hire" Promotion
-gtm scoops enrich --name "Stripe" --published-start 2026-01-01
-```
+For scoops on a *specific* company, use [`gtm signals`](#gtm-signals--per-company-intent--news--scoops) with `--types SCOOP`.
 
 ---
 
-### `gtm news` — news articles
+### `gtm signals` — per-company intent + news + scoops
 
-`enrich_news` is currently the only news tool. Requires `--company-id`.
+One call returns the latest signals across all three categories for up to 10 companies — ideal for
+a quick "what's happening at these accounts" sweep. Replaces the former `gtm intent enrich`,
+`gtm scoops enrich`, and `gtm news enrich` commands (the MCP consolidated those tools into
+`enrich_company_signals`).
 
 ```shell
-# Recent funding/financial news for ZoomInfo
-gtm news enrich --company-id 344589814 --categories FINANCIAL_RESULTS FUNDING
+# Everything recent for one company (intent + news + scoops, sorted by latest date)
+gtm signals --company-ids 344589814
 
-# Product news in the last quarter
-gtm news enrich --company-id 344589814 --categories PRODUCT --publishing-start 2026-03-01 --publishing-end 2026-05-31
+# Just the news
+gtm signals --company-ids 344589814 --types NEWS
 
-# Leadership news (appointments, departures)
-gtm news enrich --company-id 344589814 --categories PERSON
+# Intent + scoops across a batch of target accounts
+gtm signals --company-ids 344589814 239305146 5237537 --types INTENT SCOOP
 ```
 
-Valid `--categories`: `FINANCIAL_RESULTS`, `FUNDING`, `GENERAL_NEWS`, `GENERAL_PRESS_RELEASE`, `MERGER_OR_ACQUISITION`, `PERSON`, `PRODUCT`.
+The response is `{ results: [{ company, signals: [...] }] }` — each signal has `signalType`,
+`date`, `summary`, and type-specific `details`. Charges data credits for companies not under
+management (companies enriched within the prior 12 months don't incur additional charges).
 
 ---
 
@@ -376,6 +389,87 @@ gtm research contact --contact-id 1260398587 \
 
 ---
 
+### `gtm engagements` — meetings, emails, and conversation intelligence
+
+Requires your ZoomInfo org to have a calendar / email / meeting provider integration configured.
+`list` is free (no data credits).
+
+```shell
+# Recent engagements (default window: last 7 days → 7 days ahead)
+gtm engagements list --limit 10
+
+# Meetings with a specific account, newest first
+gtm engagements list --company-id 344589814 --type MEETINGS --sort -chronological
+
+# A specific date window (ISO 8601, max 90 days)
+gtm engagements list --start 2026-06-01T00:00:00Z --end 2026-08-01T00:00:00Z
+```
+
+**Ask** — natural-language questions over calls, meetings, and emails. Scope to exactly one of an
+engagement, an account, or a contact:
+
+```shell
+# Account scope: synthesize across recent engagements
+gtm engagements ask --company-id 344589814 --query "What concerns has this account raised recently? What did we promise them?"
+
+# Contact scope
+gtm engagements ask --contact-id 1260398587 --query "What has this person told us they care about?"
+
+# Engagement scope: drill into one call/meeting/email (IDs come from `gtm engagements list` — quote them, some contain angle brackets)
+gtm engagements ask --engagement-id "<abc123@mail.example.com>" --query "What were the main objections?"
+
+# Include the raw transcript / email body (engagement scope only — can be very large)
+gtm engagements ask --engagement-id "abc123" --query "Summarize this call" --include-content
+```
+
+---
+
+### `gtm audiences` — GTM Studio audiences
+
+Audiences are GTM Studio's list-building workbooks (rows of contacts or companies, plus custom
+and AI-populated columns). The write subcommands drive a downstream AI agent, so they require
+`--instruction` — a complete, self-contained description of what to do (the agent sees nothing
+else from your session).
+
+```shell
+# Find an audience (the returned id is the audienceId for every other subcommand)
+gtm audiences list --search "Q3 outbound" --type COMPANY
+
+# Columns + a 10-row preview
+gtm audiences get --id <audienceId> --preview 10
+
+# Create — plain named audience
+gtm audiences create --name "Q3 outbound targets" --type COMPANY \
+  --instruction "Create an audience for Q3 outbound targets: enterprise SaaS companies in North America."
+
+# Create from ZoomInfo search criteria (pass the exact search params as JSON)
+gtm audiences create --name "Boston CFOs" --type CONTACT \
+  --instruction "Build a lead list of CFOs at Boston-area companies." \
+  --search-query '{"jobTitleList":["CFO"],"metroRegion":"MA - Boston"}'
+
+# Rename / annotate
+gtm audiences update --id <audienceId> --name "Q4 outbound targets" \
+  --instruction "Rename the audience to Q4 outbound targets."
+
+# Add columns / load rows from JSON files
+gtm audiences columns --id <audienceId> --file ./columns.json
+gtm audiences rows --id <audienceId> --file ./rows.json \
+  --instruction "Load these trade-show leads into the audience."
+
+# Ask the analysis agent
+gtm audiences analyze --id <audienceId> --query "Summarize this audience and show the top industries"
+```
+
+`--search-query` takes the exact params of the matching search (`search_companies` for `COMPANY`,
+`search_contacts` for `CONTACT`) as a JSON object — run the search with `--debug` to see them.
+`page`, `pageSize`, and `sort` are dropped, since they don't apply to audience creation.
+
+`columns.json` is an array of `{ name, dataType, agentInstruction }` (add `columnId` to update);
+`rows.json` is an array of `{ values: [{ columnId, value }] }` (add `rowId` to update, max 50 per
+call). Column and row IDs come from `gtm audiences get`.
+
+---
+
 ### `gtm raw` — universal escape hatch
 
 Use this when you need a tool that doesn't have a curated wrapper yet.