Esta página foi traduzida pela API Cloud Translation.

Prática com a CLI do Gemini

1. Introdução

Neste codelab, você vai aprender sobre a CLI do Gemini, um agente de IA de código aberto que leva o poder do Gemini diretamente ao seu terminal.

O projeto da CLI do Gemini é de código aberto, e você pode conferir o roteiro público aqui.

Durante o codelab, você vai usar uma abordagem gradual em atividades como:

Como instalar a CLI do Gemini
Configuração básica
Como usar ferramentas e comandos integrados na CLI do Gemini
Personalizar a CLI do Gemini usando o arquivo GEMINI.md
Analisar alguns casos de uso com a CLI do Gemini

O que é necessário

Navegador da Web Google Chrome
Uma conta do Gmail
Uma máquina local com o Node 20 ou mais recente instalado.

Este codelab foi criado para usuários e desenvolvedores de todos os níveis, incluindo iniciantes.

2. Instalação

Antes de executar a configuração e a CLI do Gemini, vamos criar uma pasta que será usada como pasta inicial para todos os projetos que criarmos nela. Esse é um ponto de partida para a CLI do Gemini trabalhar, mas ela também vai referenciar outras pastas no seu sistema, que vamos abordar mais tarde, conforme necessário.

Crie uma pasta de amostra (gemini-cli-projects) e navegue até ela usando os comandos mostrados abaixo. Se preferir usar outro nome de pasta, faça isso.

mkdir gemini-cli-projects

Navegue até essa pasta:

cd gemini-cli-projects

Para executar a CLI Gemini, use um dos seguintes métodos:

Execute com o seguinte comando:

npx https://github.com/google-gemini/gemini-cli

Primeiro, instale a CLI Gemini globalmente no seu sistema. Verifique se você tem direitos de administrador para fazer isso.

npm install -g @google/gemini-cli

e execute com o seguinte comando:

gemini

Supondo que você tenha iniciado a CLI do Gemini usando um dos métodos acima, a seguinte tela vai aparecer e perguntar sobre a escolha de um tema. Selecione uma opção:

Depois de selecionar essa opção, você precisará informar o método de autenticação. Recomendamos que você use sua Conta do Google pessoal e não contas não relacionadas ao Google ou ao Google Workspace neste laboratório. Essa licença sem custo financeiro dá acesso ao Gemini 2.5 Pro e à janela de contexto de 1 milhão de tokens. O nível sem custo financeiro permite 60 solicitações de modelo por minuto e 1.000 solicitações por dia sem custos financeiros.

Se você atingir os limites da cota sem custo financeiro atual oferecida às Contas do Google, use a chave de API do Gemini ou a Vertex AI do Google Cloud, em que você precisará ter um ID do projeto e o nome do local dele. Consulte a seção Autenticação da documentação se você planeja usar outros métodos de autenticação.

Clique em "Enter". Uma página de autenticação do Google será aberta no navegador. Faça a autenticação com sua Conta do Google, aceite os termos e, depois de autenticado, você vai notar que a CLI do Gemini está pronta e aguardando seu comando. Confira abaixo uma captura de tela de exemplo:

Digite /help (barra) para ver vários comandos e atalhos de teclado, conforme mostrado abaixo:

Nossa primeira interação com a CLI do Gemini

Digite sua primeira mensagem na caixa. Vamos dar a ele uma consulta como:

Você vai notar que nossa consulta resultou em uma ferramenta GoogleSearch (uma ferramenta integrada na CLI do Gemini) que foi invocada. Essa é uma maneira interessante de usar uma das ferramentas integradas da CLI do Gemini, o GoogleSearch, que fundamenta as respostas com base em informações da Web. Vamos falar mais sobre as ferramentas na próxima seção.

Vamos sair da CLI do Gemini por enquanto. Faça isso com o comando /quit ou execute Ctrl-C duas vezes na sessão interativa do terminal da CLI do Gemini.

Arquivo de personalização da CLI do Gemini : settings.json

Se você se lembra de quando iniciamos a CLI do Gemini pela primeira vez, foi solicitado que selecionássemos um tema e um método de autenticação. Nas execuções subsequentes da CLI Gemini, não será necessário selecionar um tema e um método de autenticação novamente. Isso significa que ele está sendo armazenado em algum lugar, e o arquivo usado é chamado de settings.json, que é a maneira de personalizar a CLI do Gemini.

