yandex-search-cli 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- yandex_search_cli-0.1.0/.gitignore +11 -0
- yandex_search_cli-0.1.0/AGENTS.md +134 -0
- yandex_search_cli-0.1.0/LICENSE +21 -0
- yandex_search_cli-0.1.0/PKG-INFO +183 -0
- yandex_search_cli-0.1.0/README.md +158 -0
- yandex_search_cli-0.1.0/README.ru.md +125 -0
- yandex_search_cli-0.1.0/docs/USAGE.md +129 -0
- yandex_search_cli-0.1.0/llms.txt +52 -0
- yandex_search_cli-0.1.0/pyproject.toml +42 -0
- yandex_search_cli-0.1.0/src/yandex_cli/__init__.py +0 -0
- yandex_search_cli-0.1.0/src/yandex_cli/main.py +216 -0
- yandex_search_cli-0.1.0/uv.lock +684 -0
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# AGENTS.md — yandex-search for AI Coding Agents
|
|
2
|
+
|
|
3
|
+
This file is for AI agents (Claude Code, Codex, Cursor, Windsurf, etc.) that need to install and use `yandex-search` on behalf of a user.
|
|
4
|
+
|
|
5
|
+
## Install & setup
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
uv tool install yandex-search
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
**Credentials — Option 1 (config file, recommended):**
|
|
12
|
+
```bash
|
|
13
|
+
mkdir -p ~/.search-api
|
|
14
|
+
echo '{"apiKey": "your-key", "folderId": "your-folder-id"}' > ~/.search-api/config.json
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
**Credentials — Option 2 (environment variables):**
|
|
18
|
+
```bash
|
|
19
|
+
export YANDEX_API_KEY=your-key
|
|
20
|
+
export YANDEX_FOLDER_ID=your-folder-id
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The user needs a [Yandex Cloud](https://cloud.yandex.ru) account with Search API enabled. Quickstart: https://yandex.cloud/en/docs/search-api/quickstart
|
|
24
|
+
|
|
25
|
+
## Commands
|
|
26
|
+
|
|
27
|
+
| Command | What it does |
|
|
28
|
+
|---|---|
|
|
29
|
+
| `yandex-search <query>` | Web search via Yandex. Returns structured results with domain, date, passages. |
|
|
30
|
+
| `yandex-gen <query>` | Generative search via YandexGPT. Returns an AI-written answer with cited sources. |
|
|
31
|
+
|
|
32
|
+
Both commands support `--json` for structured output.
|
|
33
|
+
|
|
34
|
+
## Recommended agent patterns
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
# Web search, structured output
|
|
38
|
+
yandex-search "query" --json
|
|
39
|
+
|
|
40
|
+
# Extract just the URLs
|
|
41
|
+
yandex-search "query" --json | jq -r '.[].url'
|
|
42
|
+
|
|
43
|
+
# Restrict to a specific domain
|
|
44
|
+
yandex-search "query" --site habr.com --json
|
|
45
|
+
|
|
46
|
+
# Generative search (YandexGPT answer with sources)
|
|
47
|
+
yandex-gen "question" --json
|
|
48
|
+
|
|
49
|
+
# Filter results by domain pattern
|
|
50
|
+
yandex-search "regulations" --json \
|
|
51
|
+
| jq '[.[] | select(.domain | test("gov\\.ru|edu\\.ru"))]'
|
|
52
|
+
|
|
53
|
+
# Collect multiple pages
|
|
54
|
+
for page in 0 1 2; do
|
|
55
|
+
yandex-search "query" -p $page --json
|
|
56
|
+
done | jq -s 'add'
|
|
57
|
+
|
|
58
|
+
# Search .com Yandex index instead of .ru
|
|
59
|
+
yandex-search "machine learning" -t com -n 20 --json
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## JSON output schemas
|
|
63
|
+
|
|
64
|
+
**yandex-search --json**
|
|
65
|
+
```json
|
|
66
|
+
[
|
|
67
|
+
{
|
|
68
|
+
"title": "Page title",
|
|
69
|
+
"url": "https://example.ru/page",
|
|
70
|
+
"domain": "example.ru",
|
|
71
|
+
"date": "2024-03-15",
|
|
72
|
+
"passages": ["Relevant text snippet from the page..."]
|
|
73
|
+
}
|
|
74
|
+
]
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**yandex-gen --json**
|
|
78
|
+
```json
|
|
79
|
+
{
|
|
80
|
+
"message": {
|
|
81
|
+
"content": "YandexGPT answer text...",
|
|
82
|
+
"role": "ROLE_ASSISTANT"
|
|
83
|
+
},
|
|
84
|
+
"sources": [
|
|
85
|
+
{
|
|
86
|
+
"used": true,
|
|
87
|
+
"title": "Source page title",
|
|
88
|
+
"url": "https://..."
|
|
89
|
+
}
|
|
90
|
+
],
|
|
91
|
+
"isAnswerRejected": false,
|
|
92
|
+
"fixedMisspellQuery": ""
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## All flags
|
|
97
|
+
|
|
98
|
+
**yandex-search**
|
|
99
|
+
```
|
|
100
|
+
yandex-search <query> [-n N] [-t ru|com|tr|kk|be|uz] [-r REGION] [-p PAGE]
|
|
101
|
+
[--site DOMAIN] [--json]
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
**yandex-gen**
|
|
105
|
+
```
|
|
106
|
+
yandex-gen <query> [--site DOMAIN] [--json]
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Search index types (-t flag)
|
|
110
|
+
|
|
111
|
+
| Value | Description |
|
|
112
|
+
|---|---|
|
|
113
|
+
| `ru` | Russian Yandex index (default) |
|
|
114
|
+
| `com` | Yandex.com international index |
|
|
115
|
+
| `tr` | Turkish index |
|
|
116
|
+
| `kk` | Kazakh index |
|
|
117
|
+
| `be` | Belarusian index |
|
|
118
|
+
| `uz` | Uzbek index |
|
|
119
|
+
|
|
120
|
+
## Properties
|
|
121
|
+
|
|
122
|
+
- **Stateless** — no local state written between calls
|
|
123
|
+
- **Read-only** — never modifies the web or local files
|
|
124
|
+
- **Exit codes** — `0` on success, non-zero on error
|
|
125
|
+
- **Errors** — specific messages for 401 (bad key), 403 (bad folder/permissions), 429 (rate limit)
|
|
126
|
+
|
|
127
|
+
## Environment variables
|
|
128
|
+
|
|
129
|
+
| Variable | Required | Description |
|
|
130
|
+
|---|---|---|
|
|
131
|
+
| `YANDEX_API_KEY` | if no config file | API key from Yandex Cloud IAM |
|
|
132
|
+
| `YANDEX_FOLDER_ID` | if no config file | Folder ID from Yandex Cloud console |
|
|
133
|
+
|
|
134
|
+
Config file (`~/.search-api/config.json`) takes priority over environment variables.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Nolan Vale
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: yandex-search-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: AI-agent friendly CLI for Yandex Search API — web search and YandexGPT generative search from the terminal.
|
|
5
|
+
Project-URL: Homepage, https://github.com/nolan-vale/yandex-search
|
|
6
|
+
Project-URL: Repository, https://github.com/nolan-vale/yandex-search
|
|
7
|
+
Project-URL: Issues, https://github.com/nolan-vale/yandex-search/issues
|
|
8
|
+
Author: Nolan Vale
|
|
9
|
+
Maintainer: Nolan Vale Tools
|
|
10
|
+
License: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: ai-agents,automation,cli,developer-tools,llm-tools,russian-search,search,search-automation,yandex,yandex-cloud,yandex-search
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
|
|
21
|
+
Classifier: Topic :: Utilities
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Requires-Dist: requests>=2.28
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
<div align="center">
|
|
27
|
+
|
|
28
|
+
[](README.ru.md)
|
|
29
|
+
|
|
30
|
+
<!--
|
|
31
|
+
COVER IMAGE — generate with this prompt, save as docs/cover.png, then uncomment below.
|
|
32
|
+
|
|
33
|
+
Prompt (Midjourney / DALL-E 3 / Stable Diffusion XL):
|
|
34
|
+
"A dark terminal window with glowing Cyrillic search results streaming across the screen,
|
|
35
|
+
Moscow skyline blurred in the background at night, deep navy blue and warm orange gradient,
|
|
36
|
+
minimalist developer tool aesthetic, no UI chrome, no text overlay, professional tech product,
|
|
37
|
+
wide cinematic banner, 2:1 aspect ratio"
|
|
38
|
+
|
|
39
|
+
<img src="docs/cover.png" alt="yandex-search" width="100%">
|
|
40
|
+
-->
|
|
41
|
+
|
|
42
|
+
# yandex-search
|
|
43
|
+
|
|
44
|
+
CLI for [Yandex Search API](https://yandex.cloud/en/services/search-api) and YandexGPT — web search and generative AI search from your terminal.
|
|
45
|
+
|
|
46
|
+
[](https://pypi.org/project/yandex-search/)
|
|
47
|
+
[](https://python.org)
|
|
48
|
+
[](LICENSE)
|
|
49
|
+
[](https://github.com/nolan-vale/yandex-search)
|
|
50
|
+
|
|
51
|
+
</div>
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## What it does
|
|
56
|
+
|
|
57
|
+
`yandex-search` wraps the [Yandex Search API](https://yandex.cloud/en/services/search-api) in two 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.
|
|
58
|
+
|
|
59
|
+
`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.
|
|
60
|
+
|
|
61
|
+
Both commands output clean `--json` for use in scripts and AI agents.
|
|
62
|
+
|
|
63
|
+
## Who it is for
|
|
64
|
+
|
|
65
|
+
- Developers building automation pipelines over Russian-language web content
|
|
66
|
+
- AI agent developers who need structured search output from Yandex
|
|
67
|
+
- Researchers working with Russian-language sources, `.ru` domains, or Yandex Cloud
|
|
68
|
+
- Anyone using Claude Code, Codex, Cursor, or Windsurf who needs Yandex access from the terminal
|
|
69
|
+
|
|
70
|
+
## Features
|
|
71
|
+
|
|
72
|
+
- Web search via Yandex with domain, date, and passage metadata
|
|
73
|
+
- Generative search via YandexGPT — answers with cited sources
|
|
74
|
+
- Filter results by domain (`--site`)
|
|
75
|
+
- Search `.ru`, `.com`, and regional Yandex indexes
|
|
76
|
+
- Paginate results (`--page`)
|
|
77
|
+
- Filter by region code
|
|
78
|
+
- Clean `--json` output for every command
|
|
79
|
+
|
|
80
|
+
## Installation
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
uv tool install yandex-search
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
> No `uv`? Run `curl -LsSf https://astral.sh/uv/install.sh | sh`, or use `pip install yandex-search-cli`.
|
|
87
|
+
|
|
88
|
+
## Quick start
|
|
89
|
+
|
|
90
|
+
You need a [Yandex Cloud](https://cloud.yandex.ru) account with Search API enabled ([quickstart](https://yandex.cloud/en/docs/search-api/quickstart)):
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
mkdir -p ~/.search-api
|
|
94
|
+
echo '{"apiKey": "your-key", "folderId": "your-folder-id"}' > ~/.search-api/config.json
|
|
95
|
+
yandex-search "smart city digital platform"
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
> Or via env vars: `export YANDEX_API_KEY=... && export YANDEX_FOLDER_ID=...`
|
|
99
|
+
|
|
100
|
+
## Usage
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
# Web search
|
|
104
|
+
yandex-search "smart city digital platform monograph"
|
|
105
|
+
|
|
106
|
+
# Restrict to a domain
|
|
107
|
+
yandex-search "async python" --site habr.com
|
|
108
|
+
|
|
109
|
+
# Search the .com Yandex index, more results
|
|
110
|
+
yandex-search "machine learning" -t com -n 20
|
|
111
|
+
|
|
112
|
+
# Generative answer with cited sources
|
|
113
|
+
yandex-gen "explain the difference between monolith and microservices"
|
|
114
|
+
|
|
115
|
+
# Restrict generative search to a domain
|
|
116
|
+
yandex-gen "how to configure nginx" --site nginx.org
|
|
117
|
+
|
|
118
|
+
# JSON — extract all URLs
|
|
119
|
+
yandex-search "topic" --json | jq -r '.[].url'
|
|
120
|
+
|
|
121
|
+
# JSON — filter results by domain pattern
|
|
122
|
+
yandex-search "regulations" --json \
|
|
123
|
+
| jq '[.[] | select(.domain | test("gov\\.ru"))]'
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
**All flags — `yandex-search`:**
|
|
127
|
+
|
|
128
|
+
| Flag | Default | Description |
|
|
129
|
+
|---|---|---|
|
|
130
|
+
| `-n` / `--num-results` | `10` | Number of results |
|
|
131
|
+
| `-t` / `--type` | `ru` | Search index: `ru` · `com` · `tr` · `kk` · `be` · `uz` |
|
|
132
|
+
| `-r` / `--region` | — | Region code (e.g. `213` for Moscow) |
|
|
133
|
+
| `-p` / `--page` | `0` | Page number, zero-indexed |
|
|
134
|
+
| `--site` | — | Restrict results to this domain |
|
|
135
|
+
| `--json` | off | JSON array: `[{title, url, domain, date, passages}]` |
|
|
136
|
+
|
|
137
|
+
**All flags — `yandex-gen`:** `--site`, `--json`
|
|
138
|
+
|
|
139
|
+
## AI agent usage
|
|
140
|
+
|
|
141
|
+
`yandex-search` is stateless, read-only, and designed to be called by AI coding assistants (Claude Code, Codex, Cursor, Windsurf, etc.).
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
# Search and extract URLs
|
|
145
|
+
yandex-search "topic" --json | jq -r '.[].url'
|
|
146
|
+
|
|
147
|
+
# Collect results across multiple pages
|
|
148
|
+
for page in 0 1 2; do
|
|
149
|
+
yandex-search "query" -p $page --json
|
|
150
|
+
done | jq -s 'add'
|
|
151
|
+
|
|
152
|
+
# Generative answer as JSON
|
|
153
|
+
yandex-gen "question" --json | jq '.message.content'
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
JSON schema for `yandex-search --json`:
|
|
157
|
+
```json
|
|
158
|
+
[
|
|
159
|
+
{
|
|
160
|
+
"title": "Page title",
|
|
161
|
+
"url": "https://example.ru/page",
|
|
162
|
+
"domain": "example.ru",
|
|
163
|
+
"date": "2024-03-15",
|
|
164
|
+
"passages": ["Relevant text snippet..."]
|
|
165
|
+
}
|
|
166
|
+
]
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
See [AGENTS.md](AGENTS.md) for full schemas, exit codes, and environment reference.
|
|
170
|
+
|
|
171
|
+
→ [Full documentation](docs/USAGE.md)
|
|
172
|
+
|
|
173
|
+
## Project metadata
|
|
174
|
+
|
|
175
|
+
- **Author:** Nolan Vale
|
|
176
|
+
- **Brand:** Nolan Vale Tools
|
|
177
|
+
- **Focus:** search automation, Yandex Search, AI-agent tooling, Russian web workflows, developer productivity
|
|
178
|
+
- **License:** MIT
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
Built by [Nolan Vale](https://github.com/nolan-vale)
|
|
183
|
+
Part of **Nolan Vale Tools** — practical open-source utilities for search, automation, AI agents, and developer workflows.
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
[](README.ru.md)
|
|
4
|
+
|
|
5
|
+
<!--
|
|
6
|
+
COVER IMAGE — generate with this prompt, save as docs/cover.png, then uncomment below.
|
|
7
|
+
|
|
8
|
+
Prompt (Midjourney / DALL-E 3 / Stable Diffusion XL):
|
|
9
|
+
"A dark terminal window with glowing Cyrillic search results streaming across the screen,
|
|
10
|
+
Moscow skyline blurred in the background at night, deep navy blue and warm orange gradient,
|
|
11
|
+
minimalist developer tool aesthetic, no UI chrome, no text overlay, professional tech product,
|
|
12
|
+
wide cinematic banner, 2:1 aspect ratio"
|
|
13
|
+
|
|
14
|
+
<img src="docs/cover.png" alt="yandex-search" width="100%">
|
|
15
|
+
-->
|
|
16
|
+
|
|
17
|
+
# yandex-search
|
|
18
|
+
|
|
19
|
+
CLI for [Yandex Search API](https://yandex.cloud/en/services/search-api) and YandexGPT — web search and generative AI search from your terminal.
|
|
20
|
+
|
|
21
|
+
[](https://pypi.org/project/yandex-search/)
|
|
22
|
+
[](https://python.org)
|
|
23
|
+
[](LICENSE)
|
|
24
|
+
[](https://github.com/nolan-vale/yandex-search)
|
|
25
|
+
|
|
26
|
+
</div>
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## What it does
|
|
31
|
+
|
|
32
|
+
`yandex-search` wraps the [Yandex Search API](https://yandex.cloud/en/services/search-api) in two 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.
|
|
33
|
+
|
|
34
|
+
`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.
|
|
35
|
+
|
|
36
|
+
Both commands output clean `--json` for use in scripts and AI agents.
|
|
37
|
+
|
|
38
|
+
## Who it is for
|
|
39
|
+
|
|
40
|
+
- Developers building automation pipelines over Russian-language web content
|
|
41
|
+
- AI agent developers who need structured search output from Yandex
|
|
42
|
+
- Researchers working with Russian-language sources, `.ru` domains, or Yandex Cloud
|
|
43
|
+
- Anyone using Claude Code, Codex, Cursor, or Windsurf who needs Yandex access from the terminal
|
|
44
|
+
|
|
45
|
+
## Features
|
|
46
|
+
|
|
47
|
+
- Web search via Yandex with domain, date, and passage metadata
|
|
48
|
+
- Generative search via YandexGPT — answers with cited sources
|
|
49
|
+
- Filter results by domain (`--site`)
|
|
50
|
+
- Search `.ru`, `.com`, and regional Yandex indexes
|
|
51
|
+
- Paginate results (`--page`)
|
|
52
|
+
- Filter by region code
|
|
53
|
+
- Clean `--json` output for every command
|
|
54
|
+
|
|
55
|
+
## Installation
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
uv tool install yandex-search
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
> No `uv`? Run `curl -LsSf https://astral.sh/uv/install.sh | sh`, or use `pip install yandex-search-cli`.
|
|
62
|
+
|
|
63
|
+
## Quick start
|
|
64
|
+
|
|
65
|
+
You need a [Yandex Cloud](https://cloud.yandex.ru) account with Search API enabled ([quickstart](https://yandex.cloud/en/docs/search-api/quickstart)):
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
mkdir -p ~/.search-api
|
|
69
|
+
echo '{"apiKey": "your-key", "folderId": "your-folder-id"}' > ~/.search-api/config.json
|
|
70
|
+
yandex-search "smart city digital platform"
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
> Or via env vars: `export YANDEX_API_KEY=... && export YANDEX_FOLDER_ID=...`
|
|
74
|
+
|
|
75
|
+
## Usage
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
# Web search
|
|
79
|
+
yandex-search "smart city digital platform monograph"
|
|
80
|
+
|
|
81
|
+
# Restrict to a domain
|
|
82
|
+
yandex-search "async python" --site habr.com
|
|
83
|
+
|
|
84
|
+
# Search the .com Yandex index, more results
|
|
85
|
+
yandex-search "machine learning" -t com -n 20
|
|
86
|
+
|
|
87
|
+
# Generative answer with cited sources
|
|
88
|
+
yandex-gen "explain the difference between monolith and microservices"
|
|
89
|
+
|
|
90
|
+
# Restrict generative search to a domain
|
|
91
|
+
yandex-gen "how to configure nginx" --site nginx.org
|
|
92
|
+
|
|
93
|
+
# JSON — extract all URLs
|
|
94
|
+
yandex-search "topic" --json | jq -r '.[].url'
|
|
95
|
+
|
|
96
|
+
# JSON — filter results by domain pattern
|
|
97
|
+
yandex-search "regulations" --json \
|
|
98
|
+
| jq '[.[] | select(.domain | test("gov\\.ru"))]'
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
**All flags — `yandex-search`:**
|
|
102
|
+
|
|
103
|
+
| Flag | Default | Description |
|
|
104
|
+
|---|---|---|
|
|
105
|
+
| `-n` / `--num-results` | `10` | Number of results |
|
|
106
|
+
| `-t` / `--type` | `ru` | Search index: `ru` · `com` · `tr` · `kk` · `be` · `uz` |
|
|
107
|
+
| `-r` / `--region` | — | Region code (e.g. `213` for Moscow) |
|
|
108
|
+
| `-p` / `--page` | `0` | Page number, zero-indexed |
|
|
109
|
+
| `--site` | — | Restrict results to this domain |
|
|
110
|
+
| `--json` | off | JSON array: `[{title, url, domain, date, passages}]` |
|
|
111
|
+
|
|
112
|
+
**All flags — `yandex-gen`:** `--site`, `--json`
|
|
113
|
+
|
|
114
|
+
## AI agent usage
|
|
115
|
+
|
|
116
|
+
`yandex-search` is stateless, read-only, and designed to be called by AI coding assistants (Claude Code, Codex, Cursor, Windsurf, etc.).
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
# Search and extract URLs
|
|
120
|
+
yandex-search "topic" --json | jq -r '.[].url'
|
|
121
|
+
|
|
122
|
+
# Collect results across multiple pages
|
|
123
|
+
for page in 0 1 2; do
|
|
124
|
+
yandex-search "query" -p $page --json
|
|
125
|
+
done | jq -s 'add'
|
|
126
|
+
|
|
127
|
+
# Generative answer as JSON
|
|
128
|
+
yandex-gen "question" --json | jq '.message.content'
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
JSON schema for `yandex-search --json`:
|
|
132
|
+
```json
|
|
133
|
+
[
|
|
134
|
+
{
|
|
135
|
+
"title": "Page title",
|
|
136
|
+
"url": "https://example.ru/page",
|
|
137
|
+
"domain": "example.ru",
|
|
138
|
+
"date": "2024-03-15",
|
|
139
|
+
"passages": ["Relevant text snippet..."]
|
|
140
|
+
}
|
|
141
|
+
]
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
See [AGENTS.md](AGENTS.md) for full schemas, exit codes, and environment reference.
|
|
145
|
+
|
|
146
|
+
→ [Full documentation](docs/USAGE.md)
|
|
147
|
+
|
|
148
|
+
## Project metadata
|
|
149
|
+
|
|
150
|
+
- **Author:** Nolan Vale
|
|
151
|
+
- **Brand:** Nolan Vale Tools
|
|
152
|
+
- **Focus:** search automation, Yandex Search, AI-agent tooling, Russian web workflows, developer productivity
|
|
153
|
+
- **License:** MIT
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
Built by [Nolan Vale](https://github.com/nolan-vale)
|
|
158
|
+
Part of **Nolan Vale Tools** — practical open-source utilities for search, automation, AI agents, and developer workflows.
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
[](README.md)
|
|
4
|
+
|
|
5
|
+
<!--
|
|
6
|
+
<img src="docs/cover.png" alt="yandex-search" width="100%">
|
|
7
|
+
-->
|
|
8
|
+
|
|
9
|
+
# yandex-search
|
|
10
|
+
|
|
11
|
+
**CLI для [Yandex Search API](https://yandex.cloud/en/services/search-api) — веб-поиск и генеративный поиск YandexGPT из терминала.**
|
|
12
|
+
|
|
13
|
+
[](https://pypi.org/project/yandex-search/)
|
|
14
|
+
[](https://python.org)
|
|
15
|
+
[](LICENSE)
|
|
16
|
+
[](https://github.com/nolan-vale/yandex-search)
|
|
17
|
+
|
|
18
|
+
</div>
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
`yandex-search` оборачивает [Yandex Search API](https://yandex.cloud/en/services/search-api) в две команды терминала. `yandex-search` — структурированный веб-поиск с доменами, датами и сниппетами. `yandex-gen` — YandexGPT отвечает на вопросы и цитирует источники. Все команды выводят `--json` для скриптов и агентов.
|
|
23
|
+
|
|
24
|
+
## Запустить за 60 секунд
|
|
25
|
+
|
|
26
|
+
**Шаг 1 — Установка:**
|
|
27
|
+
```bash
|
|
28
|
+
uv tool install yandex-search
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
> Нет `uv`? Запусти `curl -LsSf https://astral.sh/uv/install.sh | sh`, или используй `pip install yandex-search-cli`.
|
|
32
|
+
|
|
33
|
+
**Шаг 2 — Настройка Yandex Cloud:**
|
|
34
|
+
1. Зарегистрируйся на [cloud.yandex.ru](https://cloud.yandex.ru)
|
|
35
|
+
2. Создай сервисный аккаунт и API-ключ в разделе **IAM**
|
|
36
|
+
3. Включи **Yandex Search API** для своего облака ([инструкция](https://yandex.cloud/en/docs/search-api/quickstart))
|
|
37
|
+
4. Скопируй **API-ключ** и **Folder ID** из консоли
|
|
38
|
+
|
|
39
|
+
**Шаг 3 — Укажи credentials:**
|
|
40
|
+
```bash
|
|
41
|
+
mkdir -p ~/.search-api
|
|
42
|
+
echo '{"apiKey": "твой-ключ", "folderId": "твой-folder-id"}' > ~/.search-api/config.json
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
> Можно также через переменные окружения: `export YANDEX_API_KEY=... && export YANDEX_FOLDER_ID=...`
|
|
46
|
+
|
|
47
|
+
**Шаг 4 — Поиск:**
|
|
48
|
+
```bash
|
|
49
|
+
yandex-search "умный город цифровая платформа"
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Команды
|
|
53
|
+
|
|
54
|
+
| Команда | Что делает |
|
|
55
|
+
|---|---|
|
|
56
|
+
| `yandex-search <запрос>` | Веб-поиск: возвращает title, URL, домен, дату, фрагменты текста. |
|
|
57
|
+
| `yandex-gen <запрос>` | Генеративный поиск: YandexGPT пишет ответ с цитированием каждого источника. |
|
|
58
|
+
|
|
59
|
+
Обе команды принимают `--json` — удобно для `jq`, скриптов и AI-агентов.
|
|
60
|
+
|
|
61
|
+
## Примеры
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
# Обычный поиск
|
|
65
|
+
yandex-search "умный город цифровая платформа монография"
|
|
66
|
+
|
|
67
|
+
# Только с конкретного сайта
|
|
68
|
+
yandex-search "async python" --site habr.com
|
|
69
|
+
|
|
70
|
+
# Больше результатов, поиск по .com-индексу
|
|
71
|
+
yandex-search "machine learning" -t com -n 20
|
|
72
|
+
|
|
73
|
+
# Генеративный ответ — YandexGPT с источниками
|
|
74
|
+
yandex-gen "в чём разница между монолитом и микросервисами"
|
|
75
|
+
|
|
76
|
+
# JSON: извлечь все URL
|
|
77
|
+
yandex-search "запрос" --json | jq -r '.[].url'
|
|
78
|
+
|
|
79
|
+
# JSON: только .gov.ru домены
|
|
80
|
+
yandex-search "нормативные акты" --json \
|
|
81
|
+
| jq '[.[] | select(.domain | test("gov\\.ru"))]'
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Справочник параметров
|
|
85
|
+
|
|
86
|
+
**`yandex-search`**
|
|
87
|
+
|
|
88
|
+
| Флаг | По умолчанию | Описание |
|
|
89
|
+
|---|---|---|
|
|
90
|
+
| `-n` / `--num-results` | `10` | Количество результатов |
|
|
91
|
+
| `-t` / `--type` | `ru` | Индекс: `ru` · `com` · `tr` · `kk` · `be` · `uz` |
|
|
92
|
+
| `-r` / `--region` | — | Код региона (например, `213` — Москва) |
|
|
93
|
+
| `-p` / `--page` | `0` | Номер страницы (с нуля) |
|
|
94
|
+
| `--site` | — | Ограничить поиск доменом |
|
|
95
|
+
| `--json` | off | JSON-массив: `[{title, url, domain, date, passages}]` |
|
|
96
|
+
|
|
97
|
+
**`yandex-gen`**
|
|
98
|
+
|
|
99
|
+
| Флаг | По умолчанию | Описание |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| `--site` | — | Ограничить источники доменом |
|
|
102
|
+
| `--json` | off | Сырой JSON от Яндекса |
|
|
103
|
+
|
|
104
|
+
## Для AI-агентов и скриптов
|
|
105
|
+
|
|
106
|
+
`yandex-search` создан для вызова из AI-ассистентов (Claude Code, Codex, Cursor и др.). Все команды stateless, read-only, завершаются чисто.
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
# Поиск → URL → обработка
|
|
110
|
+
yandex-search "монографии по теме" --json | jq -r '.[].url' | head -5
|
|
111
|
+
|
|
112
|
+
# Сбор результатов с нескольких страниц
|
|
113
|
+
for page in 0 1 2; do
|
|
114
|
+
yandex-search "запрос" -p $page --json
|
|
115
|
+
done | jq -s 'add'
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Смотри [AGENTS.md](AGENTS.md) — JSON-схемы, все флаги и паттерны для агентов.
|
|
119
|
+
|
|
120
|
+
→ **[Полная документация](docs/USAGE.md)**
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
Built by [Nolan Vale](https://github.com/nolan-vale)
|
|
125
|
+
Part of **Nolan Vale Tools** — practical open-source utilities for search, automation, AI agents, and developer workflows.
|