Este guia técnico descreve a instalação e a utilização operacional da ferramenta de linha de comando (CLI) para interação com os modelos de linguagem da família Gemini, desenvolvida pelo Google.

Pré-requisitos do Ambiente

A CLI do Gemini é uma aplicação construída sobre o Node.js, exigindo um ambiente de execução adequado.

• Node.js v20 ou posterior: Verifique sua versão atual com node -v. Sistemas como o Ubuntu 24.04 podem oferecer versões mais antigas via apt, sendo recomendável o uso de gerenciadores como nvm para obter a versão necessária.
• Conta Google: Necessária para autenticação. O nível gratuito oferece limites significativos de requisições e acesso ao modelo Gemini 2.5 Pro com um contexto extenso.

Procedimento de Instalação

A ferramenta é distribuída como um pacote npm global.

npm install -g @google/gemini-cli

Para confirmar a instalação bem-sucedida, verifique a versão do pacote instalado:

gemini --version

Processo de Autenticação Inicial

Ao executar o comando gemini pela primeira vez, o assistente de configuração será iniciado.

1. Seleção de Tema: Esquema de cores para a interface do terminal.
2. Método de Autenticação: Opte por "Login with Google". Isso abrirá automaticamente uma sessão no navegador para autenticação OAuth com sua conta Google.

Vinculação a um Projeto Google Cloud (Opcional, mas Recomendado)

Para integrar com serviços avançados e gerenciamento de recursos do Google Cloud, vincule a CLI a um projeto existente.

1. No Console do Google Cloud, identifique o ID do Projeto desejado.
2. Navegue até "APIs & Services" > "Library", busque por "Gemini API" e garanta que ela esteja habilitada para seu projeto.
3. Defina a variável de ambiente correspondente no seu shell: ``` export GOOGLE_CLOUD_PROJECT_ID=seu-id-de-projetoaqui-123

Coamndos e Uso Essencial

A CLI opera em modo interativo. As principais interações são:

• Diálogo Direto: Digite sua consulta ou instrução diretamente no prompt.
• Comandos de Barra (/): Comandos especiais para controle da sessão.
  • /help: Exibe a lista completa de comandos e atalhos.
  • /chat: Reinicia o histórico da conversa.
  • /stats: Mostra estatísticas de uso da sessão atual.
  • /exit: Encerra a sessão da CLI.
• Referenciamento de Arquivos: Use o símbolo @ para incluir o conteúdo de arquivos ou diretórios locais como contexto para o modelo. Por exemplo: @src/main.js ou @./docs. A CLI solicitará permissão antes do primeiro acesso.

Capacidades Avançadas

A CLI pode realizar modificações diretas no código-fonte quando solicitada. Para alterações em arquivos como @api/routes.js, a ferramenta apresentará primeiro um diff das mudanças propostas, aguardando confirmação do usuário antes de aplicá-las. Isso mantém o controle total sobre o estado do projeto. Funções semelhantes permitem gerar testes unitários para módulos referenciados, como @lib/utils.py.

Personalização com Arquivo de Contexto

Criar um arquivo GEMINI.md na raiz do seu projeto permite definir um contexto persistente. O conteúdo deste arquivo, como descrições, convenções de código e dependências importantes, será automaticamente carregado pela CLI em cada sessão, fornecendo respostas mais relevantes e alinhadas com o seu projeto.