O Gemini CLI trouxe a Google para uma corrida que já tinha o Claude Code e o Codex CLI como protagonistas: agentes de IA que vivem dentro do terminal, leem o teu código, executam comandos e editam ficheiros sem que abras um browser. A ferramenta é open source, gratuita para começar e instala-se em menos de cinco minutos, mas a configuração completa (autenticação, servidores MCP, automação) tem detalhes que fazem a diferença entre um agente útil e um que trava a cada segundo comando. Este tutorial cobre os 12 passos completos, desde o npm install até à criação de um agente próprio de revisão de código, com todos os erros que costumam aparecer pelo caminho.

O que é o Gemini CLI e porque ganhou tração em 2026

O Gemini CLI é um agente de IA open source, licenciado sob Apache 2.0, que a Google lançou para trazer os modelos Gemini diretamente para o terminal. Em vez de copiares código para uma janela de chat, o agente lê o teu repositório, sugere alterações, executa comandos de shell e edita ficheiros com a tua autorização. Funciona como concorrente direto do Claude Code (Anthropic) e do Codex CLI (OpenAI), mas com uma diferença clara: o código do agente está publicamente disponível no GitHub, no repositório google-gemini/gemini-cli, o que permite a qualquer developer inspecionar exatamente o que a ferramenta faz antes de lhe dar acesso a uma pasta com código de produção.

A ferramenta ganhou popularidade por dois motivos práticos. Primeiro, integra-se nativamente com o Model Context Protocol (MCP), o standard aberto que já liga o Claude, o Cursor e várias outras ferramentas a fontes de dados externas. Segundo, permite correr tarefas em modo não interativo, o que a torna útil dentro de pipelines de CI e scripts de automação, não só como assistente de conversa. Em agosto de 2026, o repositório oficial continua a receber releases regulares, com a última tag estável marcada como v0.49.0, publicada a 25 de junho de 2026, segundo a própria página de releases no GitHub.

Há uma mudança importante que qualquer tutorial desatualizado vai esconder de ti: desde 18 de junho de 2026, a Google deixou de aceitar o simples login pessoal com conta Google como método de autenticação gratuita para o Gemini CLI. Se seguires um guia de 2025, vais bater numa parede logo no primeiro passo. Este tutorial já reflete o fluxo atual, com chave de API, Vertex AI ou licença empresarial Gemini Code Assist.

Porque usar um agente de terminal em vez do chat no browser

Quem já usa o Gemini através do browser pode perguntar-se porque vale a pena instalar mais uma ferramenta. A resposta está no contexto que o agente consegue ver de uma vez. No chat web, copias e colas trechos de código manualmente, perdes formatação e o modelo nunca vê a estrutura completa do teu repositório. No terminal, o Gemini CLI lê ficheiros diretamente do disco, percorre pastas, executa testes e consulta o histórico do Git sem que precises de copiar nada à mão.

Isto muda o tipo de tarefa que consegues delegar. Em vez de perguntares “como é que normalmente se trata um erro 404 em Express?”, passas a pedir “adiciona tratamento de erro 404 a todos os endpoints em src/routes/ que ainda não o têm” e o agente aplica a alteração a vários ficheiros de uma só vez, mostrando o diff antes de gravar. Também ganhas a possibilidade de encadear o agente com o resto do teu fluxo de trabalho, como scripts de build, hooks de Git ou pipelines de CI, algo que um chat isolado no browser simplesmente não permite.

Há uma contrapartida óbvia: um agente que edita ficheiros e corre comandos precisa de mais confiança da tua parte do que uma janela de chat que só devolve texto. É por isso que a configuração de autenticação, sandbox e permissões, que ocupa boa parte deste tutorial, importa tanto quanto o próprio uso do agente no dia a dia.

Pré-requisitos: o que precisas antes de instalar

Antes de tocar num único comando, confirma que o teu ambiente cumpre estes requisitos. Saltar esta verificação é a causa mais comum de instalações que falham a meio.

