• Для людей — цветные таблицы, спиннеры, интерактивная настройка
• Для AI-агентов — --json на каждой команде, стабильный JSON-конверт
• Два в одном — веб-поиск Яндекса + полный Wordstat (топ, динамика, регионы)

Быстрый старт

npm i -g @polza-ai/yandex-search-cli

search init                              # интерактивная настройка
search web "Claude AI"                   # веб-поиск
search wordstat top "купить телефон"     # топ запросов по фразе
search wordstat dynamics "react"         # динамика за 30 дней

Команды

| Команда | Описание | Пример | |---------|----------|--------| | init | Настроить подключение | search init | | web | Веб-поиск | search web "запрос" --num 20 | | wordstat top | Топ запросов + ассоциации | search wordstat top "ноутбук" -n 20 | | wordstat dynamics | Динамика запроса за период | search wordstat dynamics "iphone" --period daily | | wordstat regions | Распределение по регионам | search wordstat regions "доставка" | | regions | Дерево регионов (справочник) | search regions |

Все команды поддерживают --json для машинного вывода.

Интеграция с AI-агентами

search спроектирован как инструмент для AI-агентов: данные идут в stdout (JSON/таблица), логи и спиннеры — в stderr. Флаг --json возвращает стабильный конверт:

{ "ok": true,  "data": [{ "position": 1, "title": "...", "url": "...", "snippet": "..." }] }
{ "ok": false, "error": { "code": "AUTH_ERROR", "message": "Неверный API-ключ" } }

Claude Code / Cursor / Windsurf — используйте --json и парсите { ok, data } / { ok, error }.

Конфигурация

Глобальный конфиг

~/.search-api/config.json — создаётся через search init:

{
  "apiKey": "AQVN...",
  "folderId": "b1g36...",
  "apiBaseUrl": "https://searchapi.api.cloud.yandex.net"
}

Проектный конфиг

.search-api.json — переопределяет настройки для конкретного проекта:

{
  "folderId": "другой-folder-id",
  "defaultRegion": "213",
  "familyMode": "FAMILY_MODE_STRICT"
}

init

search init

Интерактивная настройка: запрашивает API-ключ и Folder ID, проверяет подключение, сохраняет конфиг.

API-ключ создаётся в AI Studio → «API-ключи» → «Создать ключ».

web

search web <query> [опции]

| Флаг | Описание | |------|----------| | -t, --type <type> | Тип поиска: ru, tr, com, kk, be, uz (по умолчанию: ru) | | -p, --page <n> | Номер страницы, с 0 (по умолчанию: 0) | | -r, --region <id> | ID региона (см. search regions) | | -f, --family <mode> | Фильтр: none, moderate, strict | | -n, --num <n> | Результатов на странице, 1–100 (по умолчанию: 10) | | --raw | Вывести сырой XML без парсинга | | --json | JSON-вывод |

wordstat top

search wordstat top <phrase> [опции]

| Флаг | Описание | |------|----------| | -n, --num <n> | Количество результатов (по умолчанию: 10) | | -r, --region <ids> | ID регионов через запятую | | -d, --device <devices> | Устройства: all, desktop, phone, tablet | | --json | JSON-вывод |

Выводит две таблицы: Топ запросов (запросы, содержащие фразу) и Ассоциации (похожие запросы).

wordstat dynamics

search wordstat dynamics <phrase> [опции]

| Флаг | Описание | |------|----------| | -p, --period <period> | Период: daily, weekly, monthly (по умолчанию: weekly) | | --from <date> | Дата начала, YYYY-MM-DD (по умолчанию: 30 дней назад) | | --to <date> | Дата конца, YYYY-MM-DD (по умолчанию: сегодня) | | -r, --region <ids> | ID регионов через запятую | | -d, --device <devices> | Устройства | | --json | JSON-вывод |

Даты автоматически выравниваются: на понедельник/воскресенье для weekly, на 1-е/последний день месяца для monthly.

wordstat regions

search wordstat regions <phrase> [опции]

| Флаг | Описание | |------|----------| | --scope <scope> | Группировка: all, cities, regions (по умолчанию: all) | | -d, --device <devices> | Устройства | | --json | JSON-вывод |

Выводит таблицу с регионами, количеством показов, долей и affinity index (цветовая индикация: зелёный > 100%, красный < 100%).

regions

search regions [--json]

Выводит полное дерево регионов Яндекса. Используйте для поиска ID региона, который затем можно передать в --region других команд.

git clone https://github.com/polza-ai/yandex-search-cli.git
cd yandex-search-cli
npm install

npm run dev -- web "тест"                    # запуск через tsx
npm run dev -- wordstat top "фраза"          # wordstat
npm run build                                # компиляция в dist/
npm run typecheck                            # проверка типов

Требования

• Node.js 20+
• API-ключ Yandex Cloud — создаётся в AI Studio
• Folder ID — идентификатор каталога в Yandex Cloud Console

Лицензия

MIT