Resposta rápida: para instalar Gemini CLI no Windows, instale o Node.js 20 ou superior, abra o PowerShell e rode npm install -g @google/gemini-cli. Depois feche e reabra o terminal, execute gemini, escolha o método de login e teste um comando simples dentro da pasta do projeto.
O Gemini CLI é o agente de IA do Google para terminal. Ele permite conversar com Gemini dentro do projeto, pedir análise de arquivos, editar código, executar tarefas e automatizar fluxos sem depender só da interface web.
Este guia é o par natural dos tutoriais de como instalar Claude Code no Windows e como instalar Codex no Windows. A lógica é a mesma: instalar com segurança, autenticar, validar o comando e só então usar em um projeto real.
- Comando principal:
npm install -g @google/gemini-cli. - Comando para abrir:
gemini. - Requisito oficial: Node.js 20.0.0 ou superior.
- Windows recomendado: Windows 11 24H2 ou superior.
- Login mais simples: entrar com uma conta Google no navegador.
- Uso técnico: também dá para autenticar com Gemini API key ou Vertex AI.
O que é Gemini CLI?
Gemini CLI é uma ferramenta de linha de comando do Google que leva o Gemini para o terminal.
Em vez de abrir o Gemini no navegador, copiar código e colar em arquivos, você roda o comando gemini dentro da pasta do projeto. A partir daí, pode pedir tarefas como:
- explicar a estrutura do projeto;
- resumir arquivos;
- sugerir alterações;
- gerar código;
- investigar bugs;
- criar scripts;
- trabalhar com arquivos locais;
- automatizar tarefas repetitivas.
Segundo o repositório oficial no GitHub, o Gemini CLI é um agente open-source que traz o Gemini diretamente para o terminal. Segundo a documentação oficial, ele pode ser instalado por npm, Homebrew, MacPorts ou Anaconda, mas no Windows o caminho mais direto é o npm.
Antes de instalar: aviso importante sobre planos
Antes de seguir, vale uma ressalva.
A documentação oficial do Gemini CLI exibe um aviso dizendo que, para usuários do plano gratuito e Google One, o Gemini CLI será substituído pelo Antigravity CLI em 18 de junho. Isso não apaga o valor do tutorial, mas muda a decisão de quem está começando agora.
Na prática:
| Situação | Melhor leitura |
|---|---|
| Você tem Google AI Pro, Ultra, conta corporativa ou usa Google Cloud | Gemini CLI ainda faz sentido testar. |
| Você usa só conta gratuita ou Google One | Verifique se Antigravity CLI já é o caminho recomendado para sua conta. |
| Você quer comparar agentes de terminal | Instalar Gemini CLI ajuda a entender a diferença contra Codex e Claude Code. |
| Você quer algo estável para trabalho diário | Confirme planos, quotas e roadmap antes de depender da ferramenta. |
Requisitos para instalar Gemini CLI no Windows
Pela documentação oficial, os requisitos recomendados são:
| Item | Requisito |
|---|---|
| Sistema operacional | Windows 11 24H2 ou superior |
| Runtime | Node.js 20.0.0 ou superior |
| Shell | PowerShell |
| Memória para uso casual | 4 GB+ de RAM |
| Memória para uso pesado | 16 GB+ de RAM |
| Internet | Obrigatória |
Se você usa Windows 10, pode até encontrar tutoriais antigos funcionando, mas o requisito oficial atual fala em Windows 11 24H2+.
Passo 1: instale o Node.js
O Gemini CLI usa Node.js. Sem Node/npm, o comando de instalação não funciona.
Abra o PowerShell e confira se você já tem Node:
“powershell node --version “
Depois confira o npm:
“powershell npm --version “
Se o comando não existir ou a versão do Node for menor que 20, instale uma versão atual do Node.js pelo instalador oficial ou pelo gerenciador que você já usa no Windows.
Depois feche e reabra o PowerShell.
Passo 2: instale Gemini CLI com npm
Com Node e npm funcionando, rode:
“powershell npm install -g @google/gemini-cli “
Esse comando instala o pacote global do Gemini CLI.
Quando terminar, feche e reabra o PowerShell. Isso evita erro de PATH antigo.
Passo 3: confirme se o comando gemini funciona
Rode:
“powershell gemini “
Se tudo estiver certo, o Gemini CLI abre e pede autenticação.
Se quiser apenas rodar sem instalar de forma permanente, a documentação oficial também mostra:
“powershell npx @google/gemini-cli “
Use npx quando você quer testar antes de instalar globalmente. Use npm install -g quando pretende usar com frequência.
Passo 4: faça login no Gemini CLI
O Gemini CLI tem mais de um método de autenticação. Para a maioria das pessoas no computador local, o Google recomenda começar com login usando conta Google.
Opção 1: login com Google
Rode:
“powershell gemini “
Escolha Sign in with Google. O CLI abre o navegador, você entra com a conta Google e as credenciais ficam em cache local para sessões futuras.
Esse é o caminho mais simples para uso individual.
Opção 2: Gemini API key
Se você prefere usar uma chave do Google AI Studio, configure a variável de ambiente:
“powershell $env:GEMINI_API_KEY="SUA_CHAVE_AQUI" “
Depois rode:
“powershell gemini “
Escolha Use Gemini API key.
Use API key quando você quer rodar em ambiente sem navegador, script, automação ou fluxo mais técnico. Trate a chave como segredo: não cole em post, print, GitHub, log ou arquivo público.
Opção 3: Vertex AI
Se você trabalha com Google Cloud, também pode usar Vertex AI. Nesse caso, normalmente precisa configurar:
“powershell $env:GOOGLE_CLOUD_PROJECT="SEU_PROJECT_ID" $env:GOOGLE_CLOUD_LOCATION="us-central1" “
Ambientes corporativos podem exigir projeto Google Cloud, credenciais do gcloud, service account ou política interna.
Primeiro uso: rode dentro de uma pasta de projeto
Depois de autenticar, entre em uma pasta:
“powershell cd C:\caminho\do\projeto “
Abra o Gemini CLI:
“powershell gemini “
Comece com pedidos pequenos:
- "Explique a estrutura deste projeto antes de editar qualquer coisa."
- "Leia o README e diga como rodar localmente."
- "Liste os arquivos mais importantes para entender o projeto."
- "Encontre possíveis pontos de erro neste script."
- "Crie um plano de alteração, mas não edite arquivos ainda."
O melhor primeiro teste não é pedir para refatorar tudo. É pedir leitura, diagnóstico e plano.
Comandos úteis do Gemini CLI no Windows
| Tarefa | Comando |
|---|---|
| Instalar globalmente | npm install -g @google/gemini-cli |
| Rodar o CLI | gemini |
| Testar sem instalar | npx @google/gemini-cli |
| Definir API key na sessão atual | $env:GEMINI_API_KEY="SUA_CHAVE_AQUI" |
| Entrar em uma pasta | cd C:\caminho\do\projeto |
O comando mais importante é simples: gemini.
O resto depende do seu método de instalação e login.
Gemini CLI vs Codex vs Claude Code
Gemini CLI entra na mesma categoria de ferramentas como Codex e Claude Code: agentes de IA para terminal.
| Ferramenta | Empresa | Comando | Melhor quando |
|---|---|---|---|
| Gemini CLI | gemini |
Você usa Google/Gemini/Google Cloud e quer testar agente no terminal | |
| Codex | OpenAI | codex |
Você usa ChatGPT/OpenAI e quer trabalhar em projetos pelo terminal |
| Claude Code | Anthropic | claude |
Você usa Claude e quer um fluxo forte de programação no terminal |
Se você quer instalar as alternativas para comparar, veja:
- Como instalar Claude Code no Windows
- Como instalar Codex no Windows
- Codex vs Claude Code vs Gemini CLI
O comparativo justo não é "qual IA é melhor" em abstrato. É rodar a mesma tarefa real nas três ferramentas e comparar:
- qualidade da resposta;
- segurança antes de editar;
- clareza do plano;
- velocidade;
- custo/limites;
- facilidade de login;
- capacidade de entender o projeto.
Erros comuns ao instalar Gemini CLI no Windows
npm não é reconhecido
Isso significa que o Node.js/npm não está instalado ou não está no PATH.
Resolva assim:
- Instale Node.js 20 ou superior.
- Feche e reabra o PowerShell.
- Rode
node --version. - Rode
npm --version.
gemini não é reconhecido
Prováveis causas:
- instalação global não terminou;
- o terminal não recarregou PATH;
- npm global está fora do PATH.
Tente:
“powershell npm install -g @google/gemini-cli “
Depois feche e reabra o terminal.
O login não abre no navegador
Se estiver em computador local, tente rodar de novo:
“powershell gemini “
Se estiver em servidor, ambiente remoto ou terminal sem navegador, use API key com GEMINI_API_KEY.
A API key não funciona
Confira:
- se a chave veio do Google AI Studio;
- se você escreveu a variável corretamente;
- se não deixou aspas ou espaços extras;
- se está usando
GEMINI_API_KEY, não outro nome; - se a chave não foi revogada.
Para a sessão atual no PowerShell:
“powershell $env:GEMINI_API_KEY="SUA_CHAVE_AQUI" “
Conta corporativa pede projeto Google Cloud
Segundo a documentação oficial, contas de empresa, escola, Google Workspace ou licenças relacionadas ao Gemini Code Assist podem exigir configuração de projeto Google Cloud.
Nesse caso, você pode precisar definir:
“powershell $env:GOOGLE_CLOUD_PROJECT="SEU_PROJECT_ID" “
E seguir o fluxo da sua organização.
Windows antigo ou Node antigo
Se você está em Windows 10 ou Node 18, pode achar tutoriais antigos dizendo que funciona. Mas o requisito oficial atual é Windows 11 24H2+ e Node.js 20+.
Para um tutorial que envelheça melhor, siga o requisito oficial, não o "funcionou no meu PC".
Checklist rápido
- [ ] Confirmar Windows 11 24H2+.
- [ ] Instalar Node.js 20+.
- [ ] Abrir PowerShell.
- [ ] Rodar
node --version. - [ ] Rodar
npm --version. - [ ] Rodar
npm install -g @google/gemini-cli. - [ ] Fechar e reabrir PowerShell.
- [ ] Rodar
gemini. - [ ] Fazer login com Google ou API key.
- [ ] Entrar na pasta de um projeto.
- [ ] Pedir leitura/diagnóstico antes de pedir edição.
Vale a pena instalar Gemini CLI?
Vale se você quer comparar agentes de IA no terminal, já usa Gemini ou Google Cloud, ou quer entender como o Google está entrando no mesmo espaço de Codex e Claude Code.
Mas eu não trataria como substituto automático dos outros dois.
Se você já tem um fluxo bom com Claude Code, comece comparando uma tarefa pequena. Se já usa Codex, teste Gemini CLI no mesmo projeto e veja qual entende melhor seu contexto. Se você está começando do zero, talvez faça sentido instalar os três em momentos diferentes, não tudo no mesmo dia.
O ponto prático: agente de terminal não é brinquedo de prompt. Ele pode ler arquivos, sugerir mudanças e executar tarefas. Comece devagar.
Perguntas frequentes
Gemini CLI funciona no Windows?
Sim. A documentação oficial lista Windows 11 24H2 ou superior como sistema recomendado e PowerShell como shell compatível.
Qual é o comando para instalar Gemini CLI?
O comando principal é npm install -g @google/gemini-cli. Depois, rode gemini no PowerShell.
Preciso de Node.js para instalar Gemini CLI?
Sim. A documentação oficial lista Node.js 20.0.0 ou superior como requisito.
Posso usar Gemini CLI sem instalar?
Sim. A documentação oficial mostra o uso com npx @google/gemini-cli, que permite rodar sem instalação permanente.
Gemini CLI usa login com Google?
Sim. Para a maioria dos usuários locais, a documentação recomenda iniciar o CLI com gemini e escolher "Sign in with Google".
Gemini CLI aceita API key?
Sim. Você pode usar uma chave do Google AI Studio configurando a variável GEMINI_API_KEY no PowerShell.
Gemini CLI é melhor que Codex ou Claude Code?
Depende do seu ecossistema e da tarefa. Gemini CLI faz sentido para quem usa Google/Gemini/Google Cloud. Codex faz sentido para quem já usa OpenAI/ChatGPT. Claude Code faz sentido para quem já usa Claude. O melhor teste é rodar a mesma tarefa real nas três ferramentas.