@koda-sl/baker-cli 0.274.0 → 0.275.0

package/README.md

@@ -1787,6 +1787,54 @@ baker research intent "buy running shoes,best running shoes 2026,how to tie shoe
 
 ---
 
+### `baker research keyword-metrics "kw1,kw2,kw3"`
+
+Search volume, CPC, top-of-page bids and competition for a list of keywords you name — no domain involved. This is the command for sizing a market you already have keywords for; `keywords-for-site` and `keyword-gap` return volume only for the terms a domain happens to rank for.
+
+```bash
+baker research keyword-metrics "chatbot whatsapp,crm whatsapp" --location mx --language es
+baker research keyword-metrics "chatbot whatsapp" --location br --language pt --clickstream
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": [
+    {
+      "source": "keyword_planner_estimate_via_dataforseo",
+      "keyword": "chatbot whatsapp",
+      "planner_search_volume": 1000,
+      "planner_cpc": 6.27,
+      "planner_low_top_of_page_bid": 1.57,
+      "planner_high_top_of_page_bid": 5.32,
+      "planner_competition": "MEDIUM",
+      "planner_competition_index": 66
+    }
+  ]
+}
+```
+
+Every keyword you ask for comes back, in the order asked. A row whose metrics are all `null` means DataForSEO holds no data on that term — not that nobody searches it.
+
+**The volume is Google's own number.** DataForSEO resells the Keyword Planner figure, so `planner_search_volume` is the same value `baker ads google keywords metrics` returns; the two agreeing is not corroboration. `--clickstream` adds `clickstream_search_volume`, DataForSEO's own panel-derived estimate, which is independent — and costs twice as much.
+
+**Flags:**
+
+| Flag           | Description                          |
+|----------------|--------------------------------------|
+| `--location`   | Country code (us, mx, br...) or DataForSEO location code. **Defaults to us** |
+| `--language`   | Language code or name. **Defaults to en** |
+| `--clickstream`| Add DataForSEO's own volume estimate (costs 2x) |
+| `--full`       | Add keyword difficulty, search intent and the 12-month trend |
+| `--no-cache`   | Skip cache (7d TTL)                  |
+| `--output`     | Format: json\|csv\|md\|jsonl         |
+
+Max 700 keywords per call, 80 characters each.
+
+---
+
 ### `baker research keywords-for-site "domain.com"`
 
 Get keywords a competitor targets. Use `--type paid` to see only paid keywords, `--type organic` for organic only.