Skip to content
gsearch

Searching

The search command in depth: building queries, the rich blocks it extracts, headless mode, language and country, pagination, and timeouts.

gsearch search is the main command. It renders a Google Search results page for your query and extracts every structured block on it, then the organic results underneath.

Building a query

The query is the words after search, joined with spaces. Quote it so the shell passes one argument:

gsearch search "epl"
gsearch search "real madrid"
gsearch search "12.5 km in miles"

The query is sent to Google exactly as you would type it into the search box, so the same operators work: an answer-box phrase like define ephemeral triggers the dictionary, weather london triggers the weather card, AAPL stock triggers the stock quote.

The rich blocks it extracts

A single search run looks for roughly forty kinds of Google block and returns each one it finds under the features map. The categories:

  • Answer cards. Calculator, unit converter, currency, direct answer, time, weather.
  • Reference. Dictionary, translation, lyrics, featured snippet, AI overview, things to know.
  • Entities. Knowledge panel (people, films, books, places, music, and more), people also search for.
  • Finance. Stock quote, cryptocurrency, finance fundamentals chart.
  • Sports. Standings, scores, schedule, player stats.
  • Media. Videos, short videos, recipes, podcasts, web stories.
  • Commerce and local. Shopping, hotels, flights, events, jobs, local pack.
  • Community. Social posts, discussions.
  • Query helpers. Spelling correction, search refinements.

Below the cards, search always returns the organic results, People Also Ask, related searches, top stories, and (when present) the local pack. The terminal summary renders whichever blocks were found; the full set is in the JSON. See output and export for the object shape.

Headless versus visible

By default the browser runs headlessly, with no window. Add --no-headless to watch the Chrome window:

gsearch search "epl" --no-headless

This is the move the first time you run gsearch from a new machine or IP. If Google shows a consent page or a CAPTCHA, solve it in the visible window once; the persistent profile remembers the session and later headless runs go straight through. See troubleshooting if a CAPTCHA keeps returning.

Language and country

--lang sets the search language (Google's hl parameter) and --country sets the country (gl). The defaults are en and US:

gsearch search "noticias" --lang es --country ES
gsearch search "wetter berlin" --lang de --country DE

These change which results and cards Google returns, the same way switching your own language and region would.

Pagination

--pages (or -p) follows Google's "Next" link up to N result pages and concatenates the organic results:

gsearch search "python tutorial" --pages 3

The summary notes how many pages were fetched, and the organic results carry their absolute position across pages. The rich blocks come from the first page, since that is where Google renders them.

Timeouts

--timeout sets how long the browser waits for the page to render, in seconds. The default is 30:

gsearch search "epl" --timeout 60

Raise it on a slow connection or a heavy results page. The first run after a fresh install is the slowest, because Chrome is cold; later runs reuse the warm profile.

Profiles

search uses the persistent profile at ~/.cache/gsearch-profile by default, which is what carries a solved CAPTCHA or accepted consent forward. Point it elsewhere with --profile-dir, or use a fresh throwaway profile with --no-profile. See configuration for the details.

3 min read