RequisitoVersão ou especificação mínimaComo verificar
Node.js20.x ou superiornode -v
npm10.x ou superior (vem com o Node 20)npm -v
Sistema operativoLinux, macOS ou Windows (via WSL recomendado)N/D
Conta Google Cloud ou API keyConta ativa no Google AI Studioaistudio.google.com
TerminalBash, Zsh ou PowerShellN/D
Espaço em discoCerca de 200 MB para o pacote e dependênciasdf -h

Se ainda usas Node 18 ou 16, o instalador não vai bloquear de imediato, mas vais encontrar erros silenciosos em comandos que dependem de APIs mais recentes do runtime. Atualiza o Node primeiro, mesmo que isso pareça um passo extra desnecessário.

Que modelo Gemini corre por trás do CLI: Flash vs Pro

O Gemini CLI não tem um modelo fixo embutido. Em vez disso, encaminha os teus pedidos para o modelo Gemini disponível através do método de autenticação que escolheres, seja a API pública, o Vertex AI ou uma licença Code Assist. Isto tem uma consequência prática direta para o plano gratuito: como só tens acesso à linha de modelos Flash com uma chave de API gratuita, o tamanho de contexto e a profundidade de raciocínio ficam limitados ao que essa família de modelos oferece, tipicamente mais rápida e mais barata, mas menos capaz em tarefas de raciocínio complexo do que a linha Pro.

Na prática, isto significa que o mesmo comando gemini pode comportar-se de forma bastante diferente consoante o método de autenticação configurado. Numa conta pessoal com chave de API gratuita, o agente tende a ser mais conservador em tarefas de refatoração ampla e explica mais antes de agir. Num projeto Vertex AI com faturação ativa e acesso a modelos Pro, o mesmo agente consegue lidar com pedidos mais ambiciosos, como reestruturar um módulo inteiro com múltiplas dependências, sem perder o fio à meada a meio do processo.

Se notares respostas curtas, pedidos de esclarecimento excessivos ou o agente a “esquecer-se” de detalhes mencionados no início de uma sessão longa, o primeiro diagnóstico deve ser sempre o mesmo: confirma que modelo está realmente ativo antes de assumires que há um bug na ferramenta. O comando gemini --version mostra a versão do CLI, mas é dentro da própria sessão, no cabeçalho apresentado ao arrancar, que vês qual modelo está a responder.

Passo 1 a 3: instalar o Gemini CLI

Passo 1: confirma a versão do Node.js. Corre o comando abaixo. Se o resultado for inferior a v20, instala uma versão recente via nvm antes de continuares.

node -v
# esperado: v20.x.x ou superior

# se precisares de atualizar via nvm:
nvm install 20
nvm use 20

Passo 2: instala o pacote globalmente. O pacote oficial chama-se @google/gemini-cli e está disponível no registo npm.

npm install -g @google/gemini-cli

# confirmar que ficou disponível no PATH
gemini --version

Passo 3: alternativas sem instalação global. Se preferires não poluir os pacotes globais da máquina, ou se estiveres apenas a testar, usa o npx. No macOS e Linux também podes instalar via Homebrew.

# correr sem instalar (self-contained, cada execução usa o mesmo executável)
npx @google/gemini-cli

# instalação via Homebrew (macOS/Linux)
brew install gemini-cli

Repara que o pacote é distribuído como executável autocontido: quer instales com npm install -g, quer corras com npx, estás a usar o mesmo binário por trás. A diferença é apenas conveniência, já que a instalação global poupa tempo de arranque em usos frequentes.

Passo 4 e 5: escolher e configurar a autenticação

Este é o passo onde a maioria dos tutoriais antigos falha, porque descreve o fluxo de login pessoal que deixou de funcionar em junho de 2026. Atualmente existem três caminhos válidos, resumidos na tabela abaixo.

