Skip to content

Commit e5ee830

Browse files
ilyazubilyazub
committed
Update README with new architecture and usage
1 parent 600f2ed commit e5ee830

File tree

1 file changed

+170
-83
lines changed

1 file changed

+170
-83
lines changed

‎README.md‎

Lines changed: 170 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,185 @@
11
# serpapi-cli
22

3-
A prototype for a lightweight CLI client for [SerpApi].
3+
> SerpApi CLI for humans and AI agents
44
5-
## Description
5+
## Installation
66

7-
`serpapi-cli` allows for the use of SerpApi's extensive search engine result APIs
8-
directly from the command line - perform searches, check your account status,
9-
and read our documentation all without leaving the comfort of your shell.
7+
### Homebrew (macOS/Linux)
108

11-
## Installation
9+
```bash
10+
brew tap serpapi/homebrew-tap
11+
brew install serpapi
12+
```
13+
14+
### cargo-binstall (pre-built binary, no compilation)
15+
16+
```bash
17+
cargo binstall serpapi-cli
18+
```
19+
20+
### Shell script (Linux/macOS)
21+
22+
```bash
23+
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/serpapi/serpapi-cli/releases/latest/download/serpapi-installer.sh | sh
24+
```
25+
26+
### PowerShell (Windows)
27+
28+
```powershell
29+
powershell -ExecutionPolicy ByPass -c "irm https://github.com/serpapi/serpapi-cli/releases/latest/download/serpapi-installer.ps1 | iex"
30+
```
31+
32+
### Pre-built Binaries
33+
34+
Download directly from [GitHub Releases](https://github.com/serpapi/serpapi-cli/releases)
1235

13-
`serpapi-cli` is written in Rust and currently requires compiling from source:
36+
### Cargo (compile from source)
1437

38+
```bash
39+
cargo install serpapi-cli
1540
```
16-
$ cargo install --git https://github.com/serpapi/serpapi-cli.git
41+
42+
## Quick Start
43+
44+
```bash
45+
# Authenticate
46+
serpapi login
47+
48+
# Perform a search (note: --json comes BEFORE the command)
49+
serpapi --json search engine=google q=coffee
50+
```
51+
52+
## Commands
53+
54+
### search
55+
56+
Perform a search with any supported SerpApi engine.
57+
58+
```bash
59+
# Basic search
60+
serpapi --json search engine=google q=coffee
61+
62+
# Fetch all pages and merge array results
63+
serpapi --json search engine=google q=coffee --all-pages
64+
65+
# Limit to first 3 pages
66+
serpapi --json search engine=google q=coffee --all-pages --max-pages 3
67+
68+
# With server-side field filtering (reduces response size at API level)
69+
serpapi --json --fields "organic_results[].{title,link}" search engine=google q=coffee
70+
71+
# With client-side jq filtering (like gh --jq)
72+
serpapi --json --jq ".organic_results[0:3] | [.[] | {title, link}]" search engine=google q=coffee
73+
74+
# Both: server-side reduces payload, then client-side refines
75+
serpapi --json --fields "organic_results" --jq ".organic_results[0:3] | [.[] | {title, link}]" search engine=google q=coffee
76+
77+
# Multiple parameters
78+
serpapi --json search engine=google q="coffee shops" location="Austin,TX"
1779
```
1880

19-
More installation options will become available as development progresses.
81+
### account
2082

21-
## Usage
83+
Retrieve account information and usage statistics.
2284

85+
```bash
86+
serpapi --json account
2387
```
24-
$ serpapi-cli --help
25-
The official CLI client for SerpApi
26-
27-
Usage: serpapi-cli [OPTIONS] --api-key <API_KEY> <COMMAND>
28-
29-
Commands:
30-
search Perform a search
31-
archive Retrieve a previously made search
32-
location Perform a SerpApi location API lookup
33-
account Retrieve SerpApi account data
34-
docs Search SerpApi documentation
35-
help Print this message or the help of the given subcommand(s)
36-
37-
Options:
38-
--api-key <API_KEY> Your private SerpApi API key [env: SERPAPI_KEY]
39-
--json JSON output (default)
40-
-j, --jsonpath <JSONPATH> JSONPath expression for JSON mode
41-
-p, --jsonpointer <JSONPOINTER> JSONPointer expression for JSON mode
42-
--html HTML output if available
43-
-v, --verbose... Verbose output, specify more than once for more
44-
-h, --help Print help
45-
-V, --version Print version
46-
47-
$ serpapi-cli search --help
48-
Perform a search
49-
50-
Usage: serpapi-cli --api-key <API_KEY> search [PARAMS]...
51-
52-
Arguments:
53-
[PARAMS]... A key=value parameter pair, or a value for the q parameter
54-
55-
Options:
56-
-h, --help Print help
57-
58-
# Set your API key in the environment
59-
$ export SERPAPI_KEY="..."
60-
61-
# Extract specific elements using JSONPath
62-
$ serpapi-cli -j '$["account_email", "plan_searches_left"]' account
63-
[
64-
"thomas@serpapi.com",
65-
0
66-
]
67-
68-
# Or with multiple JSONPointer expressions
69-
$ serpapi-cli -p '/account_email' -p '/plan_searches_left' account
70-
[
71-
"thomas@serpapi.com",
72-
0
73-
]
74-
75-
# Look up a location
76-
$ serpapi-cli -p /0/canonical_name location Austin
77-
"Austin,TX,Texas,United States"
78-
79-
# Extract the first result from a search with a given location
80-
$ serpapi-cli -j '$.organic_results[0]["link", "snippet"]' search serpapi "location=Austin,TX,Texas,United States"
81-
[
82-
"https://serpapi.com/",
83-
"SerpApi is a real-time API to access Google search results. We handle proxies, solve captchas, and parse all rich structured data for you."
84-
]
85-
86-
# Find our social media accounts using Bing (with bonus random Wikipedia page)
87-
$ serpapi-cli -j '$.knowledge_graph.profiles[*].link' search serpapi engine=bing
88-
[
89-
"https://www.facebook.com/serpapicom/",
90-
"https://twitter.com/serp_api",
91-
"https://instagram.com/serpapicom",
92-
"https://youtube.com/channel/ucugihlybod3ya3ydirhg_mg",
93-
"https://en.wikipedia.org/wiki/iso_3166-1"
94-
]
88+
89+
### locations
90+
91+
Lookup available locations for search queries (no API key required).
92+
93+
```bash
94+
# Find locations matching "austin"
95+
serpapi --json locations q=austin num=5
96+
```
97+
98+
### archive
99+
100+
Retrieve a previously cached search by ID.
101+
102+
```bash
103+
serpapi --json archive <search-id>
104+
```
105+
106+
### login
107+
108+
Interactive authentication flow to save API key to config file.
109+
110+
```bash
111+
serpapi login
112+
```
113+
114+
## Global Flags
115+
116+
- `--json` — Clean JSON output (no ANSI colors, for AI agents and pipelines)
117+
- `--fields <expr>` — Server-side field filtering (maps to SerpApi's `json_restrictor` parameter). Note: The `--fields` filter uses SerpApi's server-side field restrictor syntax—see [SerpApi docs](https://serpapi.com) for supported expressions.
118+
- `--jq <expr>` — Client-side jq filter applied to JSON output (same as `gh --jq`)
119+
- `--api-key <key>` — Override API key (takes priority over environment and config file)
120+
- `--all-pages` — Fetch all result pages and merge array fields across pages
121+
- `--max-pages <n>` — When used with `--all-pages`, limit fetching to the first `n` pages
122+
123+
**⚠️ Important: Flag Position**
124+
125+
Global flags must come **BEFORE** the subcommand, not after:
126+
127+
```bash
128+
# ✅ Correct
129+
serpapi --json account
130+
serpapi --json --jq ".organic_results[0:3]" search engine=google q=coffee
131+
132+
# ❌ Incorrect (will fail with "unexpected argument")
133+
serpapi account --json
134+
serpapi search engine=google q=coffee --json
135+
```
136+
137+
## Configuration
138+
139+
### Authentication Priority Chain
140+
141+
The CLI checks for API keys in this order:
142+
143+
1. `--api-key` flag
144+
2. `SERPAPI_KEY` environment variable
145+
3. Config file: `~/.config/serpapi/config.toml`
146+
147+
If no API key is found, run `serpapi login` to authenticate interactively.
148+
149+
> **Security note:** For security, prefer setting `SERPAPI_KEY` as an environment variable over
150+
> passing `--api-key` on the command line (command-line arguments are visible in process listings).
151+
152+
### Config File Format
153+
154+
```toml
155+
api_key = "your_serpapi_key_here"
95156
```
96157

97-
[SerpApi]: https://serpapi.com/
98-
[crates.io]: https://crates.io/
158+
## For AI Agents
159+
160+
This CLI is optimized for consumption by AI agents (Claude, Codex, etc.):
161+
162+
- **Use `--json` flag** for clean, parseable JSON output (no ANSI colors or formatting)
163+
- **Use `--fields` for server-side filtering** to reduce token usage:
164+
- Example: `--fields "organic_results[0:3]"` returns only first 3 results
165+
- Filtering happens at the API level, saving bandwidth and context window tokens
166+
- Syntax follows SerpApi's `json_restrictor` parameter
167+
- **Use `--jq` for client-side filtering** (same as `gh --jq`):
168+
- Example: `--jq ".organic_results | length"` counts results locally
169+
- Full jq expression support: pipes, array slicing, object construction, `select`, `map`, etc.
170+
- Runs after API response is received
171+
- **Combine both** for maximum efficiency:
172+
- `--fields` reduces the API response size (less bandwidth)
173+
- `--jq` refines the result further (less context window tokens)
174+
- **Exit codes**:
175+
- `0` = success
176+
- `1` = API error (invalid key, rate limit, etc.)
177+
- `2` = usage error (missing arguments, invalid flags)
178+
- **Errors are always JSON** on stderr for structured parsing
179+
180+
## Links
181+
182+
- [SerpApi Website](https://serpapi.com/)
183+
- [API Documentation](https://serpapi.com/search-api)
184+
- [MCP Server](https://github.com/serpapi/serpapi-mcp)
185+
- [serpapi-rust Crate](https://github.com/serpapi/serpapi-rust)

0 commit comments

Comments
 (0)