Como começar a usar as extensões da CLI do Gemini

1. Introdução

A CLI do Gemini é um agente de código aberto com tecnologia de IA para seu terminal que leva o poder dos modelos do Gemini diretamente à sua linha de comando. Embora seja poderoso por si só, o verdadeiro potencial dele é revelado pelas extensões da CLI do Gemini.

As extensões são a maneira oficial e padronizada de aumentar os recursos da CLI do Gemini. Antes das extensões, a personalização da CLI geralmente envolvia a edição manual de arquivos de configuração, como settings.json, um processo que podia ser "desorganizado e propenso a erros".

Pense em uma extensão como um "contêiner" para personalizações da CLI do Gemini. É um pacote independente, com controle de versões e fácil de distribuir que reúne todos os componentes necessários para ensinar um novo conjunto de habilidades ao Gemini. Esse "contêiner de transporte" pode incluir :

• Configurações do servidor MCP: conectam o Gemini a ferramentas e APIs externas, como as APIs do Google Cloud ou serviços de terceiros.
• Arquivos de contexto (GEMINI.md): são "playbooks" que fornecem ao modelo instruções e diretrizes específicas sobre como usar as novas ferramentas de maneira eficaz.
• Comandos de barra personalizados (arquivos .toml): encapsulam comandos complexos e de várias etapas em comandos simples e fáceis de usar, como /deploy.
• Restrições de ferramentas (excludeTools): podem desativar ferramentas integradas para criar um ambiente mais seguro ou focado.

O principal valor das extensões é transformar a CLI do Gemini de um assistente pessoal em uma plataforma escalonável e pronta para empresas. Uma equipe pode empacotar toda a pilha de nuvem em uma única extensão, permitindo que novos desenvolvedores se tornem produtivos com um comando.

Neste codelab, você vai aprender a usar esse ecossistema eficiente. Você não vai criar uma extensão, mas vai instalar e usar quatro extensões diferentes para adicionar recursos de implantação de aplicativos, análise de segurança, análise de dados e infraestrutura como código ao seu terminal.

O que você aprenderá

• Instale e configure a CLI do Gemini e os pré-requisitos do Google Cloud.
• Procure extensões na galeria oficial de extensões da CLI do Gemini.
• Use a interface de linha de comando gemini extensions para instalar, listar e gerenciar extensões.
• Conheça algumas extensões da CLI do Gemini

O que você vai aprender

• O que são as extensões da CLI do Gemini e por que elas são o padrão para personalizar a CLI.
• Como encontrar e instalar extensões na Galeria de extensões ou em um URL do GitHub.
• A função dos comandos de gerenciamento de chaves: gemini extensions install, gemini extensions list e gemini extensions update.
• Como instalar e usar algumas extensões da CLI do Gemini

O que é necessário

• Navegador da Web Google Chrome
• Uma conta do Gmail
• Um projeto do Cloud com faturamento ativado

Este codelab foi criado para usuários e desenvolvedores de todos os níveis, incluindo iniciantes. É recomendável ter alguma familiaridade com a CLI do Gemini, mas as etapas para instalar a CLI do Gemini do zero serão fornecidas. Se quiser conhecer a CLI do Gemini, faça o codelab prático da CLI do Gemini.

2. Antes de começar

Criar um projeto

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

Para créditos do Google Cloud:se você quiser receber créditos do Google Cloud para começar, use este link e resgate créditos que vão ajudar você a concluir o laboratório. Siga as instruções neste link para resgatar.

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

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

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

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

7. Ative as APIs necessárias com o comando mostrado abaixo. Isso pode levar alguns minutos.

gcloud services enable cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \

Após a execução do comando, você vai receber uma mensagem semelhante à mostrada abaixo:

Operation "operations/..." finished successfully.

Se alguma API for esquecida, você sempre poderá ativá-la durante a implementação.

Consulte a documentação para ver o uso e os comandos gcloud.Antes de fazer a configuração e executar a CLI 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, embora também faça referência a 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

