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.

O que você vai aprender

Instalar e configurar a CLI do Gemini
Como explorar ferramentas, comandos integrados e configurar servidores MCP 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

Este codelab pode ser executado totalmente no Google Cloud Shell, que vem pré-instalado com a CLI Gemini.

Se preferir trabalhar na sua própria máquina, há uma seção para instalar a CLI do Gemini localmente.

Você vai precisar do seguinte:

Navegador da Web Google Chrome
Uma conta do Gmail

Este codelab foi criado para usuários e desenvolvedores de todos os níveis, incluindo iniciantes. Os casos de uso no codelab foram categorizados em tarefas de desenvolvedor e não desenvolvedor. Os casos de uso para desenvolvedores mostram como programar com a CLI do Gemini e trabalhar com um repositório do GitHub para realizar tarefas comuns de desenvolvimento, como explicação/compreensão de código, geração de documentação, correção de problemas e muito mais. Recomendamos que você conclua esses casos de uso no codelab. Há uma seção opcional no final que aborda várias tarefas diárias que não são focadas em desenvolvedores.

2. Antes de começar

Criar um projeto

No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
Confira se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

Você vai usar o Cloud Shell, um ambiente de linha de comando executado no Google Cloud que vem pré-carregado com bq. Clique em "Ativar o Cloud Shell" na parte de cima do console do Google Cloud.

Imagem do botão "Ativar o Cloud Shell"

Depois de se conectar ao Cloud Shell, verifique se sua conta já está autenticada e se o projeto está configurado com seu ID do projeto usando o seguinte comando:

gcloud auth list

Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto.

gcloud config list project

Se o projeto não estiver definido, use este comando:

gcloud config set project <YOUR_PROJECT_ID>

3. Instalação

Antes de fazer a configuração e executar a CLI do Gemini, vamos criar uma pasta que você vai usar como pasta inicial para todos os projetos que criar nela. Esse é um ponto de partida para a CLI do Gemini trabalhar, mas ela também vai referenciar outras pastas no seu sistema, que você vai conhecer 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

Você pode iniciar a CLI do Gemini diretamente com o comando gemini.

Acesse diretamente a próxima seção (configuração da CLI Gemini via settings.json).

Se você quiser instalar a CLI do Gemini localmente, siga as instruções abaixo.

A primeira etapa é instalar o Node 20 ou mais recente na sua máquina. Depois disso, você pode instalar e executar a CLI do Gemini usando um dos seguintes métodos:

Primeiro, instale a CLI Gemini globalmente no seu sistema. Talvez você precise de acesso de administrador para realizar essa etapa.

# option 1: install Gemini CLI

npm install -g @google/gemini-cli

# .. and then run
gemini

Execute com o seguinte comando:

# option 2: run without installing Gemini CLI

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

Para confirmar se a CLI está instalada, execute:

gemini --version

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:

4. Configuração da CLI do Gemini usando settings.json

Se você escolher o Cloud Shell para executar o Gemini, um tema padrão para a CLI do Gemini e o método de autenticação já serão selecionados e configurados para você.

Se você instalou e iniciou a CLI Gemini pela primeira vez, selecionou um tema e um método de autenticação.

Agora, 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 precedência (o Cloud Shell só disponibiliza as configurações do usuário):

Sistema: /etc/gemini-cli/settings.json (aplicável a todos os usuários, substitui as configurações do usuário e do espaço de trabalho).
Workspace: .gemini/settings.json (substitui as configurações do usuário).
Usuário: ~/.gemini/settings.json.

Usuário do Windows: %USERPROFILE%.gemini\settings.json (que geralmente é expandido para C:\Users<YourUsername>.gemini\settings.json)

Sistema: %ProgramData%\gemini-cli\settings.json (que geralmente é expandido para C:\ProgramData\gemini-cli\settings.json)

Usuário do Mac: ~/.gemini/settings.json (que se expande para /Users/<YourUsername>/.gemini/settings.json)

Sistema: /etc/gemini-cli/settings.json

Se você se lembra, ao selecionar o tema, você escolheu salvar as configurações 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" or "cloud-shell"
}

5. Nossa primeira interação com a CLI do Gemini

Vamos começar a usar a CLI do Gemini e digitar sua primeira consulta, conforme mostrado abaixo:

Give me a famous quote on Artificial Intelligence and who said that?

A resposta esperada é mostrada abaixo:

