Configuration

gsearch needs almost no configuration. There is no config file; every option is a flag or an environment variable, and the defaults are chosen so the common case needs neither.

The data directory

gsearch keeps its output under one tree, ~/data/gsearch by default. Inside it:

~/data/gsearch/
  json/      YYYY/MM/DD/HH-MM-slug.json   exported JSON, one per search
  markdown/  YYYY/MM/DD/HH-MM-slug.md     exported Markdown, one per search
  capture/                               raw responses from capture --out default
  gsearch.duckdb                         the DuckDB store (when you --save)

The dated json/ and markdown/ trees are written by every search run unless you pass --no-export. The DuckDB file is written only when you pass --save. See output formats for the file naming.

The database

The DuckDB store lives at ~/data/gsearch/gsearch.duckdb by default. Override the path with --db on any database command, or with the GSEARCH_DB environment variable:

GSEARCH_DB=/tmp/serps.duckdb gsearch search "epl" --save
GSEARCH_DB=/tmp/serps.duckdb gsearch info

The browser profile

gsearch drives Chrome with a persistent profile at ~/.cache/gsearch-profile. The profile is what carries cookies, consent, and a solved CAPTCHA forward between runs, so once you clear a challenge the headless runs that follow go straight through. Two flags control it on search and capture:

Flag	Meaning
--profile-dir <path>	Use a different persistent profile directory
--no-profile	Use a fresh ephemeral profile, discarded after the run

Use --no-profile when you want a clean session with no carried state. Use --profile-dir to keep separate profiles, for instance one per Google account or region.

Headless mode

The browser runs headlessly by default on both search and capture. --no-headless shows the Chrome window, which is the way to solve a consent or CAPTCHA page by hand the first time. --headless is the explicit form of the default.

Environment variables

Variable	Used for
GSEARCH_DB	DuckDB path (overrides the default ~/data/gsearch/gsearch.duckdb)

Search locale

--lang and --country set the search language (hl) and country (gl) Google applies, defaulting to en and US. They change which results and cards come back, the same way switching your own browser's language and region would. See searching.