MétodoIndicado paraLimite gratuito
Chave de API (Google AI Studio)Uso individual, testes rápidosCerca de 250 pedidos/dia, limitado a modelos da linha Flash
Vertex AIEquipas com projeto Google Cloud ativoDepende da faturação e quotas do projeto
Licença empresarial Gemini Code AssistOrganizações com contrato Google Workspace/CloudDefinido pelo plano contratado

Passo 4: obtém a tua chave de API. Entra em aistudio.google.com, cria um projeto (ou usa um existente) e gera uma chave. Copia-a para um local seguro e nunca a coloques diretamente num script versionado no Git.

# exportar a chave como variável de ambiente (recomendado)
export GEMINI_API_KEY="a_tua_chave_aqui"

# ou guardar num ficheiro de perfil carregado pela tua shell
echo 'export GEMINI_API_KEY="a_tua_chave_aqui"' >> ~/.zshrc
source ~/.zshrc

Passo 5: se usares Vertex AI, autentica com o Google Cloud CLI antes de abrires o Gemini CLI, e define o tipo de autenticação no ficheiro de configuração, como mostramos no próximo passo.

gcloud auth application-default login
gcloud config set project o-teu-projeto-gcp

Passo 6: primeira execução e assistente de configuração

Com a chave definida, corre o comando gemini dentro da pasta de um projeto qualquer. Na primeira execução, a ferramenta pergunta o método de autenticação, o tema visual do terminal e se queres partilhar estatísticas de uso anónimas.

cd ~/os-meus-projetos/app-exemplo
gemini

# saída esperada (resumida):
# > Bem-vindo ao Gemini CLI
# > Método de autenticação: [1] Chave API  [2] Vertex AI  [3] Code Assist
# > Escolhe o tema: [1] Padrão  [2] GitHub  [3] Escuro
# > Ativar telemetria anónima? (s/n)
# Sessão iniciada. Modelo ativo: gemini-flash (nível gratuito)

Nota o detalhe da última linha: se estiveres no plano gratuito com chave de API, o modelo ativo por omissão é da linha Flash, não o modelo Pro mais capaz. Isto é suficiente para tarefas de leitura, resumo e pequenas edições, mas para refatorações complexas em bases de código grandes vais notar diferença de qualidade em relação a um plano pago com acesso a Pro.

Passo 7: personalizar o ficheiro settings.json

O Gemini CLI guarda a configuração num ficheiro JSON, normalmente em ~/.gemini/settings.json para definições globais, ou numa pasta .gemini/ dentro do próprio projeto para definições locais. Isto permite teres um tema e servidores MCP diferentes por projeto.

{
  "selectedAuthType": "vertex-ai",
  "theme": "GitHub",
  "sandbox": true,
  "mcpServers": {
    "gcloud": {
      "command": "npx",
      "args": ["@google-cloud/gcloud-mcp"]
    }
  }
}

O campo "sandbox": true vale a pena destacar, porque ativa a execução de comandos de shell num ambiente isolado, em vez de correrem diretamente na tua máquina. Para quem está a testar o agente pela primeira vez num repositório sensível, isto é a diferença entre um erro reversível e um comando destrutivo mal interpretado.

Passo 8: usar o Gemini CLI no teu primeiro projeto

Com a configuração pronta, o uso do dia a dia acontece em linguagem natural. Pede tarefas concretas, uma de cada vez, e revê sempre o diff antes de aceitares uma alteração.

gemini "lê o ficheiro src/api/users.js e explica o que a função getUserById faz"

# saída esperada:
# A função getUserById recebe um ID, consulta a tabela users
# através do cliente Postgres configurado em db.js, e devolve
# um objeto JSON com os campos id, nome e email. Não trata o
# caso de ID inexistente, devolve undefined em vez de lançar
# um erro 404 explícito.
#
# Sugestão: queres que eu adicione tratamento de erro para IDs
# inexistentes? (s/n)