Você vai notar que nossa consulta resultou em uma ferramenta GoogleSearch (uma ferramenta integrada na CLI do Gemini) que foi invocada. Em outras palavras, você já usou uma das ferramentas integradas da CLI do Gemini, o GoogleSearch, que fundamenta as respostas com base em informações da Web. Você vai saber mais sobre as Ferramentas na próxima seção.

Uma maneira rápida de entender a CLI do Gemini e os vários comandos que ela oferece é digitar /help (barra) para ver uma variedade de comandos e atalhos de teclado, conforme mostrado abaixo:

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.

6. CLI do Gemini: parâmetros de comando

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. Esse modo também não permite autorizar ferramentas (incluindo WriteFile) nem executar comandos do shell.

7. 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, invoque 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 (não é recomendado), 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 usar um comando que fará com que a CLI do Gemini escolha uma das ferramentas integradas para executar e que vai ajudar você a entender como tudo funciona.

Imagine um cenário em que você quer receber as últimas notícias financeiras do mundo todo e salvar essas informações em um arquivo no diretório de trabalho local de onde você iniciou a CLI Gemini. Use 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, selecione "Permitir uma vez".

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

Como verificar se o arquivo foi gravado ou não? Use o @file para pedir que ele leia o conteúdo. 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:

8. CLI do Gemini: modo shell

Este é 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:

É possível verificar diretamente usando comandos padrão, como pwd e ls, conforme mostrado abaixo. Os comandos pressupõem um SO do tipo Linux. Se você estiver em outro sistema operacional (Windows), use comandos equivalentes, como cd, dir e type. A saída dessas chamadas está incluída na janela de contexto do modelo.

Você pode imprimir o conteúdo do arquivo com o comando cat hoje mesmo.

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. Você pode até pedir que a CLI Gemini descubra se há um feed RSS para uma área específica, por exemplo, as notas da versão do Google Cloud Platform.

Confira um exemplo de comando abaixo:

Get the latest release notes for Google Cloud from its RSS Feed and display the key points in a well-formatted list.

O ideal é que esse comando primeiro invoque a ferramenta GoogleSearch para encontrar o feed RSS do Google Cloud Platform e depois use a ferramenta WebFetch para acessar e mostrar o conteúdo do feed RSS.

9. 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. Você provavelmente tem uma dúvida: se já tiver o Git e outras ferramentas relacionadas configuradas no seu sistema, ainda vai precisar do servidor MCP do GitHub?

A CLI do Gemini vai invocar as ferramentas do Git que você tem no sistema, e você também pode instruir a CLI do Gemini a usar isso. A CLI do Gemini ajuda a traduzir suas consultas em linguagem natural para ferramentas equivalentes que você pode ter no seu sistema. Talvez seja necessário declarar isso explicitamente no comando.

Talvez você não precise da próxima seção para configurar um servidor MCP do GitHub se já tiver o seguinte configurado no seu sistema:

Ferramentas do Git (isso significa que você pode executar comandos como git init, git add etc. no seu sistema)
gh : é o GitHub na linha de comando. Ele traz solicitações de pull, problemas e outros conceitos do GitHub para o terminal ao lado de onde você já está trabalhando com o git e seu código. Instale aqui e valide a configuração com alguns comandos, principalmente em relação à autenticação no GitHub na sua máquina.

Se você ainda quiser testar o servidor MCP do GitHub, consulte a próxima seção ou pule essa parte.

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.

Este tutorial demonstra 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.

Você vai encontrar um exercício para trabalhar com o servidor MCP do GitHub em detalhes mais adiante 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.

10. Personalizar a CLI do Gemini com GEMINI.md

Se você acompanhou o uso da CLI do Gemini até agora, deve ter notado que apenas enviamos o comando e esperamos que a CLI do Gemini o execute, às vezes com resultados que não atendem às nossas expectativas. Em alguns comandos, você foi um pouco específico em termos de o que fazer e incluiu essas instruções no comando.

Isso pode funcionar bem de acordo com o que você está instruindo a CLI do Gemini a fazer e os resultados que você recebe. Mas, em muitos casos, é importante garantir que ele siga regras. Essas regras podem ser linguagens de programação ou frameworks específicos a serem usados. Também podem ser ferramentas específicas. Podem ser estilos de programação. Não é só sobre geração, mas talvez você também queira que a CLI do Gemini esteja estritamente no modo "planejamento" e apenas apresente um plano, sem gerar código ou modificar arquivos no sistema.

