# Como usar o Gemini CLI: guia passo a passo URL: https://agentvera.dev/pt/blog/how-to-use-gemini-cli/ · Publicado: 2026-10-25 Como usar o Gemini CLI: instale, escolha o login após a mudança de junho de 2026, escreva o GEMINI.md, ajuste o settings.json, adicione MCP e desfaça edições. **Resumo:** - Instale o Gemini CLI com npm, Homebrew ou MacPorts, ou experimente com npx, depois rode gemini em uma pasta de projeto e escolha um método de login. - Desde 18 de junho de 2026, os usuários do nível gratuito e do Google One foram migrados para o Antigravity CLI; o Gemini CLI agora funciona com chaves pagas da API Gemini, Vertex AI e Code Assist Standard ou Enterprise. - As regras do projeto ficam no GEMINI.md, as configurações em .gemini/settings.json, servidores MCP entram com gemini mcp add, e checkpointing com /restore permite desfazer edições de arquivos. 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](/pt/glossary/coding-agent/ "O que é 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](/pt/blog/gemini-cli-vs-claude-code/ "Gemini CLI vs Claude Code") e [Codex vs Gemini CLI](/pt/blog/codex-vs-gemini-cli/ "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: ```bash gemini --version ``` ## Passo 2: escolha como fazer login Entre em um projeto e inicie: ```bash cd my-project gemini ``` Na 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_PROJECT` com 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_KEY` e `GOOGLE_GENAI_USE_VERTEXAI=true`, ou use suas credenciais do Cloud. ```bash export GEMINI_API_KEY="your-key" gemini ``` Você 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](/pt/blog/gemini-cli-vs-claude-code/ "Gemini CLI vs Claude Code") cobre a mudança em detalhes. Consulte [os preços da API Gemini do Google](https://ai.google.dev/gemini-api/docs/pricing "Preços da API Gemini") 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: ```text 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/file` adiciona um arquivo (ou uma pasta inteira) ao seu prompt. - `!git status` executa 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 json` quando um script precisar ler o resultado. - `/copy` copia 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: ```markdown # 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: 1. **Global:** `~/.gemini/GEMINI.md`, seus padrões pessoais para todos os projetos. 2. **Workspace:** arquivos `GEMINI.md` na pasta do projeto e nas pastas acima dela. 3. **Sob demanda:** quando uma ferramenta mexe em um arquivo de uma subpasta, o Gemini também pega qualquer `GEMINI.md` dessa 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](/pt/blog/claude-md-agents-md/ "CLAUDE.md e 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.json` para suas configurações de usuário; - `.gemini/settings.json` dentro 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: ```json { "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](/pt/blog/ai-coding-agent-security/ "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](/pt/glossary/mcp/ "O que é MCP") dão ao Gemini ferramentas extras: consulta de documentação, navegador, GitHub, seu banco de dados. Adicione um pelo shell: ```bash gemini mcp add github npx -y @modelcontextprotocol/server-github ``` Para 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 ` 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](/pt/blog/what-is-mcp-server/ "O que é um servidor MCP"). Cada servidor adiciona descrições de ferramentas à [janela de contexto](/pt/glossary/context-window/ "O que é uma 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`: ```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 ` 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-sessions` mostra as sessões salvas com números; `gemini --resume 3` abre uma delas. - Dentro de uma sessão, o `/resume` permite 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 test` e 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.** `/compress` guarda um resumo; `/clear` começ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](/pt/blog/git-worktree-parallel-agents/ "Git worktrees para agentes em paralelo") 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](/pt/agents/gemini-cli/ "Gemini CLI no AgentVera") para mais detalhes. - **[Workspace](/pt/features/workspace/ "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.md` ou no `AGENTS.md`. - **[Gerenciador de MCP](/pt/features/mcp-manager/ "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](/pt/features/flows/ "Flows"):** passe o resultado de um agente para o próximo, por exemplo o Gemini escreve e outro agente revisa. - **[Code review](/pt/features/code-review/ "Code review"):** revise as mudanças de um agente automaticamente no fim de um turno. - **Worktrees:** crie um pelo [painel Git](/pt/features/git-and-github/ "Git e GitHub") 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](/pt/download/ "Baixar 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](/pt/agents/antigravity/ "Antigravity no AgentVera"). ## 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](/pt/blog/how-to-use-codex-cli/ "Como usar o Codex CLI"). ## Perguntas frequentes **O Gemini CLI ainda é gratuito?** Não para contas pessoais. O aviso do Google diz que, em 18 de junho de 2026, os usuários do nível gratuito e do Google One foram migrados para o Antigravity CLI. O Gemini CLI continua funcionando com chaves pagas da API Gemini, Vertex AI e licenças Gemini Code Assist Standard ou Enterprise. **Qual a diferença entre GEMINI.md e AGENTS.md?** Os dois são arquivos Markdown com instruções do projeto. O Gemini CLI lê o GEMINI.md por padrão. Se sua equipe já mantém as regras no AGENTS.md, defina context.fileName no settings.json como uma lista, por exemplo ["AGENTS.md", "GEMINI.md"], e o Gemini CLI vai ler os dois. **Como impedir que o Gemini CLI execute comandos sem perguntar?** Fique no modo de aprovação padrão, que pergunta antes de cada chamada de ferramenta. O auto_edit aprova edições de arquivos, mas ainda pergunta antes de outras ferramentas, e o yolo aprova tudo, então use o yolo só dentro de um sandbox em que você confia. **Como desfaço uma mudança que o Gemini CLI fez?** Ative o checkpointing no settings.json. O Gemini CLI passa a salvar um snapshot antes de cada edição de arquivo, e o /restore devolve seus arquivos. Sem checkpointing, o /rewind (ou Esc duas vezes) ainda permite voltar pela conversa e pelas mudanças de arquivos. **Como continuo uma sessão anterior do Gemini CLI?** Inicie o Gemini CLI com --resume latest para continuar a sessão mais recente, ou rode gemini --list-sessions e retome uma pelo número. Dentro de uma sessão, o /resume permite navegar e escolher uma conversa salva. --- **Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/