Este comportamento, explicar antes de agir e pedir confirmação antes de editar ficheiros, é o padrão por omissão. Consegues correr em modo mais autónomo, mas isso implica abrir mão de parte da rede de segurança, algo que discutimos mais à frente na secção sobre segurança.

Passo 9: ligar servidores MCP para expandir capacidades

O verdadeiro poder do Gemini CLI aparece quando o ligas a servidores MCP externos. Cada servidor expõe ferramentas que o agente pode chamar, como interagir com o gcloud, consultar um repositório GitHub ou correr queries numa base de dados. A Google disponibiliza um servidor MCP oficial para o gcloud que se instala com um único comando.

cd ~
npx @google-cloud/gcloud-mcp init --agent=gemini-cli

# o comando regista automaticamente o servidor em
# ~/.gemini/settings.json, dentro de "mcpServers"

Depois de ligado, podes pedir coisas como “lista os buckets do Cloud Storage no projeto atual” e o agente traduz isso numa chamada real ao gcloud através do servidor MCP, sem que precises de sair do terminal ou de decorar a sintaxe exata do comando. O mesmo mecanismo funciona ao contrário: existem projetos da comunidade, como o gemini-cli-mcp, que expõem as ferramentas internas do Gemini CLI a outros clientes MCP, incluindo o Claude Code, permitindo combinar agentes de fornecedores diferentes no mesmo fluxo de trabalho.

Passo 10: criar extensões e comandos personalizados

Além de servidores MCP de terceiros, podes criar extensões próprias para tarefas repetidas na tua equipa, como aplicar o guia de estilo interno ou gerar changelogs num formato específico. Uma extensão é essencialmente uma pasta com um ficheiro de manifesto e, opcionalmente, comandos pré-definidos.

mkdir -p ~/.gemini/extensions/changelog-pt
cat > ~/.gemini/extensions/changelog-pt/manifest.json << 'EOF'
{
  "name": "changelog-pt",
  "description": "Gera changelog em português a partir dos commits",
  "commands": {
    "changelog": "Analisa os ultimos commits do git log e escreve um changelog em portugues europeu, agrupado por tipo (Novo, Correcao, Alterado)."
  }
}
EOF

A partir daqui, corres gemini /changelog dentro de qualquer repositório e o agente aplica a instrução guardada, sem que tenhas de escrever o mesmo prompt sempre que precisas de gerar as notas de lançamento.

Passo 11: automação com o modo não interativo

Para usar o Gemini CLI dentro de pipelines de CI ou scripts de automação, evita o modo conversacional e usa a flag de prompt direto, que devolve a resposta e termina o processo sem esperar por confirmação manual.

#!/bin/bash
# script: revisar-pr.sh
# Corre numa pipeline de CI para gerar um resumo automático de um PR

DIFF=$(git diff origin/main...HEAD)

gemini --prompt "Reve este diff e assinala apenas problemas de seguranca
ou bugs obvios. Se direto, sem introducoes: $DIFF" > resumo-revisao.txt

cat resumo-revisao.txt

Em pipelines, define sempre um limite de tempo à volta da chamada, porque um pedido mal formulado pode levar o agente a tentar chamadas de ferramentas em loop antes de desistir sozinho.

Passo 12: gerir limites gratuitos e monitorizar utilização

Se estiveres no plano gratuito com chave de API, o limite prático ronda os 250 pedidos por dia, restrito à linha de modelos Flash. Para equipas, isto esgota-se depressa num dia de uso intensivo. Duas práticas ajudam a esticar a quota: agrupar perguntas relacionadas num único pedido em vez de várias chamadas pequenas, e usar o modo não interativo apenas para tarefas que realmente precisam do agente, não para substituir um simples comando de pesquisa em texto.