Digite GEMINI.md. Esse é o arquivo de contexto (o padrão é GEMINI.md, mas pode ser configurado usando a propriedade contextFileName no arquivo settings.json) que é essencial para configurar o contexto instrucional (também chamado de "memória") fornecido ao modelo do Gemini. Com esse arquivo, você pode dar instruções específicas do projeto, guias de estilo de programação ou informações relevantes para a IA, tornando as respostas mais personalizadas e precisas para suas necessidades.

O arquivo GEMINI.md está no formato Markdown e é carregado de maneira hierárquica, combinada de vários locais.

A ordem de carregamento é:

Contexto global:**~/.gemini/GEMINI.md** (para instruções que se aplicam a todos os seus projetos).
Contexto do projeto/ancestral:a CLI pesquisa do diretório atual até a raiz do projeto por arquivos GEMINI.md.
Contexto do subdiretório:a CLI também verifica subdiretórios em busca de arquivos GEMINI.md, permitindo instruções específicas do componente.

Use o /memory show para ver o contexto combinado final enviado ao modelo.

Como é um GEMINI.md? Criamos um com base na documentação oficial:

# Project: My Awesome TypeScript Library

## General Instructions:

- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 20+.

## Coding Style:

- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).

## Specific Component: `src/api/client.ts`

- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.

## Regarding Dependencies:

- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.

Ele fornece algumas instruções gerais, além de instruções muito específicas para estilo de programação, gerenciamento de dependências e muito mais. Embora este seja um exemplo de arquivo GEMINI.md para projetos TypeScript, você pode escrever o seu com base na linguagem de programação, no framework, no estilo de programação e em outras preferências.

Você pode testar um arquivo GEMINI.md personalizado. Este é um gist publicado que mostra como usar a CLI do Gemini apenas no modo de planejamento. O arquivo é reproduzido aqui:

# Gemini CLI Plan Mode
You are Gemini CLI, an expert AI assistant operating in a special 'Plan Mode'. Your sole purpose is to research, analyze, and create detailed implementation plans. You must operate in a strict read-only capacity.

Gemini CLI's primary goal is to act like a senior engineer: understand the request, investigate the codebase and relevant resources, formulate a robust strategy, and then present a clear, step-by-step plan for approval. You are forbidden from making any modifications. You are also forbidden from implementing the plan.

## Core Principles of Plan Mode
*   **Strictly Read-Only:** You can inspect files, navigate code repositories, evaluate project structure, search the web, and examine documentation.
*   **Absolutely No Modifications:** You are prohibited from performing any action that alters the state of the system. This includes:
    *   Editing, creating, or deleting files.
    *   Running shell commands that make changes (e.g., `git commit`, `npm install`, `mkdir`).
    *   Altering system configurations or installing packages.

## Steps
1.  **Acknowledge and Analyze:** Confirm you are in Plan Mode. Begin by thoroughly analyzing the user's request and the existing codebase to build context.
2.  **Reasoning First:** Before presenting the plan, you must first output your analysis and reasoning. Explain what you've learned from your investigation (e.g., "I've inspected the following files...", "The current architecture uses...", "Based on the documentation for [library], the best approach is..."). This reasoning section must come **before** the final plan.
3.  **Create the Plan:** Formulate a detailed, step-by-step implementation plan. Each step should be a clear, actionable instruction.
4.  **Present for Approval:** The final step of every plan must be to present it to the user for review and approval. Do not proceed with the plan until you have received approval. 

## Output Format
Your output must be a well-formatted markdown response containing two distinct sections in the following order:

1.  **Analysis:** A paragraph or bulleted list detailing your findings and the reasoning behind your proposed strategy.
2.  **Plan:** A numbered list of the precise steps to be taken for implementation. The final step must always be presenting the plan for approval.

NOTE: If in plan mode, do not implement the plan. You are only allowed to plan. Confirmation comes from a user message.

Salve o conteúdo acima em um arquivo chamado GEMINI.md e salve em ~/.gemini/GEMINI.md. Essa é a mesma pasta em que você criou o arquivo settings.json. Você também pode manter o arquivo GEMINI.md na pasta <current project folder>/.gemini ou ter vários arquivos GEMINI.md nos subdiretórios se tiver instruções diferentes.

Dê um comando para gerar um aplicativo e veja como ele responde.

Confira outro arquivo GEMINI.md ( Modo de explicação do Gemini) que você pode estudar e reutilizar para suas necessidades. O foco é que a CLI do GEMINI seja um guia interativo, ajudando os usuários a entender bases de código complexas por um processo de descoberta conversacional.

