Community project — this is not officially supported by Zyte and may be subject to breaking changes.
Vibecoded — this project was built with AI assistance and has not been rigorously audited. Treat the code accordingly: review it before using it in anything important, and don't assume it is correct, secure, or production-ready.
A command-line tool for the Zyte Search API. Returns organic search results and AI Overviews as clean, structured JSON — suitable for agent pipelines or direct inspection.
- Fetches organic results and AI Overviews from Google via the Zyte Search API
- Outputs structured JSON to stdout; all logging goes to stderr
- Clean AI Overview extraction: prose text, bullet items, and source links — all deduplicated and stripped of citation noise. Note: AI Overview parsing is best-effort and not guaranteed to be perfect; the output is designed to be consumed by an LLM rather than parsed programmatically.
- Interactive TUI mode (
--tui) built with Textual - Optional HTML snapshot saves for debugging
- Python 3.12+
- A Zyte API key — sign up free at https://www.zyte.com/sign-up
# Clone and enter the project
git clone https://github.com/zytelabs/zyte-search-cli.git
cd zyte-search-cli
# Create a virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate
pip install -e .
# Set your Zyte API key
export ZYTE_API_KEY=your_api_key_hereIf you use uv:
uv sync
export ZYTE_API_KEY=your_api_key_herepython search.py "symptoms of vitamin d deficiency"The JSON result is written to stdout. All progress logging goes to stderr.
# Pipe JSON to a file
python search.py "what causes inflation" > results.json
# Write JSON directly to a file
python search.py "what causes inflation" -o results.json
# Increase result count
python search.py "machine learning" --max-results 50
# Target a specific country
python search.py "best laptops" --geolocation GB --locale en-GB
# Enable SafeSearch
python search.py "kids science projects" --safe active
# Save the raw HTML response for debugging
python search.py "climate change" --save-htmlLaunch the interactive terminal UI — no query argument needed:
python search.py --tuiFill in the form on the left, press Run or Ctrl+R, and watch results appear on the right.
| Flag | Default | Description |
|---|---|---|
query |
— | Search query (positional, omit with --tui) |
--domain |
google.com |
Search domain |
--max-results |
10 |
Number of results (10–100, step 10) |
--geolocation |
— | 2-letter country code, e.g. US, GB |
--locale |
— | Locale string, e.g. en-US |
--safe |
— | SafeSearch: active or off |
--save-html |
— | Save raw HTML snapshots alongside JSON |
-o / --output |
stdout | Write JSON to a file instead of stdout |
--tui |
— | Launch the interactive terminal UI |
{
"query": "symptoms of vitamin d deficiency",
"url": "https://www.google.com/search?q=...",
"fetchedAt": "2025-05-21T20:00:00Z",
"organicResults": [
{
"rank": 1,
"title": "Vitamin D Deficiency: Causes, Symptoms & Treatment",
"url": "https://my.clevelandclinic.org/...",
"description": "..."
}
],
"aiOverview": {
"text": "Vitamin D deficiency can cause a range of symptoms...",
"liItems": [
{
"text": "Fatigue and tiredness",
"links": [{ "text": "Cleveland Clinic", "href": "https://..." }]
}
],
"allLinks": [
{ "text": "Cleveland Clinic", "href": "https://..." }
]
}
}The aiOverview key is omitted when Google does not return an AI Overview for the query.
MIT