Para monitorizar consumo em projetos Vertex AI, usa a consola do Google Cloud e ativa alertas de orçamento antes de a equipa começar a usar o agente em produção. Um agente que corre em CI a cada push pode gerar uma fatura surpreendentemente alta se ninguém tiver definido um teto.

5 casos de uso reais para o Gemini CLI esta semana

Antes de avançares para o projeto completo, vale a pena veres exemplos concretos de tarefas onde o Gemini CLI poupa tempo real, sem exigir nenhuma configuração além da que já fizeste até aqui.

  • Explorar uma base de código desconhecida: pede ao agente para mapear a estrutura de um repositório que acabaste de clonar, identificar o ponto de entrada da aplicação e listar as dependências externas mais usadas, uma tarefa que normalmente demora vários minutos de navegação manual.
  • Escrever testes para código legado: aponta o agente a uma função sem cobertura de testes e pede casos de teste que cubram os caminhos principais e os casos limite óbvios, revendo sempre o resultado antes de aceitares.
  • Migrar sintaxe entre versões de uma linguagem: usa o agente para converter callbacks em promises, ou funções de classe em componentes funcionais, aplicando o mesmo padrão a múltiplos ficheiros de uma só vez.
  • Preparar notas de lançamento: combina o comando de extensão personalizada que criaste no Passo 10 com o histórico de commits para gerar um rascunho de changelog em minutos, em vez de escreveres à mão.
  • Depurar um erro com stack trace longo: cola o stack trace completo e pede ao agente para localizar a linha de código responsável e propor uma correção, poupando o tempo de percorrer manualmente vários ficheiros.

Projeto completo: um agente de revisão de pull requests

Junta tudo o que viste até aqui num projeto funcional: um script que corre automaticamente sempre que abres um pull request, resume as alterações e assinala riscos, publicando o resultado como ficheiro de saída para revisão. Cria a seguinte estrutura de pastas.

meu-projeto/
├── .gemini/
│   └── settings.json
├── .github/
│   └── workflows/
│       └── revisao-gemini.yml
└── scripts/
    └── revisar-pr.sh

O ficheiro de workflow do GitHub Actions instala o Gemini CLI, injeta a chave a partir dos secrets do repositório e corre o script de revisão em cada pull request.

name: Revisao automatica com Gemini CLI
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  revisao:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @google/gemini-cli
      - run: chmod +x scripts/revisar-pr.sh && ./scripts/revisar-pr.sh
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

Com isto em produção, cada PR novo recebe um resumo automático em segundos, antes mesmo de um revisor humano abrir o código. Não substitui a revisão de um colega, mas apanha erros óbvios, como variáveis não usadas, segredos esquecidos num commit ou funções sem tratamento de erro, antes que cheguem a essa fase.

Gemini CLI vs Claude Code vs Codex CLI

Os três agentes de terminal resolvem o mesmo problema com filosofias diferentes. O Gemini CLI aposta em ser open source e MCP-first, com o código do agente publicado no GitHub sob Apache 2.0 e integração nativa tanto como cliente como servidor MCP. O Claude Code, da Anthropic, foca-se em fluxos de trabalho profundos dentro de bases de código grandes e é frequentemente citado por developers como referência em tarefas de refatoração extensa. O Codex CLI, da OpenAI, segue um caminho semelhante ao Gemini CLI em termos de integração com o ecossistema de ferramentas da própria empresa.

CritérioGemini CLIClaude CodeCodex CLI
LicençaOpen source (Apache 2.0)ProprietárioProprietário
Suporte MCPNativo, cliente e servidorNativo, clienteSuporte crescente
Autenticação gratuitaChave API (~250 pedidos/dia, modelos Flash)Depende do plano AnthropicDepende do plano OpenAI
Instalaçãonpm, Homebrew, npxnpmnpm, Homebrew
Integração cloud nativaGoogle Cloud / Vertex AINenhuma específicaNenhuma específica