O arquivo GEMINI.md é essencial para que a CLI do Gemini siga suas preferências. Recomendamos conferir a série prática CLI do Gemini na prática, que aborda essa área, como gerar um arquivo automaticamente para seu projeto, personalizar até mesmo o comando do sistema e muito mais.

Você também pode criar o arquivo GEMINI.md enquanto interage com a CLI do Gemini. A qualquer momento, use o comando /memory add <alguma instrução/regra>, e a CLI Gemini vai anexar isso ao arquivo GEMINI.md. Você pode até usar a linguagem natural para pedir à CLI Gemini que adicione à memória, por exemplo, GEMINI.md, usando comandos como "Lembre-se de <alguma instrução/regra>" ou "Adicione à memória <alguma instrução/regra>".

11. CLI do Gemini: comandos de barra personalizados

Você acabou de ver como personalizar GEMINI.md para criar um modo de planejamento. A seção anterior também forneceu links para um modo de explicação.

E se você quisesse configurar os dois modos e instruir a CLI Gemini a entrar em qualquer um deles usando os comandos de barra /plan ou /explain? É exatamente isso que os comandos de barra personalizados da CLI do Gemini fazem.

Conforme a documentação afirma, "Com os comandos personalizados, é possível salvar e reutilizar seus comandos favoritos ou mais usados como atalhos pessoais na CLI do Gemini. É possível criar comandos específicos para um único projeto ou comandos disponíveis globalmente em todos os projetos, simplificando seu fluxo de trabalho e garantindo a consistência."

Vamos criar alguns comandos de barra personalizados: /plan e /explain.

A próxima etapa é entender de onde a CLI do Gemini extrai os comandos personalizados. De acordo com a documentação, ele descobre comandos de dois locais, carregados em uma ordem específica:

Comandos do usuário (globais): localizados em ~/.gemini/commands/. Esses comandos estão disponíveis em qualquer projeto em que você esteja trabalhando.
Comandos do projeto (local): localizado em <your-project-root>/.gemini/commands/. Esses comandos são específicos do projeto atual e podem ser verificados no controle de versões para serem compartilhados com sua equipe.

Vamos escolher a pasta do projeto atual de onde você iniciou a CLI do Gemini. Então, essa será a pasta <your-project-root>/.gemini/commands/. Crie a estrutura de pastas.

O que precisamos criar dentro dessa pasta? Precisamos de dois arquivos TOML (plan.toml e explain.toml). Leia mais sobre namespaces e convenções de nomenclatura aqui.

Cada arquivo TOML precisa ter dois campos : description e prompt. A descrição precisa ser curta e objetiva, já que vai aparecer ao lado do comando na CLI do Gemini. O exemplo de arquivo TOML abaixo foi extraído da postagem oficial do blog sobre comandos de barra personalizados.

Confira abaixo um exemplo de arquivo plan.toml. O comando contém um marcador de posição especial {{args}}. A CLI vai substituir esse marcador por todo o texto digitado pelo usuário após o nome do comando.

description="Investigates and creates a strategic plan to accomplish a task."
prompt = """
Your primary role is that of a strategist, not an implementer.
Your task is to stop, think deeply, and devise a comprehensive strategic plan to accomp{{lish the following goal: args}}

You MUST NOT write, modify, or execute any code. Your sole function is to investigate the current state and formulate a plan.

Use your available "read" and "search" tools to research and analyze the codebase. Gather all necessary context before presenting your strategy.

Present your strategic plan in markdown. It should be the direct result of your investigation and thinking process. Structure your response with the following sections:

1.  **Understanding the Goal:** Re-state the objective to con&firm your understanding.
2.  **Investigation  Analysis:** Describe the investigative steps you would take. What files would you need to read? What would you search for? What critical questions need to be answered before any work begins?
3.  **Proposed Strategic Approach:** Outline the high-level strategy. Break the approach down into logical phases and describe the work that should happen in each.
4.  **Verification Strategy:** Explain how the success of this plan would be measured. What should be tested to ensure the goal is met without introduci&ng regressions?
5.  **Anticipated Challenges  Considerations:** Based on your analysis, what potential risks, dependencies, or trade-offs do you foresee?

Your final output should be ONLY this strategic plan.
"""

Tente criar um arquivo explain.toml também. Você pode consultar o modo de explicação do Gemini para escolher um conteúdo.

Reinicie a CLI do Gemini. Agora você vai encontrar um comando de barra (/plan), como mostrado abaixo:

12. 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.

Programação com a CLI do Gemini