As configurações são aplicadas com a seguinte ordem de precedência:

Espaço de trabalho: .gemini/settings.json (substitui as configurações do usuário e do sistema).
Usuário: ~/.gemini/settings.json (substitui as configurações do sistema).
Sistema: /etc/gemini-cli/settings.json (válido para todos os usuários).

Se você se lembra, ao selecionar o tema, pedimos que as configurações fossem salvas nas configurações do usuário. Acesse ~/.gemini folder e você vai notar o arquivo settings.json.

Meu arquivo settings.json é mostrado abaixo. Se você tivesse selecionado outro tema, o nome dele apareceria ali.

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal"
}

3. Parâmetros de comando da CLI do Gemini

Há alguns parâmetros de linha de comando que podem ser fornecidos ao iniciar a CLI Gemini. Para conferir uma lista completa de opções, use --help, conforme mostrado abaixo.

gemini --help

Isso vai mostrar todas as opções disponíveis. Consulte a documentação aqui.

Vamos analisar algumas delas. A primeira é configurar a CLI do Gemini para usar o modelo Pro ou o Flash. No momento da redação deste laboratório, esses são os únicos dois modelos compatíveis. Por padrão, o modelo Gemini 2.5 Pro é usado, mas se você quiser usar o modelo Flash, faça isso ao iniciar a CLI do Gemini com o parâmetro -m, como mostrado abaixo:

gemini -m "gemini-2.5-flash"

Se você começar da maneira acima, poderá verificar o modelo na parte de baixo à direita do terminal da CLI do Gemini, conforme mostrado abaixo:

Modo não interativo

Uma opção interessante é executar a CLI do Gemini em um modo não interativo. Isso significa que você fornece o comando diretamente, e ele responde sem abrir o terminal interativo da CLI do Gemini. Isso é muito útil se você planeja usar a CLI do Gemini de forma automatizada como parte do script ou de qualquer outro processo de automação. Use o parâmetro -p para fornecer o comando à CLI do Gemini, conforme mostrado abaixo:

gemini -p "What is the gcloud command to deploy to Cloud Run"

Não é possível continuar a conversa com perguntas complementares.

4. CLI do Gemini: ferramentas integradas

A CLI do Gemini vem com um conjunto de ferramentas integradas, e a documentação de ferramentas afirma: "O modelo do Gemini usa essas ferramentas para interagir com seu ambiente local, acessar informações e realizar ações. Essas ferramentas melhoram os recursos da CLI, permitindo que ela vá além da geração de texto e ajude com uma ampla variedade de tarefas".

Para conferir uma lista das ferramentas integradas atuais, basta invocar o comando /tools, conforme mostrado abaixo:

Uma das coisas que você precisa se perguntar imediatamente é se a CLI do Gemini pode simplesmente chamar essas ferramentas quando quiser. A resposta padrão é não quando se trata de operações sensíveis que podem envolver gravação no sistema local, leitura de um sistema externo, acesso à rede externa e assim por diante.

Embora haja um --yolomode disponível ao iniciar a CLI, que não vamos usar, a CLI do Gemini vai pedir permissão para executar a ferramenta escolhida. Você pode negar a permissão, permitir que ela seja executada uma vez ou conceder permissão geral para que ela seja executada sempre. Você tem e deve ter controle total sobre as coisas.

Vamos dar um comando que faça a CLI do Gemini escolher uma das ferramentas integradas para executar e que nos dê uma boa compreensão de como tudo funciona.

Queremos receber informações sobre as últimas notícias financeiras do mundo todo e salvar isso em um arquivo no nosso diretório de trabalho local, de onde iniciamos a CLI do Gemini. Enviamos o seguinte comando:

Search for the latest headlines today in the world of finance and save them in a file named finance-news-today.txt

Imagine por um momento o que ele precisa fazer. O ideal é que ele faça uma Pesquisa Google para receber notícias de algumas fontes de informação relevantes que possam fornecer notícias financeiras. Em seguida, ele precisa criar um arquivo chamado finance-news-today.txt (uma operação de gravação no seu sistema local que vai exigir sua permissão) com o conteúdo.

