@zoominfo/gtm-ai-cli 1.0.1 → 2.0.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
 
@@ -14,6 +14,8 @@ The easiest way to install the GTM CLI on MacOS or Linux is using [Homebrew](htt
 brew install zoominfo/gtm-ai/gtm-ai-cli
 ```
 
+> **Heads-up:** the unrelated [Git Time Metric](https://github.com/git-time-metric/gtm) project also ships a `gtm` binary via Homebrew — always install with the tap-qualified name above, not a bare `brew install gtm`.
+
 To upgrade to the latest version, run
 
 ```shell
@@ -31,6 +33,8 @@ Ensure that you install it as a **global** package
 npm install -g @zoominfo/gtm-ai-cli
 ```
 
+This installs the canonical `gtm` command plus a `zoominfo` alias — every command works identically under either name (e.g. `zoominfo companies search`). These docs use `gtm` throughout.
+
 ### Download a Prebuilt Binary
 
 Download the latest binary from the [releases](https://github.com/Zoominfo/gtm-ai-cli/releases) page for your platform.
@@ -46,7 +50,7 @@ Make the downloaded package executable and place it on your PATH
 ```shell
 chmod +x gtm-macos-arm64
 mv gtm-macos-arm64 /usr/local/bin/gtm
-xattr -d com.apple.quarantine /usr/local/bin/apollo #only required on macOS
+xattr -d com.apple.quarantine /usr/local/bin/gtm #only required on macOS
 ```
 
 **Windows**
@@ -61,7 +65,7 @@ git clone https://github.com/Zoominfo/gtm-ai-cli.git
 cd gtm-ai-cli
 npm install
 npm run build
-npm link        # makes `gtm` available globally
+npm link        # makes `gtm` (and its alias `zoominfo`) available globally
 ```
 
 ## Authentication
@@ -137,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`.
 
 ---
 
@@ -158,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"
@@ -187,6 +192,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
 ```
 
 ---
@@ -211,8 +219,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
@@ -266,13 +283,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`.
 
 ---
 
@@ -295,31 +306,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).
 
 ---
 
@@ -372,6 +383,41 @@ 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 raw` — universal escape hatch
 
 Use this when you need a tool that doesn't have a curated wrapper yet.