yandex-search-cli

CLI for Yandex Search API and YandexGPT — web search, image search, generative AI search, and Wordstat statistics from your terminal.

---

What it does

yandex-search-cli wraps the Yandex Search API in five terminal commands. It is the practical way to query Yandex — the dominant search engine for Russian-language content — from scripts, pipelines, and AI agent workflows.

yandex-search performs web search and returns structured results: title, URL, domain, publication date, and text passages. yandex-gen uses YandexGPT to answer a question and cite the sources it used. yandex-image-search and yandex-image-search-by-image search images by text query or by a reference image. yandex-wordstat returns query-frequency statistics — top queries, trends over time, and regional distribution.

All commands output clean --json for use in scripts and AI agents.

Who it is for

• Developers building automation pipelines over Russian-language web content
• AI agent developers who need structured search output from Yandex
• Researchers working with Russian-language sources, .ru domains, or Yandex Cloud
• Anyone using Claude Code, Codex, Cursor, or Windsurf who needs Yandex access from the terminal

Features

• Web search via Yandex with domain, date, and passage metadata
• Generative search via YandexGPT — answers with cited sources
• Filter results by domain (--site)
• Search .ru, .com, and regional Yandex indexes
• Paginate results (--page)
• Filter by region code
• Clean --json output for every command
• Image search — find images matching a text query (yandex-image-search)
• Reverse image search — find pages containing a given image (yandex-image-search-by-image)
• Yandex Wordstat query-frequency statistics — top queries, trends over time, regional distribution (yandex-wordstat)

Installation

uv tool install yandex-search-cli

No uv? Run curl -LsSf https://astral.sh/uv/install.sh | sh, or use pip install yandex-search-cli.

Quick start

You need a Yandex Cloud account with Search API enabled (quickstart):

mkdir -p ~/.search-api
echo '{"apiKey": "your-key", "folderId": "your-folder-id"}' > ~/.search-api/config.json
yandex-search "smart city digital platform"

Or via env vars: export YANDEX_API_KEY=... && export YANDEX_FOLDER_ID=...

Usage

# Web search
yandex-search "smart city digital platform monograph"

# Restrict to a domain
yandex-search "async python" --site habr.com

# Search the .com Yandex index, more results
yandex-search "machine learning" -t com -n 20

# Generative answer with cited sources
yandex-gen "explain the difference between monolith and microservices"

# Restrict generative search to a domain
yandex-gen "how to configure nginx" --site nginx.org

# JSON — extract all URLs
yandex-search "topic" --json | jq -r '.[].url'

# JSON — filter results by domain pattern
yandex-search "regulations" --json \
  | jq '[.[] | select(.domain | test("gov\\.ru"))]'

All flags — yandex-search:

Flag	Default	Description
-n / --num-results	10	Number of results
-t / --type	ru	Search index: ru · com · tr · kk · be · uz
-r / --region	—	Region code (e.g. 213 for Moscow)
-p / --page	0	Page number, zero-indexed
--site	—	Restrict results to this domain
--json	off	JSON array: [{title, url, domain, date, passages}]

All flags — yandex-gen: --site, --json

All flags — yandex-image-search: -n / --num-results, -t / --type, -r / --region, -p / --page, --site, --json

All flags — yandex-image-search-by-image: --url / --cbir-id (one required), --site, --page, --family-mode, --json

All flags — yandex-wordstat: subcommands top, dynamics, regions, regions-tree — see full documentation for per-subcommand flags

AI agent usage

yandex-search-cli is stateless, read-only, and designed to be called by AI coding assistants (Claude Code, Codex, Cursor, Windsurf, etc.).

# Search and extract URLs
yandex-search "topic" --json | jq -r '.[].url'

# Collect results across multiple pages
for page in 0 1 2; do
  yandex-search "query" -p $page --json
done | jq -s 'add'

# Generative answer as JSON
yandex-gen "question" --json | jq '.message.content'

JSON schema for yandex-search --json:

[
  {
    "title": "Page title",
    "url": "https://example.ru/page",
    "domain": "example.ru",
    "date": "2024-03-15",
    "passages": ["Relevant text snippet..."]
  }
]

See AGENTS.md for full schemas, exit codes, and environment reference.

→ Full documentation

How this was built

Spec first, then a plan, then implementation with AI coding agents (Claude Code, Codex). Every diff gets reviewed before merge, and releases go through tests and basic security checks. More on the process on the Nolan Vale profile.

Project metadata

• Author: Nolan Vale
• Brand: Nolan Vale Tools
• Focus: search automation, Yandex Search, AI-agent tooling, Russian web workflows, developer productivity
• License: MIT

---

Built by Nolan Vale
Part of Nolan Vale Tools — practical open-source utilities for search, automation, AI agents, and developer workflows.