Vamos ver o que acontece (faça o mesmo na sua máquina).

Primeiro, ele invoca a ferramenta GoogleSearch para pesquisar na Web.

Quando a pesquisa é concluída, ela recupera os dados, conforme mostrado abaixo:

Depois disso, ele estará pronto para gravar no arquivo e usará a ferramenta WriteFile, mas como essa é uma operação sensível (gravar), ele vai pedir sua permissão. Você pode decidir o tipo de permissão, ou seja, permitir uma vez, permitir sempre etc. Por enquanto, vamos selecionar "Permitir uma vez".

Isso vai gravar as informações no arquivo, e uma mensagem de sucesso será mostrada abaixo:

Como verificamos se o arquivo foi gravado ou não? Podemos usar o @file para pedir que ele leia o conteúdo. Damos um comando, conforme mostrado abaixo. Ao digitar @, uma lista de arquivos na pasta atual é exibida, incluindo o arquivo que acabou de ser criado. Selecione essa opção e envie o comando. Meu comando é mostrado abaixo:

read the contents of @finance-news-today.txt

Isso resulta na invocação das ferramentas necessárias (ReadManyFiles, ReadFile) e o conteúdo é exibido conforme mostrado abaixo:

Este também é um bom momento para aprender a trabalhar diretamente com o Shell na CLI do Gemini. Para entrar no modo shell, pressione ! na caixa de mensagem. Isso vai alternar para um modo Shell. Para voltar, pressione ! novamente ou a tecla ESC.

No modo shell, você verá o ! no início do comando, conforme mostrado abaixo:

Posso verificar diretamente usando comandos padrão como pwd e ls, conforme mostrado abaixo:

Podemos imprimir o conteúdo do arquivo com o comando cat hoje.

Exercício: confira um exercício curto para testar. Escolha um feed RSS. Dê um comando à CLI do Gemini para buscar o conteúdo do feed RSS e formatar os resultados de uma maneira específica. Essa é uma boa maneira de automatizar algo no início do dia.

Dica:você vai acabar fazendo com que a CLI do Gemini use a ferramenta WebFetch.

5. Como configurar servidores do Protocolo de Contexto de Modelo (MCP)

Um servidor MCP é um aplicativo que expõe ferramentas e recursos à CLI do Gemini pelo Protocolo de Contexto de Modelo, permitindo que ela interaja com sistemas e fontes de dados externos. Os servidores MCP atuam como uma ponte entre o modelo do Gemini e seu ambiente local ou outros serviços, como APIs.

Um servidor MCP permite que a CLI do Gemini descubra e execute ferramentas, estendendo assim os recursos da CLI do Gemini para realizar ações além dos recursos integrados, como interagir com bancos de dados, APIs, scripts personalizados ou fluxos de trabalho especializados.

A CLI do Gemini permite configurar servidores MCP para descobrir e usar ferramentas personalizadas. Se a CLI do Gemini estiver aberta, você poderá verificar os servidores MCP configurados com o comando /mcp, conforme mostrado abaixo:

Se você não tiver configurado nenhum servidor MCP, a documentação do servidor MCP da CLI do Gemini será aberta.

É possível configurar servidores MCP no nível global no arquivo ~/.gemini/settings.json ou no diretório raiz do projeto. Crie ou abra o arquivo .gemini/settings.json. No arquivo, adicione o bloco de configuração mcpServers, conforme mostrado abaixo:

"mcpServers": {
    "server_name_1": {},
    "server_name_2": {},
    "server_name_n": {}
 }

Cada configuração de servidor é compatível com as seguintes propriedades ( documentação de referência):

Obrigatório (um dos seguintes)

command (string): caminho para o executável do transporte Stdio
url (string): URL do endpoint SSE (por exemplo, "http://localhost:8080/sse")
httpUrl (string): URL do endpoint de streaming HTTP.

Opcional

