Skip to content
gsearch

Introduction

What gsearch gives you, the one command to start with, and the things you can do from there.

A Google Search results page is much more than ten blue links. Above and beside them, Google renders answer cards: a knowledge panel for an entity, a weather forecast, a sports standings table, a dictionary entry, a calculator, a stock quote, a featured snippet, an AI overview. Those rich blocks are the most useful part of a search and the most awkward to get at.

gsearch hands them to you on the command line. You run one command and get back every structured block on the page, plus the organic results underneath, as a clean object you can read, pipe into jq, or save.

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
  ...

Why use it

The paid SERP APIs (SerpApi and the like) cover the same blocks, but you pay per query and trust their parse of a page you cannot see. gsearch reads the same page you would see in a browser, on your own machine, so there is no API key, no per-query bill, and the output tracks what Google actually shows. The trade is that a run takes a couple of seconds rather than milliseconds, and it is meant for personal, low-volume research rather than bulk scraping.

What you can do with it

A few commands cover almost everything:

  • Read the rich blocks. A plain gsearch search "<query>" pulls every answer card on the page: knowledge panel, weather, sports, dictionary, calculator, stock and crypto quotes, featured snippet, AI overview, People Also Ask, and more. See searching.
  • Ask answer-box questions. Queries like 12.5 km in miles, define ephemeral, weather tokyo, or AAPL stock return the matching card directly.
  • Switch verticals. -v images, -v videos, -v news, -v shopping, or -v books returns that tab's results. See verticals.
  • Get structured output. --json prints the whole result to stdout for jq or another program, and every run also writes a dated JSON and Markdown file. See output and export.
  • Store and revisit. --save keeps results in DuckDB, and info, dump, and export let you review and rewrite them. See storing results.

One thing to know

gsearch drives a real Chrome to render the page, so the first time you run it, or from a fresh IP, Google may show a consent form or a CAPTCHA. This is normal. Run once with --no-headless to see the browser window, solve it by hand, and gsearch remembers the session so later runs go straight through. See troubleshooting if a CAPTCHA keeps returning.

Scope

gsearch is a read-only client over the public Google Search results page. It is meant for personal, low-volume research and learning. Respect Google's terms of service, keep the rate gentle, and do not point it at anything you are not allowed to scrape.

Next: install it, then take the quick start.

3 min read