Na prática, escolher entre os três costuma resumir-se ao ecossistema onde já trabalhas. Se a tua equipa já vive no Google Cloud, o Gemini CLI encaixa-se sem fricção adicional. Nada impede, aliás, de correres os três em paralelo em projetos diferentes, dado que todos aceitam ser orquestrados via MCP.

Antigravity CLI: a alternativa para quem só quer login simples

Depois de fechar o login pessoal gratuito do Gemini CLI em junho de 2026, a Google não deixou os utilizadores individuais sem opção. Passou a recomendar o Antigravity CLI, um binário separado escrito em Go, identificado pelo comando agy, como caminho mais simples para quem só quer experimentar um agente de IA no terminal sem configurar chaves de API ou projetos Google Cloud. Se o teu objetivo é uma experiência rápida de fim de semana, sem qualquer intenção de integrar o agente em CI ou em fluxos empresariais, vale a pena verificar primeiro se o Antigravity CLI cobre a tua necessidade antes de passares pela configuração mais elaborada de autenticação do Gemini CLI descrita neste tutorial.

Para equipas e projetos que precisam de automação, integração MCP profunda ou uso em pipelines, o Gemini CLI continua a ser a escolha correta, precisamente pelas capacidades que o Antigravity CLI não se propõe a substituir.

Erros comuns ao configurar o Gemini CLI

Estes são os erros que mais aparecem em relatos de utilizadores e nos próprios fóruns de suporte da ferramenta.

  • Seguir tutoriais que mencionam login pessoal com Google. Esse caminho fechou-se em junho de 2026. Se um guia não mencionar chave de API ou Vertex AI, está desatualizado.
  • Colocar a chave de API diretamente no código. Usa sempre variáveis de ambiente ou um gestor de secrets. Uma chave exposta num repositório público é encontrada por scanners automáticos em minutos.
  • Ignorar o modo sandbox em repositórios sensíveis. Sem "sandbox": true, comandos de shell sugeridos pelo agente correm diretamente no teu sistema.
  • Esperar qualidade de modelo Pro no plano gratuito. O nível gratuito usa modelos Flash. Para tarefas complexas de arquitetura, a diferença de qualidade nota-se.
  • Não definir timeout em scripts de CI. Um pedido em modo não interativo sem limite de tempo pode prender uma pipeline inteira à espera de resposta.
  • Misturar configurações globais e locais sem perceber a prioridade. As definições em .gemini/ dentro do projeto sobrepõem-se às globais em ~/.gemini/, o que confunde quem espera o comportamento inverso.

Nenhum destes erros é grave isoladamente, mas combinados custam horas de depuração a quem está a testar a ferramenta pela primeira vez. Reserva a primeira sessão com o Gemini CLI para um repositório de testes, sem código de produção, e só avança para projetos reais depois de teres confirmado que a autenticação, o sandbox e os servidores MCP que precisas estão configurados como esperas.

Resolução de problemas: os erros mais frequentes

Quando algo corre mal, a maioria dos casos cai numa destas oito categorias. Confirma o sintoma na tabela antes de abrires uma issue no repositório do GitHub, porque grande parte destes problemas resolve-se localmente em menos de um minuto.

SintomaCausa provávelSolução
"command not found: gemini"Pacote instalado sem acesso ao PATH global do npmConfirma com npm config get prefix e adiciona o caminho ao PATH da shell
Erro de autenticação ao abrir o CLITentativa de login pessoal, já descontinuadoGera uma chave de API em aistudio.google.com e exporta GEMINI_API_KEY
"quota exceeded" a meio do diaLimite diário de 250 pedidos no plano gratuito atingidoAguarda o reset diário ou migra para Vertex AI com faturação ativa
Instalação falha com erros de permissõesnpm global a exigir sudo em alguns sistemasUsa nvm para gerir Node sem permissões de root, evita sudo npm install -g
Servidor MCP não aparece nas ferramentas disponíveisErro de sintaxe no bloco mcpServers do settings.jsonValida o JSON com python3 -m json.tool ~/.gemini/settings.json
Respostas lentas ou a cortar a meioContexto demasiado grande enviado para um modelo FlashReduz o âmbito do pedido ou muda para um modelo Pro se tiveres acesso
Agente sugere comandos destrutivos sem avisoModo sandbox desativadoAtiva "sandbox": true no settings.json antes de dares acesso a um repositório real
Pipeline de CI trava indefinidamenteChamada em modo não interativo sem timeout definidoEnvolve o comando com um limite de tempo explícito, por exemplo timeout 120 gemini --prompt "..."