Observação:se você estiver usando o Google Cloud Shell, a CLI do Gemini já estará instalada.

Você pode iniciar a CLI do Gemini diretamente com o comando gemini em um novo terminal do Cloud Shell ou ela já terá sido iniciada em um terminal separado do Cloud Shell.

Nossa primeira interação com a CLI do Gemini

Precisamos garantir que tudo esteja bem com nosso ambiente da CLI do Gemini para dar nosso primeiro comando, conforme mostrado abaixo:

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

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 receber uma resposta para sua consulta.

Vamos começar com as extensões.

3. O que é uma extensão?

Uma extensão é um pacote independente, com controle de versões e fácil de distribuir. Pense nele como o "contêiner de transporte" das suas personalizações da CLI Gemini, agrupando tudo o que é necessário para um fluxo de trabalho específico em um único pacote organizado.

Uma extensão pode agrupar qualquer combinação de:

• Comandos de barra personalizados (seus arquivos .toml).
• Configurações do servidor MCP (que antes ficavam em settings.json).
• Arquivos de contexto (GEMINI.md) para fornecer instruções e diretrizes específicas ao modelo.
• Restrições de ferramentas (excludeTools) para criar um ambiente mais seguro e focado.

Por que usar extensões? Os principais benefícios

Adotar extensões para suas personalizações oferece várias vantagens importantes:

• Instalação com um comando: isso é essencial. Em vez de uma configuração manual de várias etapas, um usuário pode instalar um conjunto de ferramentas completo e complexo com um único comando: gemini extensions install <URL> ou gemini extensions install --path=some/local/path. O <URL> no comando acima pode ser o URL do GitHub em que você hospedou a extensão.
• Distribuição simplificada: compartilhar seu trabalho é tão fácil quanto compartilhar um único URL de repositório Git. Não é mais necessário passar arquivos individuais e snippets de configuração.
• Controle de versões e gerenciamento de dependências: como as extensões geralmente são hospedadas em repositórios Git, você tem controle de versões sem custo financeiro. Há gemini extensions update command maneiras de atualizar uma extensão para a versão mais recente.
• Capacidade de descoberta e ecossistema: as extensões são a base de um ecossistema rico e aberto, assim como os marketplaces do VS Code ou do Chrome. O mecanismo de extensões pode formar a base de um futuro marketplace em que essas extensões estejam disponíveis para análise, download e muito mais, no verdadeiro estilo da comunidade.

A introdução do framework de extensões é um sinal claro de que a CLI do Gemini está evoluindo de uma ferramenta independente poderosa para uma plataforma extensível de verdade.

4. Entender os fundamentos das extensões

Esta seção aborda as partes do ecossistema de extensões voltadas para o usuário: como encontrar extensões e como gerenciá-las.

Conheça a galeria de extensões

A Galeria de extensões é o marketplace central para descobrir todas as extensões oficiais criadas pelo Google e de terceiros:

1. Abra o seguinte URL no seu navegador: https://geminicli.com/extensions/browse/.
2. Essa galeria é o mecanismo de capacidade de descoberta do ecossistema. Você pode conferir extensões de empresas como GitHub, Redis e DynaTrace, mostrando a variedade de ferramentas disponíveis.
3. Role a tela para baixo e encontre o card de extensão do Cloud Run.
4. O card fornece uma descrição, o autor (Google) e um botão de comando Copy install com um clique. Essa é a maneira mais simples de receber o comando de instalação de uma extensão.

Extensões da CLI do Gemini: comandos de gerenciamento

O comando gemini extensions é o ponto de entrada para gerenciar suas extensões locais.

Execute no terminal para ver a lista de comandos disponíveis.

Os comandos são simples (instalar/desinstalar, listar, atualizar, ativar/desativar etc.), e vamos usar alguns deles neste codelab.

Verificar seu estado atual

Antes de instalar qualquer coisa, vamos verificar nossa "página em branco".