Vamos usar a CLI do Gemini para criar um aplicativo com vibe code. Nesta tarefa, você vai pedir à CLI do Gemini para gerar um aplicativo e enviar a versão inicial para um repositório do GitHub.

Pré-requisito

Para executar as tarefas nesta seção, há alguns pré-requisitos:

Git
CLI do Gemini com o servidor MCP do GitHub (já fizemos isso) ou se você configurou o gh ( ferramenta da CLI do GitHub), isso também funciona.
Familiaridade com os princípios básicos do Git e um pouco de conhecimento de programação

Vamos presumir que você iniciou a CLI do Gemini em uma pasta específica da sua escolha. Verifique se os servidores MCP foram iniciados com sucesso, principalmente o servidor MCP do GitHub.

Comece com um comando inicial. Modifique como quiser. Durante a sessão com a CLI do Gemini, ela vai pedir permissões para criar arquivos etc. Conceda as permissões necessárias.

Nesta tarefa, não queremos que a CLI do Gemini execute ou teste o aplicativo para nós, já que queremos um pouco mais de controle. Mas a decisão é totalmente sua.

Generate a website for a 1-day event filled with technical talks. There are going to be 6 talks in a single track of 1 hour each. Each talk has the following information: title, 1 or maximum of 2 speakers, category (1 or maximum of 3 keywords), duration and a description. The website has a single page where users can see the schedule for the entire day with the timings. There will be one lunch break of an hour and the event starts at 10:00 AM. Keep a 10 minute transition between talks. I would like to use Node.js on the server side and standard HTML, JavaScript and CSS on the front-end. The users should be able to search the talks based on category.

I would like you to proceed in the following way: 
1. Plan out how you would design and code this application.
2. Ask me for any clarifications along the way.
3. Once I am fine with it, do generate the code and provide me instructions to run and test locally.

Os próximos comandos e respostas são um exemplo de fluxo observado. Você pode receber uma resposta completamente diferente. Por isso, analise o plano e interaja com a CLI do Gemini conforme necessário.

Às vezes, a CLI do Gemini tenta fazer mais e até dá os comandos que gostaria de executar. Para este exercício, é recomendável não fazer isso para ter mais controle sobre como ele realiza a tarefa e o que você gostaria de validar primeiro.

Por exemplo, se ele oferecer a execução dos comandos, basta sair e dar uma mensagem como mostrado abaixo:

Ao seguir as instruções para iniciar o servidor e navegar até a página inicial, recebemos um site de amostra, conforme mostrado abaixo. Você vai ver uma variante de um site semelhante se tiver usado o mesmo comando:

Você pode continuar fazendo mais mudanças com a ajuda da CLI do Gemini. Quando estiver satisfeito com as mudanças, envie para um repositório do GitHub.

Primeiro, vamos criar um arquivo .gitignore com a ajuda da CLI do Gemini.

Create a .gitignore file for this project.

A próxima etapa é dar instruções à CLI Gemini para enviar esse repositório na nossa conta do GitHub. Isso vai exercitar as ferramentas do servidor MCP do GitHub em segundo plano.

Envie um comando semelhante a este:

Great! I would now like to push all of this to a new repository in my Github account. I would like to name this repository <Your-Name>-event-talks-app

Ele vai passar por vários comandos aqui:

Crie o repositório.
Ele vai usar vários comandos do Git : init, add, commit para gerenciar o repositório Git local.
Em seguida, ele vai configurar o Git remoto e fazer um push.

Observação:há casos em que a CLI do Gemini pode atingir o tempo limite ou usar um nome de usuário incorreto etc. Interaja com ela e sugira as correções.

Se tudo der certo, você terá um repositório do GitHub. Confira abaixo uma captura de tela de exemplo:

Você não gerou um README.md para este projeto. Isso é um bom exercício para a próxima seção, em que vamos trabalhar com o repositório que você acabou de criar.

Usar a CLI Gemini para trabalhar em um repositório do GitHub

Neste caso de uso, você vai usar a CLI do Gemini para trabalhar com um repositório do GitHub. Você vai realizar várias tarefas, incluindo:

Noções básicas sobre a base de código
Gerar a documentação
Implementar um novo recurso
Confirme e envie as mudanças de volta para o repositório
Trabalhar em um problema do GitHub e implementar as mudanças propostas

Isso vai dar uma boa base para trabalhar com seus repositórios e usar a CLI do Gemini como um assistente para essas tarefas específicas do desenvolvedor.

Pré-requisito

Para realizar as tarefas desta seção, você precisa fazer o seguinte:

