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:

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

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.