1. Execute o comando gemini extensions list:
2. Você vai ver a seguinte saída, confirmando que nenhuma extensão foi instalada ainda.

No extensions installed.

5. A extensão do Cloud Run (como implantar um app)

A extensão do Cloud Run disponível na galeria de extensões da CLI do Gemini é um servidor MCP que permite implantar nossos aplicativos no Cloud Run.

Confira abaixo o card da extensão do Cloud Run na galeria de extensões:

Primeiro, instale a extensão do Cloud Run clicando em Copiar comando de instalação, conforme mostrado acima. Em seguida, cole esse comando no terminal do Cloud Shell. Ele será semelhante a este:

gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp

Ao executar o comando acima, você vai ver uma confirmação necessária. Aprove. A extensão do Cloud Run será instalada.

Installing extension "cloud-run".
**Extensions may introduce unexpected behavior. Ensure you have investigated the extension source and trust the author.**
This extension will run the following MCP servers:
  * cloud-run (local): npx -y @google-cloud/cloud-run-mcp
This extension will append info to your gemini.md context using gemini-extension/GEMINI.md
Do you want to continue? [Y/n]: Y
Extension "cloud-run" installed successfully and enabled.

Se você executar o comando gemini extensions list, a extensão do Cloud Run vai aparecer instalada, como mostrado abaixo:

✓ cloud-run (1.0.0)
 Path: <HOME_FOLDER>/.gemini/extensions/cloud-run
 Source: https://github.com/GoogleCloudPlatform/cloud-run-mcp (Type: github-release)
 Release tag: v1.5.0
 Enabled (User): true
 Enabled (Workspace): true
 Context files:
  <HOME_FOLDER>/.gemini/extensions/cloud-run/gemini-extension/GEMINI.md
 MCP servers:
  cloud-run

Se você iniciar a CLI do Gemini agora e executar o comando /mcp, vai aparecer o seguinte:

Agora vamos voltar ao Cloud Shell e tentar implantar um aplicativo. Para isso, primeiro precisamos ter um aplicativo simples para implantar no Cloud Run. Siga estas etapas:

Verifique se você está na pasta que criamos antes, ou seja, gemini-cli-projects. Crie outra pasta dentro dela chamada gemini-cloud-run e navegue até ela.

mkdir gemini-cloud-run

cd gemini-cloud-run

Agora crie dois arquivos nessa pasta (app.py e requirements.txt), com o conteúdo abaixo:

app.py

from flask import Flask
app = Flask(__name__)
@app.route('/')
def hello_world():
  return 'Hello from Gemini and Cloud Run!'
if __name__ == "__main__":
  app.run(debug=True, host='0.0.0.0', port=8080)

requirements.txt

Flask
gunicorn

Agora inicie a CLI do Gemini na pasta gemini-cloud-run e, quando o terminal estiver pronto, envie o seguinte comando:

/deploy --project="PROJECT_ID" --location="PROJECT_LOCATION" --name="SERVICE_NAME"

Você precisará especificar o PROJECT_ID (ID do projeto do Google Cloud), o PROJECT_LOCATION e o SERVICE_NAME. Se você não fornecer isso, o comando do Cloud Run vai invocar as ferramentas adequadas para ajudar você a escolher.

Como parte do processo, ele vai selecionar a ferramenta certa na extensão do servidor MCP do Cloud Run que instalamos. Por exemplo, você vai ver uma mensagem como esta:

Conceda permissão para usar a ferramenta.

Pronto! A CLI do Gemini agora tem todas as informações necessárias e sua permissão para executar as ferramentas. Agora, ele vai executar todo o pipeline de implantação: criar a imagem do Docker, enviá-la para o Artifact Registry, configurar e implantar um novo serviço do Cloud Run.

Depois de alguns instantes (na verdade, 2 a 3 minutos), você vai ver uma mensagem de sucesso com um URL de serviço. Confira um exemplo de execução abaixo:

