# google-terminal-search Run Google searches from your terminal — zero dependencies, pipe-friendly output. - URL: https://fernando.moretes.com/open-source/google-terminal-search - Markdown: https://fernando.moretes.com/open-source/google-terminal-search/guide.md?lang=en - GitHub: https://github.com/fernandofatech/google-terminal-search - Homepage: https://fernando.moretes.com - Language: Shell - Topics: automation, bash, cli, developer-tools, google-search, moretes, portfolio, productivity, terminal - Stars: 0 - Forks: 0 - Updated: 2026-05-16T01:14:57Z --- google-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 - **Zero dependencies** — works with standard tools on any Unix/Linux/macOS system; nothing to install beyond the script itself. - **Parseable output** — results printed in a structured format, suitable for downstream processing with `grep`, `awk`, `fzf`, or `xargs`. - **Pipe-friendly** — designed to fit into existing shell pipelines without special behavior or colored output that breaks automation. - **No build step** — a single `chmod +x` and the script is ready to use; no compilation, no packaging. - **MIT licensed** — free to use in personal and professional projects, with attribution. ## How the utility works Execution flow of google-terminal-search: from user input to parseable results in the terminal. ### 💻 Terminal - Developer shell session (user) - main.sh entry point (compute) ### ⚙️ Script Internals - Argument parser (compute) - Query builder (compute) - curl HTTP fetch (edge) - sed/awk result parser (compute) ### 🌐 External - Google Search (external) ### 📤 Output - stdout parseable text (data) - Downstream grep/fzf/xargs (compute) ### Flows - user -> main_sh: runs with query - main_sh -> arg_parse: passes args - arg_parse -> query_build: validated terms - query_build -> http_fetch: encoded URL - http_fetch -> google: HTTP request - google -> http_fetch: response HTML - http_fetch -> parser: raw HTML - parser -> stdout: URLs + titles - stdout -> pipe: optional pipe ## 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 bash` if needed), `curl` available 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 -3` returns 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 `~/.bashrc` or `~/.zshrc` if you prefer a shorter name. _Full installation and usage examples_ ```bash # 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. ## References - [fernandofatech/google-terminal-search — GitHub](https://github.com/fernandofatech/google-terminal-search) - [Fernando Azevedo — Portfolio](https://fernando.moretes.com) - [fzf — command-line fuzzy finder](https://github.com/junegunn/fzf) - [Google Custom Search JSON API (official alternative)](https://developers.google.com/custom-search/v1/overview) - [Bash Reference Manual — GNU Project](https://www.gnu.org/software/bash/manual/bash.html) ## Links - [GitHub repository](https://github.com/fernandofatech/google-terminal-search) - [Homepage](https://fernando.moretes.com)