Dicas avançadas para tirar mais partido da ferramenta

Depois de dominares o básico, há ajustes que fazem diferença real no dia a dia. Cria perfis de configuração separados por tipo de projeto, um para scripts pessoais com sandbox ativo por omissão, outro para repositórios de produção com permissões mais restritas. Usa o histórico de comandos do próprio agente para construir uma biblioteca de prompts reutilizáveis, guardados como extensões, em vez de reescreveres a mesma instrução todas as semanas.

Combina o Gemini CLI com o servidor MCP do GitHub para automatizar tarefas que hoje fazes manualmente, como etiquetar issues por prioridade a partir da descrição, ou gerar um primeiro rascunho de notas de lançamento a partir dos commits fechados desde a última tag. E se a tua equipa já usa Claude Code para certas tarefas, lembra-te de que os dois podem coexistir. O projeto comunitário gemini-cli-mcp expõe as ferramentas internas do Gemini CLI a clientes MCP como o Claude Code, o que evita teres de escolher um agente único para toda a equipa.

Outra prática que compensa é manter um ficheiro de contexto na raiz do repositório, com convenções de nomenclatura, decisões de arquitetura e padrões de teste que a equipa segue. O agente lê este ficheiro automaticamente no arranque de cada sessão, o que reduz drasticamente o número de vezes que precisas de repetir as mesmas regras dentro de um prompt. Equipas que adotam esta prática relatam sessões mais curtas e sugestões mais alinhadas com o estilo de código já existente, em vez de sugestões genéricas que depois precisam de ser ajustadas manualmente.

Segurança: o que considerar antes de dar acesso de shell a um agente

Um agente que lê o teu repositório, edita ficheiros e executa comandos de shell é, por definição, uma superfície de ataque nova. A própria Google recomenda inspecionar o código aberto do agente antes de o correr em ambientes sensíveis, precisamente porque a licença Apache 2.0 permite essa auditoria. Na prática, três cuidados cobrem a maioria dos riscos.

  • Corre o agente apenas em pastas de confiança. Nunca apontes o Gemini CLI para um diretório com ficheiros de origem desconhecida sem reveres primeiro o conteúdo.
  • Revê sempre os comandos de shell sugeridos antes de aceitares a execução automática, sobretudo comandos que apagam, movem ou publicam ficheiros.
  • Configura servidores MCP com o mínimo de permissões necessário. Um servidor MCP mal configurado, como um que dê acesso total ao gcloud sem restrição de projeto, pode expor recursos de cloud que nada têm a ver com a tarefa original.

Guarda sempre as tuas credenciais, chave de API e credenciais do Vertex AI, fora do controlo de versões, e trata o ficheiro settings.json como qualquer outro ficheiro de configuração sensível, com permissões de leitura restritas ao teu utilizador.

Para equipas maiores, vale a pena tratar a adoção do Gemini CLI como qualquer outra ferramenta com acesso privilegiado ao código: definir num documento interno quais os repositórios onde o agente pode correr sem supervisão, quais exigem sempre revisão humana antes de qualquer commit, e quem é responsável por rodar as chaves de API caso uma delas seja exposta acidentalmente. Um agente de IA com acesso de shell não introduz um risco fundamentalmente diferente de um script de automação mal escrito, mas introduz um risco menos previsível, porque as instruções em linguagem natural podem ser interpretadas de formas que não anteciparias com um script determinístico.

