Skip to content
gsearch

Quick start

From an empty terminal to a structured Google Search result, in a handful of commands.

This walks the core loop: run a basic search, read an answer card, get the result as JSON, switch verticals, and save a result to look at later. Every command here hits live data and finishes in a couple of seconds.

gsearch search "epl"

──────────────── Google Search - 'epl' ────────────────
  response: 2143ms  |  features: Sports Standings, Knowledge Panel
  organic: 11  |  paa: 4  |  stories: 3

Standings:  Premier League
  #   Team            P    W   D   L   Pts
  1   Liverpool       29   21  6   2   69
  ...

search prints a readable summary of every rich block it found, then the organic results underneath. It also writes a JSON and a Markdown file under ~/data/gsearch/ by default. The first line after the rule tells you which feature blocks were detected.

2. An answer-box query

The rich blocks are the point. Ask for a conversion, a definition, the weather, or a stock quote and gsearch reads the card Google renders:

gsearch search "12.5 km in miles"     # the unit converter
gsearch search "define ephemeral"     # the dictionary entry
gsearch search "weather tokyo"        # the weather forecast
gsearch search "AAPL stock"           # the stock quote

──────────────── Google Search - '12.5 km in miles' ────────────────
  response: 1980ms  |  features: Unit Converter

Conversion:  12.5 km = 7.767 mi

3. JSON to stdout

--json prints the full structured result to stdout instead of the summary, which is the form to pipe into jq or another program:

gsearch search "AAPL stock" --json | jq '.features.stock'

{
  "title": "Apple Inc",
  "price": "201.45",
  "change": "+1.23",
  "change_pct": "0.61%"
}

With --json, gsearch writes only to stdout and skips the file export.

4. Switch verticals

-v (or --vertical) moves between web, images, videos, news, shopping, and books. Each returns its own result shape:

gsearch search "python tutorial" -v videos    # the videos vertical
gsearch search "running shoes" -v shopping     # products with price and store
gsearch search "climate change" -v news        # articles and top stories
gsearch search "cats" -v images                # image cards

See verticals for what each one returns.

5. Save and revisit

--save upserts the result into a local DuckDB database alongside the file export:

gsearch search "real madrid" --save
gsearch search "weather tokyo" --save
gsearch info                          # feature breakdown across everything stored

DB: ~/data/gsearch/gsearch.duckdb
Searches stored: 2

  Feature            Count   %
  Sports Standings   1       50%
  Weather            1       50%
  Knowledge Panel    1       50%

dump reprints recent stored searches and export rewrites them to JSON and Markdown. See storing results.

Where to next

You have the core loop. From here:

3 min read