The Cloud Run service SERVICE_NAME has been deployed from the current folder in project PROJECT_ID.
  You can view the service in the Cloud Console: https://console.cloud.google.com/run/detail/PROJECT_LOCATION/SERVICE_NAME?project=PROJECT_ID
  The service is accessible at: https://SERVICE_NAME-SOME-ID.a.run.app

Clique no link. O app Flask vai exibir a página inicial:

Isso mostra o poder de uma extensão da CLI do Gemini (Cloud Run, neste caso), que encapsulou completamente a complexidade dos comandos gcloud CLI e simplesmente cuidou de todos os detalhes para você.

Conheça outras ferramentas no servidor MCP do Cloud Run.

6. A extensão do BigQuery (análise de grandes conjuntos de dados)

Para acompanhar, você vai precisar de:

• Projeto do Google Cloud com a API BigQuery ativada.
• Permissões do IAM:
• Usuário do BigQuery (roles/bigquery.user)

1. Execute este comando para definir a variável de ambiente BIGQUERY_PROJECT. É o projeto que vai executar os jobs do BigQuery, não necessariamente o projeto em que seus dados estão armazenados (embora possam ser o mesmo).

export BIGQUERY_PROJECT=<YOUR_GCP_PROJECT_ID>

2. Instale a extensão de análise de dados do BigQuery com o comando abaixo. Conceda permissão para instalar. Após a instalação, você terá duas extensões instaladas na sua configuração : cloud-run e bigquery-data-analytics.

gemini extensions install https://github.com/gemini-cli-extensions/bigquery-data-analytics

3. Vamos iniciar a CLI do Gemini novamente com o seguinte comando::

gemini

A CLI do Gemini vai ser iniciada no seu terminal:

Os comandos a seguir precisam ser inseridos no terminal da CLI do Gemini.

4. Confirme se a extensão do BigQuery está instalada e pronta para uso inserindo o comando de barra abaixo:

/extensions list

A extensão bigquery-data-analytics também vai aparecer na lista.

5. Execute o comando abaixo para conferir as ferramentas disponíveis

/mcp list

6. Vamos fazer uma pergunta básica de análise sobre o conjunto de dados público do BigQuery: o e-commerce de look. Esse conjunto de dados tem informações sobre clientes, produtos e pedidos de um site fictício de e-commerce de roupas. Insira este comando na CLI do Gemini:

Look at BigQuery's the look ecommerce public dataset. Identify the top 5 products that had the most orders.

• A CLI do Gemini vai perguntar se você quer permitir a execução das ferramentas do BigQuery. Para continuar, selecione a terceira opção: Yes, always allow all tools from server "bigquery_data_analytics".
• Nos bastidores, o Gemini vai gerar a consulta SQL apropriada, invocar a ferramenta execute_sql e retornar uma resposta em linguagem natural com seus dados:

7. Agora, vamos pedir ao Gemini para prever qual será a taxa de devolução de produtos com base em dados históricos. Para esse comando, a CLI do Gemini não deve tentar gerar um SQL detalhado para criar essa previsão. Ela precisa invocar a ferramenta forecast do servidor MCP, que usa o AI.Forecast do BigQuery nos bastidores:

Forecast what the return rate will be next month.

• Você vai receber uma resposta como esta:

7. Mais informações

Assim, concluímos nosso codelab, em que abordamos o que são as extensões da CLI do Gemini, os comandos básicos para trabalhar com elas e exploramos algumas extensões : cloud-run e bigquery-data-analytics.

Acesse a galeria de extensões do Gemini em https://geminicli.com/extensions/ para conhecer as extensões disponíveis no momento (mais de 100 no momento da redação) que você pode usar hoje. Cada card de extensões contém informações, o tipo de extensão (MCP, contexto etc.), o link do repositório do GitHub e um comando para instalar a extensão no seu ambiente.

8. Parabéns

Parabéns! Você entendeu as extensões da CLI do Gemini e como instalar e usar várias delas.

Documentos de referência

• Extensões da CLI do Gemini
• Galeria de extensões da CLI do Gemini