Com os 12 passos, o projeto completo e a tabela de resolução de problemas cobertos, já tens tudo o que precisas para correr o Gemini CLI em produção, não apenas como curiosidade de fim de semana. O próximo movimento natural é escolher um repositório pequeno da tua equipa, aplicar a configuração de sandbox e MCP descrita aqui, e só depois expandir para projetos maiores à medida que ganhas confiança no comportamento do agente.

Perguntas frequentes sobre o Gemini CLI

O Gemini CLI é mesmo gratuito?

Sim, o código é open source e a ferramenta em si não tem custo. O que pode ter custo é o uso da API por trás dela: o plano gratuito com chave de API do AI Studio está limitado a cerca de 250 pedidos por dia em modelos Flash. Para uso intensivo, precisas de ativar faturação no Vertex AI ou obter uma licença Code Assist.

Preciso de uma conta Google Cloud para usar o Gemini CLI?

Não obrigatoriamente. Uma chave de API do Google AI Studio chega para uso individual. Uma conta Google Cloud só é necessária se quiseres usar Vertex AI ou servidores MCP como o gcloud-mcp.

O Gemini CLI funciona offline?

Não. É um cliente que envia pedidos para os modelos Gemini na cloud da Google. Sem ligação à internet, o agente não consegue processar pedidos.

Posso usar o Gemini CLI e o Claude Code no mesmo projeto?

Sim. Como ambos suportam MCP, podes ligá-los entre si ou usá-los em paralelo em tarefas diferentes, sem conflito direto entre as ferramentas.

O que aconteceu ao login pessoal gratuito com conta Google?

Foi descontinuado a 18 de junho de 2026 para utilizadores individuais do Gemini CLI. A Google passou a recomendar uma ferramenta separada, o Antigravity CLI, para quem procura esse fluxo mais simples, mantendo o Gemini CLI focado em utilizadores com chave de API, Vertex AI ou licença empresarial.

É seguro deixar o Gemini CLI executar comandos automaticamente?

Só com o modo sandbox ativado e revisão cuidada das permissões dos servidores MCP ligados. Sem essas precauções, o agente tem acesso direto ao teu sistema de ficheiros e shell.

Qual é a diferença entre o Gemini CLI e o Gemini Code Assist?

O Gemini Code Assist é o produto mais amplo da Google para assistência de código, disponível também como extensão de IDE. O Gemini CLI é especificamente o agente de terminal, que pode usar uma licença Code Assist como método de autenticação.

Consigo usar o Gemini CLI em Windows?

Sim, mas a experiência mais estável é através do WSL (Windows Subsystem for Linux). A instalação direta em PowerShell funciona, mas alguns comandos de shell sugeridos pelo agente assumem sintaxe Unix.

Quanto custa efetivamente usar o Gemini CLI todos os dias?

Para um developer individual dentro do limite de 250 pedidos diários no plano gratuito, o custo é zero. Acima desse limite, ou se precisares de modelos Pro, o custo passa a depender do preço por token cobrado pela API Gemini ou pelas quotas de faturação configuradas no teu projeto Vertex AI, que variam consoante o volume mensal contratado.

O Gemini CLI substitui um IDE com extensão de IA?

Não por completo. O Gemini CLI destaca-se em tarefas amplas, como analisar um repositório inteiro, automatizar scripts ou correr em CI, enquanto uma extensão de IDE costuma ser mais rápida para edições pequenas e localizadas, com sugestões enquanto escreves. Muitos developers usam os dois em conjunto, cada um para o tipo de tarefa onde é mais eficiente.

Fontes: repositório oficial no GitHub, anúncio oficial da Google, documentação do Gemini CLI, documentação do Google Cloud, codelab oficial sobre MCP e especificação do Model Context Protocol.