Git
CLI do Gemini com o servidor MCP do GitHub (já fizemos isso) ou se você configurou o gh ( ferramenta da CLI do GitHub), isso também funciona.
Familiaridade com os conceitos básicos do Git e um pouco de conhecimento de programação. Vamos usar o Node.js neste exemplo porque você já pode ter o ambiente pronto na sua máquina devido à instalação da CLI Gemini. Mas, depois, você pode escolher um repositório com uma linguagem de programação e um framework diferentes.
Você precisa ter concluído a seção anterior e ter o repositório em mãos, onde criamos um site de Event Talks.

Vamos continuar usando a CLI do Gemini na pasta/diretório que você usou para gerar o aplicativo Event Talks. Se necessário, clone o repositório na sua máquina local e inicie a CLI do Gemini nesse diretório. Teste os seguintes cenários:

Noções básicas sobre a base de código

Quero entender esse projeto em detalhes. Me ajude a entender os principais recursos e depois divida em lado do servidor e do cliente. Pegue um fluxo de amostra e mostre como a solicitação e a resposta funcionam.
Explicar @server.js

Como gerar um arquivo README

Gere um arquivo README para este projeto.

Nesse caso, a CLI Gemini não apenas gerou o arquivo README, mas também quis executar os comandos para adicionar ao repositório Git e enviar as mudanças para o repositório remoto. Se você encontrar essa ação, permita que ela seja feita.

Em alguns casos, ele pode até gerar o arquivo LICENSE para você. Você pode decidir se quer fazer isso. Dependendo do resultado, os arquivos README e/ou LICENSE serão gerados, e as mudanças serão enviadas para o GitHub.

Implementar um novo recurso

Quero implementar um novo recurso em que o usuário também possa pesquisar por um determinado alto-falante. Primeiro, mostre um plano de como você implementaria essa mudança e, depois, podemos gerar o código.

Ele vai fornecer um plano que você pode aprovar. Após a aprovação, a CLI do Gemini vai fazer essas mudanças. Teste suas mudanças e, se houver bugs (o que é provável), peça para a CLI do Gemini corrigir.

Quando as mudanças estiverem boas, siga as mesmas etapas para confirmar e enviar por push ao repositório remoto.

Gerar problemas com base em recursos sugeridos

Vamos tentar algo interessante aqui. Você vai perguntar à CLI do Gemini como ela pode melhorar a experiência do usuário desse aplicativo e, com base na avaliação, ela pode criar essas sugestões como problemas no mesmo repositório do GitHub. Ele vai usar a ferramenta "create_issue" do servidor MCP do GitHub.

Tente o seguinte comando:

Quero que você avalie o aplicativo do ponto de vista da experiência do usuário. Facilidade de uso, capacidade de resposta, mensagens úteis e muito mais. Crie uma lista de melhorias e crie problemas no repositório do GitHub.

O ideal é que ele compartilhe as melhorias primeiro com você e depois crie os problemas no repositório do GitHub com sua permissão. Confira um exemplo de captura de tela da nossa execução:

Trabalhar em um problema do GitHub e implementar as mudanças propostas

Agora você pode pegar um dos problemas gerados anteriormente e pedir para a CLI do Gemini trabalhar e implementar a solução.

Confira abaixo um exemplo de problema gerado:

Pegue o URL do problema inteiro e forneça um comando como este:

Leia o problema: <YOUR_ISSUE_URL> e entenda quais mudanças precisam ser feitas. Primeiro, discuta o plano e depois mostre as mudanças propostas no código.

Aprove as mudanças e envie-as para o repositório. Você pode até pedir para ele fechar o problema.

(Opcional) Atividades cotidianas

Os casos de uso abaixo são tarefas que você pode acabar fazendo regularmente. Isso inclui organizar arquivos em pastas, buscar e resumir conteúdo da Web, processar arquivos de imagem e extrair conteúdo deles, trabalhar com bancos de dados e muito mais.

Explore os casos de uso que quiser.

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".

Confira um exemplo de pasta e o conteúdo dela abaixo. Talvez você tenha outros arquivos:

Navegue até essa pasta e inicie a CLI do Gemini. Primeiro, você vai pedir para a CLI do Gemini criar algumas pastas: "Imagens", "Documentos" e "Vídeos". Depois, vai pedir para ela organizar os arquivos nas pastas.

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 abaixo um exemplo do estado final da pasta. Você vai ver novas subpastas criadas e os arquivos movidos para elas, dependendo do tipo.

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'.