@zoominfo/gtm-ai-cli 2.0.0 → 2.1.0

package/README.md

@@ -184,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
 ```
 
@@ -244,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
 ```
 
@@ -418,6 +424,52 @@ gtm engagements ask --engagement-id "abc123" --query "Summarize this call" --inc
 
 ---
 
+### `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.