google-terminal-search
Run Google searches from your terminal — zero dependencies, pipe-friendly output.
git clone https://github.com/fernandofatech/google-terminal-search.gitgoogle-terminal-search is a pure Bash command-line utility that runs Google searches directly from your terminal, returning parseable results ready for shell pipelines.
What it is and why it exists
This repository was born from a practical need: leaving a terminal workflow to open a browser for a quick search is a small but constant interruption. The goal is to eliminate that friction by keeping everything on the command line.
The script is written entirely in Bash, with no external dependencies beyond the standard tools available on any Unix/Linux/macOS system — curl, sed, awk, and similar. There is no runtime to install, no npm install, no Python virtual environment. You clone it, set the execute bit, and use it.
The output is designed to be parseable: URLs and titles are printed in a structured way, meaning you can pipe results into grep, head, fzf, xargs, or any other tool in your usual pipeline. The goal is not to replace a browser — it is to give quick access to search results without leaving the context you are already working in.
This project is part of Fernando Azevedo's public portfolio ecosystem, focused on automation, developer productivity, and pragmatic engineering practices.
Key characteristics
grep, awk, fzf, or xargs.chmod +x and the script is ready to use; no compilation, no packaging.How the utility works
Execution flow of google-terminal-search: from user input to parseable results in the terminal.
- Developer · shell session
- main.sh · entry point
- Argument · parser
- Query · builder
- curl · HTTP fetch
- sed/awk · result parser
- Google · Search
- stdout · parseable text
- Downstream · grep/fzf/xargs
How it works internally
The flow is straightforward. main.sh receives search terms as positional arguments, builds a Google search URL with the terms properly URL-encoded (spaces become + or %20, special characters are escaped), and uses curl to fetch the HTML of the results page.
The returned HTML is then processed by regular expressions via sed and/or awk to extract the relevant elements — typically result titles and their corresponding URLs. This parsing step is the most sensitive part of the script: Google's HTML is not a stable API, and changes to the page structure may require adjustments to the regular expressions.
Output goes to stdout in a structured format, enabling immediate use in pipelines. For example, you can grab only the first returned URL with head -1, filter results by domain with grep, or present an interactive list with fzf for selection and browser opening via xopen or open.
There is no persistent state, no mandatory configuration files, no cache. Each invocation is independent. This keeps the script simple and auditable — you can read the entire code in a few minutes and understand exactly what is happening.
Installation and usage
- 1
Prerequisites
Bash 4+ (macOS ships with Bash 3 by default — install via
brew install bashif needed),curlavailable on PATH. No other dependency is required. - 2
Clone the repository
Clone the repository to a local directory of your choice.
- 3
Set execute permission
Make the scripts executable with
chmod +x. There is no build or compilation step. - 4
Run a search
Pass search terms as arguments to
main.sh. Terms with spaces should be quoted. - 5
Use in pipelines
Chain the output with other shell tools. For example,
./main.sh 'bash scripting' | head -3returns the top three results, or./main.sh 'aws cli' | grep 'docs.aws'filters by domain. - 6
Optional: add to PATH
For global access, create a symlink or copy the script to a directory on your PATH, such as
~/.local/bin/gsearch. Add an alias in~/.bashrcor~/.zshrcif you prefer a shorter name.
# 1. Clone
git clone https://github.com/fernandofatech/google-terminal-search.git
cd google-terminal-search
# 2. Set execute permission
chmod +x *.sh
# 3. Basic search
./main.sh 'bash string manipulation'
# 4. Pipe to head — get only the first 5 results
./main.sh 'aws s3 sync options' | head -5
# 5. Filter results by domain
./main.sh 'terraform aws provider' | grep 'registry.terraform.io'
# 6. Interactive selection with fzf (if installed)
./main.sh 'linux cron syntax' | fzf
# 7. Open first result in default browser (macOS/Linux)
./main.sh 'jq tutorial' | head -1 | xargs open
# 8. Optional: install globally
ln -s "$(pwd)/main.sh" ~/.local/bin/gsearch
# Then from anywhere:
gsearch 'event-driven architecture patterns'Parsing stability
Google does not expose a stable public API for scraping search results. The results page HTML changes periodically, which can break the regular expressions used by the script. If results appear empty or malformed after a Google update, the expressions likely need adjustment. Check open issues on the repository or inspect the HTML returned by curl directly to diagnose.
Integration with fzf
The most useful combination I have found day-to-day is ./main.sh 'query' | fzf | xargs open. fzf presents results in an interactive fuzzy-searchable list, you select with Enter, and xargs open (or xdg-open on Linux) opens the URL in the default browser. It is the closest flow to a real search without leaving the terminal.
Frequently asked questions
Do I need a Google API key?
No. The script scrapes the Google results page directly via curl, without using the Google Custom Search API. This means zero cost and zero credential setup, but also implies the parsing stability limitations described above.
Does it work on macOS?
Yes, with the caveat that macOS ships with Bash 3.2 by default (for licensing reasons). If the script uses Bash 4+ features, install a newer version via Homebrew: brew install bash. curl is already installed on macOS.
Can Google block the requests?
Yes. Google detects automated scraping and may return a CAPTCHA or 429 error if requests are too frequent. For occasional and ad-hoc use, the script works fine. For intensive or automated use at scale, consider the official Google Custom Search JSON API.
Can I use it in CI/CD scripts?
Technically yes, but it is not the recommended use. CI pipelines run in controlled environments where stability is critical, and reliance on HTML scraping is not reliable enough for that context. Use the official Google API if you need programmatic searches in automation.
Who this project is for
This utility is for developers who live in the terminal and want to reduce the friction of quick lookups without installing anything heavy. If you already use fzf, ripgrep, jq, and similar tools as part of your daily workflow, google-terminal-search fits naturally into that ecosystem.
It is not a tool for production use or critical automation — the reliance on HTML scraping makes it unsuitable for that. But for ad-hoc queries during development, debugging, or research, it eliminates an unnecessary context switch.
The code is short, readable, and auditable. If you are learning shell scripting, it is also a good example of how to structure a CLI utility in Bash: argument parsing, URL construction, fetching with curl, and text processing with sed/awk. It is part of my public portfolio precisely because it demonstrates that simple tools, well executed, have real value.