args (string[]): argumentos de linha de comando para transporte Stdio
headers (objeto): cabeçalhos HTTP personalizados ao usar "url" ou "httpUrl"
env (objeto): variáveis de ambiente para o processo do servidor. Os valores podem fazer referência a variáveis de ambiente usando a sintaxe $VAR_NAME ou ${VAR_NAME}.
cwd (string): diretório de trabalho para transporte Stdio.
timeout (number): tempo limite da solicitação em milissegundos (padrão: 600.000 ms = 10 minutos)
trust (booleano): quando verdadeiro, ignora todas as confirmações de chamada de função para este servidor (padrão: falso).
includeTools (string[]): lista de nomes de ferramentas a serem incluídas deste servidor MCP. Quando especificado, apenas as ferramentas listadas aqui estarão disponíveis nesse servidor (comportamento de lista de permissões). Se não for especificado, todas as ferramentas do servidor serão ativadas por padrão.
excludeTools (string[]): lista de nomes de ferramentas a serem excluídas deste servidor MCP. As ferramentas listadas aqui não estarão disponíveis para o modelo, mesmo que sejam expostas pelo servidor. Observação: excludeTools tem precedência sobre includeTools. Se uma ferramenta estiver nas duas listas, ela será excluída.

Vamos configurar um dos principais servidores MCP que você pode precisar se estiver trabalhando com o GitHub. No entanto, a CLI do Gemini vai invocar as ferramentas do git que você tem no seu sistema, e você também pode instruir a CLI do Gemini a usar isso. Ele vai ajudar você com os comandos e executar as ações, mas você precisa ter essas ferramentas configuradas no seu sistema.

Servidor MCP do GitHub

O servidor MCP oficial do GitHub oferece documentação suficiente sobre as ferramentas que ele expõe e como configurá-las. Você pode escolher executar localmente ou remotamente, já que a CLI Gemini também é compatível com servidores MCP remotos.

Neste tutorial, escolhemos usar a opção de servidor MCP remoto no GitHub. Para isso, primeiro você precisa ter um token de acesso pessoal (PAT) do GitHub.

Depois disso, adicione o objeto do servidor MCP ao arquivo settings.json. O arquivo settings.json completo no meu sistema é mostrado abaixo. Você pode ter outras configurações, mas o objeto mcpServers precisa ser igual ao mostrado abaixo:

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal",
  "mcpServers": {
       "github": {
            "httpUrl": "https://api.githubcopilot.com/mcp/",
            "headers": {
                "Authorization": "GITHUB_PAT"
            },
            "timeout": 5000
       }
  }
}

É possível iniciar a CLI do Gemini novamente ou executar um comando /mcp refresh depois de atualizar o settings.json com a configuração do servidor MCP do GitHub. A captura de tela abaixo destaca o servidor MCP do GitHub configurado na minha máquina e as várias ferramentas agora disponíveis para a CLI do Gemini trabalhar com o MCP.

Vamos começar com um comando que vai invocar uma das ferramentas do servidor MCP do GitHub. Envie o seguinte comando:

Ele vai escolher a ferramenta correta no servidor MCP do GitHub, mas, assim como outras ferramentas integradas, isso também exige que você conceda permissão explícita para invocar a ferramenta. Confira o resultado.

Agora, trabalhe com um dos seus projetos do GitHub. Faça consultas em linguagem natural, como:

Descreva o <repo-name> para mim.
Clone o <repo-name> na minha máquina local.
Descreva @<file-name> ou @<directory-name>/
Quais são os diferentes componentes desse repositório?
Fiz as mudanças necessárias. Você pode enviar as mudanças para o GitHub e usar as ferramentas do servidor MCP do GitHub para fazer isso.

Vamos fazer um exercício para trabalhar com o servidor MCP do GitHub em detalhes mais tarde no laboratório.

Servidor MCP do Context7

O Context7 oferece documentação atualizada para LLMs e editores de código de IA. Se você quiser fornecer o contexto ao LLM com a documentação mais recente do framework de sua escolha, o servidor MCP Context7 é uma boa opção para configurar.

Confira se a biblioteca está listada na página inicial do Context7.

Este é o servidor MCP que você precisa adicionar ao arquivo settings.json.

"context7": {
      "httpUrl": "https://mcp.context7.com/mcp"
    }

Depois que o servidor MCP for configurado e a CLI do Gemini for carregada com ele, você poderá ver as ferramentas do Context7, conforme mostrado abaixo:

Agora você pode ser específico no comando e pedir à CLI do Gemini para usar Context7 na documentação mais recente ao gerar seu aplicativo ou trecho de código usando uma estrutura XYZ específica.

