Para usar o Gemini CLI, instale-o com npm ou Homebrew, rode gemini dentro de uma pasta de projeto, escolha como fazer login e então descreva o que você quer em linguagem natural. O Gemini lê seus arquivos, propõe edições e comandos de shell e, por padrão, pergunta antes de executar cada um.
Antes de começar, uma ressalva importante. Desde 18 de junho de 2026, o Gemini CLI não atende mais usuários do nível gratuito e do Google One. O Google migrou esses usuários para o Antigravity CLI. O Gemini CLI continua funcionando com uma chave paga da API Gemini, Vertex AI ou uma licença Gemini Code Assist Standard ou Enterprise. Este guia cobre instalação, login, GEMINI.md, configurações, MCP, modos de aprovação, slash commands, checkpointing e retomada de sessões. Tudo aqui segue a documentação oficial do Gemini CLI do Google em outubro de 2026.
O que é o Gemini CLI
O Gemini CLI é o agente de código de código aberto do Google para o terminal. Ele roda modelos Gemini, lê e edita arquivos na pasta em que você o inicia, executa comandos de shell, pesquisa na web, se conecta a servidores MCP e recebe as instruções do projeto pelo GEMINI.md. É um agente de código, não um autocomplete: você entrega uma tarefa e ele a resolve passo a passo. Para uma comparação com outros agentes, veja Gemini CLI vs Claude Code e Codex vs Gemini CLI.
Passo 1: instale o Gemini CLI
O Gemini CLI precisa de Node.js. Escolha a instalação que combina com o seu ambiente:
| Método | Comando |
|---|---|
| Experimentar sem instalar | npx @google/gemini-cli |
| npm (qualquer plataforma) | npm install -g @google/gemini-cli |
| macOS, Linux (Homebrew) | brew install gemini-cli |
| macOS (MacPorts) | sudo port install gemini-cli |
Há três canais de release no npm: @latest (estável, semanal), @preview (semanal, à frente do estável) e @nightly. A maioria das pessoas deve ficar no estável. Para atualizar depois, rode gemini update ou reinstale pelo seu gerenciador de pacotes. Confira a instalação:
gemini --versionPasso 2: escolha como fazer login
Entre em um projeto e inicie:
cd my-project
geminiNa primeira execução, o Gemini CLI pergunta como você quer se autenticar. Há três opções:
- Sign in with Google: abre o navegador. Depois da mudança de junho de 2026, isso é para organizações com licença Gemini Code Assist Standard ou Enterprise; defina
GOOGLE_CLOUD_PROJECTcom o ID do seu projeto no Google Cloud antes de começar. - Chave da API Gemini: crie uma chave no Google AI Studio e defina
GEMINI_API_KEY. O uso é cobrado por token em uma chave paga. - Vertex AI: para equipes no Google Cloud. Defina
GOOGLE_API_KEYeGOOGLE_GENAI_USE_VERTEXAI=true, ou use suas credenciais do Cloud.
export GEMINI_API_KEY="your-key"
geminiVocê pode trocar de método depois com /auth. Se você usava o Gemini CLI com uma conta pessoal gratuita, o aviso do Google indica o Antigravity CLI no lugar; Gemini CLI vs Claude Code cobre a mudança em detalhes. Consulte os preços da API Gemini do Google para ver os valores atuais antes de rodar sessões longas com uma chave.
Passo 3: sua primeira tarefa
Comece com algo pequeno e real:
Explain how the payment module is structured, then add input validation
to the refund endpoint and run the tests.O Gemini vai ler os arquivos de que precisa, mostrar cada edição e comando e esperar o seu OK. Alguns atalhos ajudam desde o primeiro dia:
@path/to/fileadiciona um arquivo (ou uma pasta inteira) ao seu prompt.!git statusexecuta um comando de shell diretamente. Um!sozinho liga e desliga o modo shell.gemini -p "summarize README.md"roda um único prompt sem a interface interativa e imprime a resposta. Adicione--output-format jsonquando um script precisar ler o resultado./copycopia a última resposta para a área de transferência.
Passo 4: escreva um GEMINI.md
O GEMINI.md é um arquivo Markdown de instruções que o Gemini CLI carrega e envia com cada prompt: como fazer build e testar, estilo de código, o que não mexer. Rode /init e o Gemini gera uma primeira versão a partir do seu projeto. Mantenha-o curto e concreto:
# Project: billing-service
## Commands
- Install: npm ci
- Test: npm test (run before you say a task is done)
## Style
- TypeScript, 2-space indent, strict equality only.
- New endpoints go in src/routes and need a test.
## Don't
- Don't edit files in src/generated.O Gemini CLI carrega os arquivos de contexto em camadas e os junta:
- Global:
~/.gemini/GEMINI.md, seus padrões pessoais para todos os projetos. - Workspace: arquivos
GEMINI.mdna pasta do projeto e nas pastas acima dela. - Sob demanda: quando uma ferramenta mexe em um arquivo de uma subpasta, o Gemini também pega qualquer
GEMINI.mddessa pasta e das pastas acima.
Você pode dividir um arquivo longo com imports, por exemplo uma linha @./docs/style-guide.md. Para ver o que o modelo realmente recebe, rode /memory show; /memory list mostra quais arquivos foram carregados. Se você editar um arquivo no meio da sessão, recarregue com /memory reload.
Se o seu repositório já tem um AGENTS.md, você não precisa duplicá-lo. Defina context.fileName nas configurações como ["AGENTS.md", "GEMINI.md"]. CLAUDE.md vs AGENTS.md explica como manter um único conjunto de regras para vários agentes.
Passo 5: settings.json
O Gemini CLI lê as configurações de arquivos JSON:
~/.gemini/settings.jsonpara suas configurações de usuário;.gemini/settings.jsondentro de um projeto para as configurações do workspace.
Rode /settings para mudar a maioria das opções em um editor dentro da própria CLI, em vez de editar o JSON à mão. Um pequeno exemplo:
{
"general": {
"defaultApprovalMode": "auto_edit",
"checkpointing": { "enabled": true }
},
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}O modelo pode ser definido por execução com -m / --model. Os aliases auto (o padrão), pro, flash e flash-lite permitem escolher por velocidade e profundidade sem decorar nomes exatos de modelos; /model troca o modelo durante a sessão.
Passo 6: modos de aprovação e o sandbox
O Gemini CLI pergunta antes de executar ferramentas, a não ser que você diga o contrário. A flag --approval-mode define o comportamento:
| Modo | O que acontece |
|---|---|
default | Pergunta antes de cada chamada de ferramenta |
auto_edit | Aprova edições de arquivos automaticamente, mas ainda pergunta antes de outras ferramentas, como comandos de shell |
plan | Somente leitura: o Gemini pode olhar e planejar, mas não mudar nada |
yolo | Aprova todas as chamadas de ferramenta; só para um ambiente isolado |
A flag antiga --yolo ainda existe, mas está obsoleta em favor de --approval-mode=yolo. Você pode tornar auto_edit ou plan o padrão nas configurações; o yolo só pode ser ligado pela linha de comando.
O sandbox vem desligado por padrão. Inicie com --sandbox (ou -s) para rodar as ferramentas em um ambiente isolado: Seatbelt no macOS, ou um contêiner Docker ou Podman. Se você quer usar auto_edit ou yolo com frequência, ligue o sandbox primeiro. Segurança de agentes de código com IA explica por que só as aprovações não bastam.
Passo 7: conecte servidores MCP
Servidores MCP dão ao Gemini ferramentas extras: consulta de documentação, navegador, GitHub, seu banco de dados. Adicione um pelo shell:
gemini mcp add github npx -y @modelcontextprotocol/server-githubPara um servidor HTTP, adicione --transport http e uma URL em vez de um comando. --env KEY=value passa variáveis de ambiente, e --scope user deixa o servidor disponível em todos os projetos, não só neste. gemini mcp list mostra o que está configurado e gemini mcp remove <name> apaga um servidor.
Por baixo dos panos, isso vai para a seção mcpServers do settings.json, então você também pode editar por lá. Dentro de uma sessão, /mcp lista os servidores e suas ferramentas, /mcp auth faz login em servidores que usam OAuth e /mcp reload os reinicia. A ideia é nova para você? Leia o que é um servidor MCP. Cada servidor adiciona descrições de ferramentas à janela de contexto, então mantenha só os que você usa.
Passo 8: os slash commands que vale conhecer
| Comando | O que faz |
|---|---|
/init | Gera um GEMINI.md para o projeto |
/memory show | Mostra as instruções que o modelo está recebendo |
/settings | Abre o editor de configurações |
/model | Troca o modelo |
/auth | Troca o método de login |
/mcp | Lista servidores MCP e ferramentas |
/tools | Lista as ferramentas que o Gemini pode usar |
/stats | Uso da sessão, do modelo e das ferramentas |
/compress | Substitui a conversa por um resumo para economizar tokens |
/clear | Limpa a tela e começa do zero |
/resume | Navega e retoma sessões salvas |
/rewind | Volta pela conversa (também Esc duas vezes) |
/restore | Restaura arquivos a partir de um checkpoint |
/directory | Adiciona mais pastas ao workspace |
/help | Lista todos os comandos |
Você também pode escrever seus próprios comandos. Um arquivo .toml em ~/.gemini/commands/ vira um slash command pessoal, e um em .gemini/commands/ dentro de um projeto é compartilhado com todo mundo que usa o repositório. /commands list mostra todos.
Passo 9: checkpointing e desfazer
O checkpointing é a rede de segurança do Gemini CLI, e ele vem desligado por padrão. Ligue-o no settings.json:
{
"general": {
"checkpointing": { "enabled": true }
}
}A partir daí, toda vez que você aprova uma ferramenta que muda arquivos, o Gemini primeiro salva um snapshot do projeto em um repositório git sombra separado, em ~/.gemini/history/. Ele não mexe no seu histórico git. Rode /restore para ver a lista de checkpoints e /restore <id> para devolver seus arquivos e a conversa àquele ponto. O Gemini então oferece de novo a chamada de ferramenta original, para que você possa executá-la de novo, alterá-la ou pulá-la.
Mesmo sem checkpointing, o /rewind (ou Esc duas vezes) permite voltar a um prompt anterior e escolher desfazer a conversa, as mudanças no código ou as duas coisas.
Passo 10: retome sessões
O Gemini CLI salva suas sessões por projeto:
gemini --resume latest(ou-r latest) continua a sessão mais recente.gemini --list-sessionsmostra as sessões salvas com números;gemini --resume 3abre uma delas.- Dentro de uma sessão, o
/resumepermite navegar, salvar e reabrir conversas.
Você também pode passar um novo prompt de imediato: gemini -r latest "check for type errors".
Dicas para resultados melhores
- Faça commit antes de tarefas grandes. Checkpoints são bons; um commit no git é melhor e funciona com qualquer ferramenta.
- Diga como verificar. “Rode
npm teste corrija as falhas” é melhor que “faça funcionar”. - Use o modo plan para mudanças maiores. Deixe o Gemini explorar e propor um plano antes de editar qualquer coisa.
- Referencie arquivos com
@. É mais rápido do que esperar o Gemini encontrá-los e mantém o contexto focado. - Comprima ou limpe entre tarefas.
/compressguarda um resumo;/clearcomeça de novo. Os dois economizam tokens. - Um agente por worktree. Se você roda mais de um agente, dê a cada um seu próprio git worktree para que não sobrescrevam o trabalho um do outro.
Quando um terminal não basta
O Gemini CLI costuma ser um entre vários agentes que uma equipe usa. Quando você quer o Gemini em uma tarefa e o Codex ou o Claude Code em outra, ou um agente conferindo o trabalho de outro, um único terminal fica apertado.
O AgentVera é um app desktop para macOS, Windows e Linux que roda o Gemini CLI (e outros agentes de CLI) em terminais reais, lado a lado. Cada agente Gemini usa seu próprio login do Google ou GEMINI_API_KEY; o terminal pergunta qual na primeira execução. Veja a página Gemini CLI no AgentVera para mais detalhes.
- Workspace: uma grade de agentes por projeto, de 1×1 a 5×4. Cada agente Gemini começa com sua própria sessão e a reabre depois de reiniciar o app.
- Permissões por agente: escolha Ask, Auto ou Full access ao criar o agente.
- Instruções: o Gemini CLI não tem flag para instruções extras, então o campo Role do AgentVera não chega até ele. Coloque as regras no
GEMINI.mdou noAGENTS.md. - Gerenciador de MCP: os servidores que você configura no AgentVera são anexados ao Gemini na inicialização, mesclados por nome com as suas próprias configurações do Gemini.
- Flows: passe o resultado de um agente para o próximo, por exemplo o Gemini escreve e outro agente revisa.
- Code review: revise as mudanças de um agente automaticamente no fim de um turno.
- Worktrees: crie um pelo painel Git e inicie um agente nele.
A grade, os worktrees, o code review e o gerenciador de MCP estão no plano gratuito; os flows estão no Pro e no Team. Baixe o AgentVera e teste no seu próprio repositório. Se você usa uma conta gratuita do Google, o AgentVera também suporta o Antigravity.
Conclusão
Instale o Gemini CLI, rode gemini e escolha um login que ainda funcione depois de junho de 2026: uma chave de API paga, Vertex AI ou uma licença do Code Assist. Rode /init e mantenha seu GEMINI.md curto, defina padrões com /settings e adicione servidores MCP só quando precisar. Fique no modo de aprovação padrão até confiar no setup, ligue o checkpointing para que o /restore possa desfazer edições e use --resume latest para continuar de onde parou. Para comparar com o agente da OpenAI, leia como usar o Codex CLI.