A Gemini API CLI e a Gemini CLI são ferramentas diferentes. A primeira, executada pelo comando gemini-api, é um cliente de terminal sem estado local oculto, lançado pelo Google em beta em 27 de outubro de 2026 para chamar modelos e agentes gerenciados pela API Gemini a partir de scripts, pipelines de integração contínua (CI) e outros agentes. A segunda, executada por gemini, é um agente de programação que conversa com o usuário e pode trabalhar com arquivos e comandos do projeto. Para desenvolver interativamente, a Gemini CLI costuma ser o ponto de partida; para integrar chamadas específicas à API em um fluxo existente, faz mais sentido examinar gemini-api.
CLI significa interface de linha de comando: um programa controlado pelo terminal. API é a interface pela qual um software solicita recursos de outro. O nome semelhante não indica que a nova ferramenta seja uma atualização direta da antiga, nem que uma instalação substitua a outra. Esta comparação é documental, baseada em materiais oficiais consultados em 29 de outubro de 2026, sem execução própria das ferramentas.
O que foi lançado em 27 de outubro?
O registro de mudanças da API Gemini identifica explicitamente o beta de gemini-api nessa data. O novo cliente usa a Interactions API para gerar texto e mídia, analisar documentos, transcrever arquivos e iniciar agentes gerenciados. Segundo o guia do Google, é distribuído como binário independente, sem exigir a inclusão de um SDK no projeto. SDK é um conjunto de bibliotecas que um desenvolvedor importa no código da aplicação.
O ponto técnico decisivo está na palavra sem estado: uma execução de gemini-api não mantém, por si só, uma sessão local implícita para o próximo comando. Em tarefas encadeadas, o responsável pelo script precisa transmitir referências, como um identificador de interação anterior, o caminho de um arquivo ou o identificador de um trabalho em segundo plano. Isso não significa que a API nunca armazene dados: a Interactions API admite estado no servidor e, segundo sua documentação, armazena solicitações por padrão, com opção store=false nos casos previstos.
Comparação prática das duas ferramentas
| Critério | Gemini API CLI (gemini-api) | Gemini CLI (gemini) |
|---|---|---|
| Papel principal | Cliente para chamar modelos e agentes da API em comandos explícitos. | Agente de terminal para explorar, explicar e modificar projetos com acompanhamento do usuário. |
| Experiência comum | Comandos independentes, arquivos de saída e formatos estruturados para automação. | Sessão conversacional com ferramentas, permissões e contexto do projeto. |
| Automação | Projetada para scripts e CI, com saída JSON, execução de verificação sem chamada de rede e códigos de saída. | Também oferece modo headless, com a opção -p e saída JSON; não é exclusiva de sessões interativas. |
| Autenticação | Documentação de início rápido baseada em chave da API Gemini, via GEMINI_API_KEY ou configuração de credenciais. | Permite login com Conta Google, chave da API Gemini e opções Vertex AI, conforme o cenário. |
| Instalação documentada | Binários para macOS, Linux e Windows; scripts de instalação e instalação com Go. | Pacote @google/gemini-cli, instalado por npm e outras opções documentadas. |
| Maturidade | Beta, com aviso oficial de possíveis mudanças incompatíveis entre versões menores. | Projeto separado, com canais próprios stable, preview e nightly. |
A distinção não é, portanto, que uma ferramenta automatiza e a outra não. A Gemini CLI tem modo não interativo e pode rodar em CI; o diferencial de gemini-api é expor, de forma enxuta, operações específicas da Interactions API para outros agentes e programas controlarem.
Quando usar cada comando?
Para examinar um repositório e pedir alterações acompanhadas: a documentação da Gemini CLI mostra instalação por npm com npm install -g @google/gemini-cli e inicialização pelo comando gemini. A ferramenta pode analisar o código, propor mudanças e solicitar permissão para determinadas operações. Se a tarefa for isolada e sem interface interativa, sua documentação também apresenta gemini -p "Explique este erro".
Para chamar a API a partir de outro agente ou script: após instalar o binário, configurar uma chave de API e definir permissões, o guia da nova ferramenta exemplifica gemini-api generate "Resuma este texto" e gemini-api analyze -i ./relatorio.pdf "Liste as conclusões". São exemplos documentais de sintaxe, não saídas verificadas pela DTech. O comando gemini-api generate "Teste" --dry-run permite pré-visualizar e validar a requisição localmente sem realizar a chamada à API.
O guia do Google descreve saída estruturada com -o json, códigos de retorno para falhas e uso de --stream=false quando um fluxo de geração precisar retornar um único objeto JSON. Essas opções interessam quando um programa precisa interpretar o resultado sem ler uma conversa de terminal.
Autenticação, custos e migração exigem cuidado
- Credenciais: gemini-api pode receber GEMINI_API_KEY pelo ambiente ou guardar a credencial no cofre do sistema operacional. Não publique chaves em código, logs ou repositórios. Na Gemini CLI, o login por Conta Google não deve ser tratado como equivalente comercial a uma chave de API.
- Não há migração direta de comandos: substituir gemini por gemini-api em um script pode mudar argumentos, formato das respostas, tratamento de erros, sessão, permissões e cobrança. Teste a compatibilidade em ambiente controlado antes de alterar um pipeline de produção. Em CI, fixe uma versão do beta em vez de depender automaticamente da mais recente.
- Estado e privacidade: ausência de estado local oculto não elimina armazenamento no serviço. Examine a configuração de retenção da Interactions API, as políticas de dados aplicáveis e os arquivos enviados, especialmente quando houver documentos confidenciais.
- Disponibilidade e limitações: o Google documenta instaladores ou binários para macOS, Linux e Windows, mas isso não equivale a um teste próprio em todas as versões dos sistemas. O cliente novo não oferece conexão WebSocket bidirecional para voz e vídeo ao vivo; o Google indica SDKs e Live API para esse caso.
Funciona no Brasil? E é gratuito?
O Brasil consta da lista oficial de regiões atendidas pela API Gemini e pelo Google AI Studio. Isso confirma a elegibilidade regional dos serviços listados, não o funcionamento do beta em qualquer conta, máquina ou configuração. A verificação de acesso deve considerar a credencial, o projeto, o recurso chamado e os limites da conta.
A instalação da CLI e o preço das chamadas são questões distintas. O Google mantém níveis gratuitos e pagos para determinados modelos e recursos da API, com limites e preços variáveis; não há base para chamar todo uso de gemini-api de gratuito. A Gemini CLI também possui regras de quota, preço e privacidade que dependem da forma de autenticação. Um usuário com assinatura de aplicativo não deve presumir que todas as chamadas por chave de API estejam incluídas.
Decisão prática: escolha Gemini CLI quando quiser um agente para trabalhar diretamente no terminal e no projeto, inclusive no modo headless. Escolha Gemini API CLI quando precisar inserir chamadas explícitas a modelos, análise de arquivos, geração de mídia ou agentes gerenciados em scripts e outros agentes. Como gemini-api ainda é beta, valide os comandos, os formatos e o acesso efetivo antes de adotá-la como substituta de qualquer fluxo existente.