Confira um exemplo de comando em que quero escrever um agente usando o Kit de Desenvolvimento de Agente (ADK) do Google. Estou especificando no meu comando para pesquisar a documentação do mesmo pelo servidor MCP Context7.

I am working on coding an Agent using the Agent Development Kit (ADK) from Google. I would like to know how to create the LLMAgent in Python. Use Context7 for the latest documentation on ADK and specifically use /google/adk-python, /google/adk-docs and adk.wiki

Esta é a saída recebida:

Servidor MCP das Apresentações Google

O projeto do GitHub em https://github.com/matteoantoci/google-slides-mcp (link em inglês) fornece um servidor MCP para interagir com a API Google Slides. Ele permite criar, ler e modificar apresentações Google de maneira programática.

As etapas para configurar o servidor MCP são fornecidas no projeto. Você precisa ter um ambiente Node.js em que vai criar o servidor, configurar um projeto do Google Cloud e tokens OAuth 2.0 e, em seguida, configurar o servidor MCP no arquivo settings.json.

Depois da configuração, você pode executar comandos como:

Extraia as informações mais recentes de "web_url", resuma-as em pontos principais e crie uma apresentação chamada "my_presentation".

Experimente!

Mais servidores MCP

Confira outra lista de servidores MCP que podem ser interessantes para você:

Servidor MCP do Firebase
Serviços de mídia de IA generativa do Google (Imagen, Veo, Lyria)
Caixa de ferramentas do MCP para bancos de dados (trabalhe com o Firestore, o BigQuery e os bancos de dados do Google Cloud)
Servidor MCP do Google Workspace (trabalhe com Documentos, Planilhas, Agenda e Gmail)

As instruções para configurar os servidores MCP acima estão publicadas nesta postagem do blog.

6. Casos de uso para testar

A CLI do Gemini pode ser aplicada a uma ampla variedade de casos de uso para desenvolvedores e não desenvolvedores. Confira alguns cenários e, dependendo da sua área de interesse, teste qualquer um ou todos eles.

Em cada um desses casos, o comando é fornecido. Você pode testar isso no modo interativo ou não interativo da CLI do Gemini usando o parâmetro -p ao iniciar a CLI do Gemini.

Organizar arquivos/pastas

Você pode usar a CLI do Gemini para organizar os arquivos de acordo com os tipos em várias pastas, conforme necessário. Acesse uma pasta no seu computador que tenha vários arquivos .txt, .png, .jpg, .pdf, .mp4 e outros. Geralmente, é a área de trabalho ou a pasta "Downloads".

Navegue até essa pasta e inicie a CLI do Gemini. Vamos pedir para ele criar várias pastas primeiro: Imagens, Documentos, Vídeos e depois organizar os arquivos nelas.

A CLI Gemini geralmente pede permissão antes de executar comandos, especialmente aqueles que modificam seu sistema de arquivos (como gravar, mover ou excluir arquivos). Sempre revise esses comandos com atenção antes de conceder permissão. Essa é sua rede de segurança.

Create the following folders "Images","Documents","Videos"

Em seguida, envie o seguinte comando:

Go through all the files in this folder and then organize them by moving all the files ending with .jpg, .jpeg, .gif into the "Images" folder. Move all ".txt" files into the "Documents" folder. Move all the ".mp4" files in the "Videos" folder.

Confira alguns outros cenários de organização (os comandos são fornecidos ao lado de cada cenário):

Resumo:para cada documento na pasta "Documentos", crie um arquivo txt na mesma pasta chamado "summary_ORIGINAL_FILENAME.txt" que contenha um resumo de três frases dos principais pontos do documento.
Categorização por tipo:verifique todos os arquivos PDF e DOCX neste diretório. Mova todos os arquivos com "invoice" no nome ou conteúdo para a pasta "Financial/Invoices". Mova os arquivos com "receipt" para "Financial/Receipts". Todos os outros arquivos .docx vão para "Relatórios".
Extração de informações importantes (e "tagging"): para cada arquivo PDF na pasta "Financial/Invoices", leia o conteúdo. Se você encontrar uma data, renomeie o arquivo para incluir essa data no formato AAAA-MM-DD. Por exemplo: ‘invoice_2025-07-26_original_name.pdf'.