Guia Completo de Gemini CLI

O Que é o Gemini CLI?

O Gemini CLI é o agente de terminal aberto do Google, publicado como @google/gemini-cli. Ele lê o diretório do projeto, chama ferramentas e conversa com os modelos Gemini a partir do shell.

Em 18 de junho de 2026 o CLI deixou de atender contas gratuitas e as assinaturas Google AI Pro e Ultra. Uso pessoal no terminal passa pelo Antigravity CLI. Licença Gemini Code Assist Standard ou Enterprise, e chave de API paga, continuam no Gemini CLI. O recorte está no anúncio de 19 de maio de 2026.

Node 20+

Runtime mínimo oficial

npm

@google/gemini-cli

Login

Conta Google ou chave

18 jun

Corte do plano pessoal

Instalação do Gemini CLI

Passo a passo para instalar e configurar o Gemini CLI em seu sistema

1

Pré-requisitos

Node.js 20 ou mais recente, npm, e um shell (PowerShell, Bash ou Zsh). macOS 15+, Windows 11 24H2+ ou Ubuntu 20.04+.

node --version
npm --version

2

Instalação

O pacote oficial é do npm. Homebrew no macOS/Linux também instala o mesmo CLI.

npm install -g @google/gemini-cli

# Sem instalar de forma permanente
npx @google/gemini-cli

# macOS ou Linux, se você usa Homebrew
brew install gemini-cli

3

Autenticação

Na máquina local, abra o CLI e escolha Sign in with Google. Para script ou CI, use uma chave do AI Studio na variável GEMINI_API_KEY.

# Linux ou macOS
export GEMINI_API_KEY="sua_chave"

# Windows PowerShell
$env:GEMINI_API_KEY="sua_chave"

4

Verificação

Teste a instalação com um comando simples.

gemini

Comandos Básicos

Os comandos essenciais para começar a usar o Gemini CLI

Sessão interativa

Abre o agente no diretório atual

gemini

Sem instalação global

Roda o pacote oficial uma vez via npx

npx @google/gemini-cli

Canal preview

Build semanal, separado do estável

npm install -g @google/gemini-cli@preview

Contexto do projeto

Arquivo GEMINI.md na raiz, lido em toda sessão

GEMINI.md

Recursos Avançados

O que o CLI documenta hoje: contexto do repositório, ferramentas e agentes

GEMINI.md

Instruções estáveis do repositório. O CLI lê esse arquivo no início da sessão.

# Contexto do projeto
Site estático em português.
Mudanças pequenas. Não invente versão de dependência.

Servidor MCP

O CLI conecta servidores MCP para ferramentas externas. A configuração está na documentação de MCP do próprio CLI.

Agent Skills

Skills empacotam um procedimento reutilizável. Hooks disparam ações em pontos da sessão. Os dois estão na documentação atual.

Subagentes

Uma tarefa longa pode ser dividida em subagentes. O Antigravity CLI, sucessor no plano pessoal, aprofunda esse modo assíncrono.

Configuração Avançada

Personalize o comportamento do Gemini CLI com opções de configuração

Arquivo de Configuração

Crie um arquivo de configuração para definir opções padrão.

# Contexto: GEMINI.md na raiz do repositório
# Ajustes do CLI: arquivo de settings da documentação oficial
# https://geminicli.com/docs/cli/settings

Variáveis de Ambiente

GEMINI_API_KEY — chave do AI Studio
GOOGLE_API_KEY — chave Vertex AI
Login Google — caminho recomendado na máquina local

Exemplos de Integração

Como integrar o Gemini CLI em seus fluxos de trabalho

Modo headless

Script e CI usam o modo headless, com GEMINI_API_KEY definida. Os flags e o formato de saída estão na documentação de headless, não em --output.

export GEMINI_API_KEY="sua_chave"
# Flags: https://geminicli.com/docs/cli/headless
gemini

Trabalho no repositório

Aberto na raiz do git, o CLI já enxerga os arquivos. Peça o commit na sessão interativa e revise a mensagem antes de gravar.

git status
gemini

Melhores Práticas

Dicas essenciais para usar o Gemini CLI de forma eficaz e segura

Princípios de Uso

1. Seja Específico

Prompts detalhados geram respostas mais precisas e úteis.

2. Gerencie Tokens

Monitore o uso de tokens para evitar custos excessivos em versões pagas.

3. Valide Saídas

Sempre verifique as respostas geradas, especialmente para código ou dados críticos.

4. Fique na sessão

A conversa interativa guarda o contexto. Para script, use o modo headless da documentação, com a chave de API.

5. Proteja Dados

Nunca envie dados sensíveis ou confidenciais para modelos de IA.

Segurança

Use chaves de API limitadas
Não exponha chaves em repositórios
Revogue chaves comprometidas

Performance

Use modelos mais leves quando possível
Limite o número de tokens
Cacheie respostas comuns

Dica Importante

A linha atual é Gemini 3. O id exato (Flash, Pro e variantes) muda. Confira a página de modelos do CLI antes de gravar um nome em settings ou em script.

Solução de Problemas

Soluções para os problemas mais comuns com o Gemini CLI

Erro de Autenticação

Conta pessoal depois de 18 de junho de 2026 não autentica mais neste CLI. Nos demais casos, entre de novo ou confira GEMINI_API_KEY.

# Linux ou macOS
echo $GEMINI_API_KEY

# Windows PowerShell
echo $env:GEMINI_API_KEY

Cota

A cota depende do plano (conta Google, AI Studio ou Vertex). O número não é fixo neste guia. A tabela oficial está em geminicli.com/docs/resources/quota-and-pricing.

Node antigo

Abaixo do Node 20 o pacote npm falha na instalação ou na execução. Atualize o runtime e rode de novo.

node --version

Problemas de Instalação

O pacote pip google-gemini-cli não é o CLI oficial. Reinstale pelo npm, com Node 20 ou mais recente.

node --version
npm install -g @google/gemini-cli
gemini

Tópicos Avançados

Explore funcionalidades avançadas do Gemini CLI

Headless

Automação sem TTY. Exige chave de API ou Vertex, conforme a página de autenticação.

Hooks

Pontos de extensão antes e depois de ações do agente. A referência está em geminicli.com/docs/hooks.

Plan mode

O agente apresenta um plano antes de editar arquivos. Útil quando a mudança atravessa vários módulos.

Pastas confiáveis

O CLI pede confirmação antes de agir num diretório novo. A lista fica em trusted folders, na documentação de configuração.