# google-terminal-search

Busca no Google sem sair do terminal — um script em Bash, zero dependência além do shell.

- URL: https://fernando.moretes.com/open-source/google-terminal-search

- Markdown: https://fernando.moretes.com/open-source/google-terminal-search/guide.md?lang=pt

- GitHub: https://github.com/fernando-moretes/tool-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-09-08T20:36:12Z

---

Um utilitário de linha de comando, escrito em Bash puro, que recebe a consulta como argumento, monta a URL de busca do Google e a entrega ao navegador padrão — para quem passa o dia no terminal e não quer trocar de janela para procurar uma mensagem de erro.

## Por que isso existe

Depois de 16 anos operando plataformas em produção, a maior parte do meu dia acontece em um terminal: `aws`, `terraform`, `kubectl`, `git`, logs. O ciclo mais frequente é ler uma exceção — `AccessDeniedException`, `CrashLoopBackOff`, um erro do `pnpm` — e precisar procurá-la. Cada busca exige o mesmo ritual: copiar o texto, trocar para o navegador, colar, voltar. Parece barato; não é. São 5 a 10 segundos por busca, dezenas de vezes por dia, e o custo real não é o tempo — é a quebra de contexto. Quando volto ao terminal, perdi o fio do que estava depurando.

**O que este repositório resolve:** encurtar esse ciclo a um comando. Você digita a consulta onde já está, e o navegador abre com o resultado. O texto nunca passa pela área de transferência, então não sobrescreve o que você tinha copiado antes.

**O que ele deliberadamente não faz:** não raspa a página de resultados do Google. Uma ferramenta que baixa o HTML de busca com `curl` funciona por uma semana e depois começa a receber CAPTCHA e bloqueio por IP — eu já mantive uma dessas e o custo de manutenção não compensa um utilitário de conveniência. Delegar a renderização ao navegador é a decisão que mantém o script pequeno e sem manutenção.

## O que importa

- **Uma dependência:** Bash e um navegador. Nada de Python, Node ou chave de API — instala em segundos e continua funcionando depois de trocar de máquina.
- **A consulta vem dos argumentos:** `"$@"` vira a query, então o texto com espaços e aspas chega inteiro ao Google.
- **Abre no navegador padrão:** a busca é renderizada por quem sabe renderizá-la, com sua sessão e suas preferências.
- **Portável entre macOS e Linux:** a única diferença entre os dois é o comando que abre URL, e isso é um `if` no script.
- **Versionado pela mesma esteira dos outros repositórios:** lint de PR, CI, varredura de segurança e release saem dos workflows reutilizáveis do `platform`.

## O caminho de uma busca

Do argumento no shell até a aba do navegador. Nenhum serviço próprio no meio — o script só monta a URL e delega.

### 💻 Shell — o script

- Argumentos "$@" → query (compute)
- URL-encode espaço, aspas, & (compute)
- URL montada google.com/search?q= (compute)
- Abridor de URL open | xdg-open (edge)

### 🌐 Externo — fora do seu controle

- Navegador padrão sessão do usuário (frontend)
- Google Search renderiza o resultado (external)

### Fluxos

- user -> args: digita a consulta
- args -> encode
- encode -> url
- url -> opener
- opener -> browser: entrega a URL
- browser -> google: GET /search?q=…
- google -> browser: HTML dos resultados

## Instalar e usar

1. **Clone o repositório** — `git clone https://github.com/fernando-moretes/tool-google-terminal-search.git` — é um repositório pequeno; o clone completo leva menos de um segundo.

2. **Leia o script antes de dar permissão de execução** — `head -40` no arquivo. É um script de shell que vai rodar com as suas permissões; ler 40 linhas custa menos que confiar cegamente. O cabeçalho também é onde estão as opções que o README não documenta.

3. **Dê permissão de execução e coloque no PATH** — `chmod +x` no script e um link simbólico em `~/.local/bin` (ou `~/bin`, se for o que você já usa). Evite `/usr/local/bin` para ferramenta pessoal — precisa de `sudo` e some no próximo upgrade do sistema.

4. **Confirme que o abridor de URL existe** — No macOS, `open` vem com o sistema. No Linux de desktop, `xdg-open` vem do pacote `xdg-utils` — em imagens mínimas e em servidores ele não está lá, e o script vai falhar com `command not found` em vez de abrir nada.

5. **Rode com a consulta como argumento** — Passe a consulta entre aspas quando ela tiver caracteres que o shell interpreta — `&`, `|`, `>`, parênteses. Mensagem de erro copiada de log quase sempre tem um deles.

_Instalação em quatro comandos e uma primeira busca. Ajuste o nome do link ao que você prefere digitar._

```bash
git clone https://github.com/fernando-moretes/tool-google-terminal-search.git
cd tool-google-terminal-search
head -40 *.sh                      # leia antes de executar
chmod +x *.sh
mkdir -p ~/.local/bin
ln -sf "$PWD"/*.sh ~/.local/bin/gs  # 'gs' é só a minha escolha de nome

# primeira busca — aspas porque a mensagem tem parênteses
gs "AccessDeniedException is not authorized to perform sts:AssumeRole"
```

## Como funciona por dentro

Um script desse tamanho tem três partes, e cada uma tem um modo de falha próprio.

**Coleta dos argumentos:** a consulta é `"$*"` ou `"$@"` juntado com espaço. A diferença importa: sem as aspas, o Bash quebra a consulta em palavras e recola com um espaço só, o que destrói espaços duplos e qualquer glob — um `*` na mensagem de erro vira a lista de arquivos do diretório atual.

**Codificação da URL:** o Google aceita espaço como `+` ou `%20`, mas `&`, `#` e `%` precisam virar `%26`, `%23` e `%25` — senão o `&` corta a query no meio e o `#` vira fragmento que nem chega ao servidor. Em Bash puro, isso é um loop sobre os bytes com `printf '%%%02X'`, ou um `sed` com a tabela de escape. Não há biblioteca; há uma dúzia de linhas que você consegue auditar.

**Entrega ao navegador:** aqui está a única bifurcação por sistema. `open "$url"` no macOS, `xdg-open "$url"` no Linux, detectados por `uname` ou por `command -v`. No WSL, o caminho útil é `wslview` ou `cmd.exe /c start` — se o script não tratar esse caso, a URL abre dentro do Linux, sem navegador, e falha em silêncio.

A lição por trás de manter isso em Bash em vez de Python: o custo de um utilitário assim não é escrevê-lo — é mantê-lo funcionando em toda máquina nova por anos. Bash está em todas elas.

> **O que o README não diz — e por quê:** O README deste repositório é o cabeçalho padrão da minha esteira: tipo, linguagem, temas e as regras de contribuição. Ele não lista as flags do script. Isso é uma escolha de manutenção, não um esquecimento: um script de uma tela documenta a si mesmo no cabeçalho, e um README que repete as flags fica desatualizado no segundo commit. Se o que você precisa não está nas primeiras 40 linhas do arquivo, abra uma issue — é mais útil que eu adivinhar aqui.

## O que um script de 50 linhas tem a ver com esteira de release

Este repositório é pequeno de propósito e, ainda assim, passa pela mesma régua que os meus repositórios maiores. As regras vêm do `platform`: branch nomeada como `<tipo>/<escopo>` (`feat/`, `fix/`, `chore/`, `docs/`), commit e título de PR em Conventional Commits, e a versão calculada a partir dos commits — ninguém escreve número de versão à mão. O `pr-lint`, o CI, a varredura de segurança e o release são workflows reutilizáveis chamados daqui; corrigir a régua é mudar um arquivo lá, não em cada repositório.

O motivo de aplicar isso a um utilitário de shell é o mesmo de aplicar a um Lambda: o custo de uma convenção é pago uma vez, e a exceção é paga toda vez que alguém abre o repositório e pergunta "por que este é diferente?". Depois de manter dezenas de repositórios, aprendi que o que quebra não é a regra rigorosa — é a regra com exceção.

**O que isso significa para quem contribui:** um PR com título fora do padrão falha no lint antes de qualquer revisão humana. Não é burocracia; é o que permite que o changelog e a tag saiam sem que eu toque em nada.

## Perguntas que aparecem

### Funciona em servidor sem interface gráfica?

Não como está: sem navegador não há onde abrir a URL. Nesse cenário, o útil é imprimir a URL montada e colá-la na máquina com interface — ou usar um navegador em modo texto como `w3m`, aceitando que o Google vai servir uma página bem diferente.

### Por que não usar um alias no `.zshrc`?

Um alias de uma linha resolve o caso feliz e quebra no primeiro `&` ou `#` da consulta. O que justifica um repositório é a codificação de URL e a detecção de sistema — e o fato de que versionado, ele viaja para a próxima máquina junto com o resto do meu ambiente.

### Dá para trocar o Google por outro buscador?

A URL base é uma string no script; trocar para DuckDuckGo é mudar `google.com/search?q=` por `duckduckgo.com/?q=`. Se fizer isso, mude também o nome do link no PATH — `gs` abrindo DuckDuckGo é o tipo de surpresa que custa dez minutos de confusão daqui a seis meses.

### Isso viola os termos do Google?

Abrir uma URL de busca no seu próprio navegador é o que você faz ao digitar na barra de endereço — não há automação contra o serviço. O que os termos proíbem é raspagem automatizada dos resultados, e é exatamente o que este script não faz.

## Referências

- [fernando-moretes/tool-google-terminal-search — GitHub](https://github.com/fernando-moretes/tool-google-terminal-search)
- [fernando.moretes.com — portfólio e artigos](https://fernando.moretes.com)
- [fernandofatech/platform — convenções e workflows reutilizáveis](https://github.com/fernandofatech/platform)
- [Conventional Commits 1.0.0](https://www.conventionalcommits.org)
- [xdg-open — freedesktop.org xdg-utils](https://www.freedesktop.org/wiki/Software/xdg-utils/)

## Quando usar — e quando não

Use quando: você passa a maior parte do dia num terminal em macOS ou Linux de desktop, procura mensagem de erro dezenas de vezes por dia, e quer uma ferramenta que não exige runtime nem chave de API para continuar funcionando na próxima máquina. Não use quando: o ambiente é headless, ou você precisa dos resultados como dados — para isso, o caminho honesto é a Custom Search JSON API do Google, com chave, cota de 100 consultas gratuitas por dia e custo por bloco de mil acima disso, não um script que finge ser navegador. O valor deste repositório não está na sofisticação — está em custar zero de manutenção por anos.

## Links

- [GitHub repository](https://github.com/fernando-moretes/tool-google-terminal-search)
- [Homepage](https://fernando.moretes.com)