Como instalar uma extensão no Gemini CLI: passo a passo, escopo e o que fazer quando ela não aparece

Fala aí, beleza? Se tu usa o Gemini CLI no dia a dia, uma hora vai querer plugar coisa nova nele: um servidor MCP, uns comandos prontos, um contexto fixo pro projeto

O Gemini CLI faz isso com extensões: um pacote em pasta, com o manifesto gemini-extension.json, que pode trazer comandos TOML, servidores MCP e arquivo de contexto

Este guia vai da instalação até a confirmação na sessão, passando pelo escopo (global ou só no projeto) e pelo que fazer quando a extensão some. Tudo tirado da documentação oficial no repositório google-gemini/gemini-cli (pasta docs/extensions) e da referência em geminicli.com, consultadas em 19/10/2026 🙂

O que você precisa antes de instalar uma extensão

Você precisa de três coisas: o Gemini CLI instalado, o git na máquina e saber de onde vem a extensão

Se liga na lista:

• Gemini CLI instalado: ele é mantido pelo Google e sai pelo npm com o pacote @google/gemini-cli. Depois de instalado, tu inicia com o comando gemini
• Git instalado: obrigatório pra instalar extensão a partir do GitHub
• Origem da extensão: uma URL do GitHub, um caminho local na sua máquina ou algo que tu achou na galeria oficial de extensões

A instalação do CLI fica assim:

npm install -g @google/gemini-cli
gemini

Tome cuidado com o Trusted Folders!

Esse recurso vem desativado por padrão e precisa ser ligado nas configurações

Se ele estiver ativo e a pasta atual não for confiável, o CLI roda em safe mode: não dá pra instalar, atualizar nem desinstalar extensões, e os comandos .toml personalizados ficam desabilitados

O que uma extensão do Gemini CLI empacota

Uma extensão é um diretório com um arquivo de manifesto chamado gemini-extension.json e, opcionalmente, arquivos de contexto

Pensa assim: se tu conhece o package.json do NPM, o manifesto faz um papel parecido, ele diz o que o pacote é e o que ele traz pro agente

Os campos que importam pra quem vai instalar:

• name: identifica a extensão de forma única e serve pra resolver conflito. Só letras minúsculas ou números, com hífen no lugar de underscore ou espaço
• mcpServers: mapeia nomes de servidores MCP para as configurações deles. Esses servidores sobem na inicialização, junto com os que estão no seu settings.json
• contextFileName: um arquivo markdown (ou uma lista deles) com contexto carregado em TODA sessão. Se o campo não existir e houver um GEMINI.md, ele é usado por padrão
• excludeTools: uma lista de nomes de ferramentas a excluir
• settings: valores que a extensão pede na instalação, cada um com envVar (nome da variável de ambiente) e sensitive (se true, o valor vai pro keychain do sistema e aparece mascarado)

E os comandos?

Eles são arquivos TOML dentro da subpasta commands/, e o nome do comando sai da estrutura de pastas:

minha-extensao/
  gemini-extension.json
  GEMINI.md
  commands/
    deploy.toml      -> vira /deploy
    gcs/
      sync.toml      -> vira /gcs:sync

Subpasta vira namespace com dois pontos, por isso gcs/sync.toml vira /gcs:sync

Um manifesto mínimo ficaria parecido com isto (exemplo ilustrativo, só com campos documentados, não é uma extensão real):

{
  "name": "minha-extensao",
  "contextFileName": "GEMINI.md",
  "excludeTools": []
}

O formato interno de cada servidor em mcpServers e de cada item em settings fica de fora do exemplo, porque o que importa aqui é tu saber ler o manifesto antes de instalar

Passo a passo: instalar, configurar e confirmar a extensão

O caminho é: terminal fora da sessão, gemini extensions install, confirmar o aviso, preencher settings e reiniciar

Bora ver na prática?

1. Abra um terminal normal, fora do modo interativo

Os comandos gemini extensions ... rodam no shell, não dentro da conversa com o agente

Erro comum deste passo: tentar rodar gemini extensions install dentro da sessão interativa. Lá ele não funciona

2. Rode o install apontando pra origem

A sintaxe documentada é:

   gemini extensions install <source> [--ref <ref>] [--auto-update] [--pre-release] [--consent] [--skip-settings]

O <source> é a URL do GitHub ou um caminho local. O exemplo oficial instala a extensão do Workspace:

   gemini extensions install https://github.com/gemini-cli-extensions/workspace

Erro comum deste passo: instalar do GitHub sem git na máquina. Sem ele, a instalação a partir do GitHub não rola

3. Leia o aviso de risco e confirme

A instalação mostra um prompt de confirmação sobre riscos de segurança

Existe a flag --consent, que reconhece esse risco e pula o prompt. Ela é útil em script, mas com extensão que tu não conhece é pedir pra se ferrar: o aviso está ali justamente pra tu parar e pensar no que vai rodar na sua máquina

4. Preencha os settings que a extensão pedir

Se o manifesto declara settings, o CLI pergunta os valores na instalação. Os marcados como sensitive vão pro keychain do sistema e aparecem mascarados na interface

Pra ver ou mudar depois:

   gemini extensions config <name>

Depois do nome da extensão dá pra apontar um setting específico e usar --scope <scope>, se precisar

Se quiser pular essa etapa na hora do install, existe a --skip-settings

5. Use as flags opcionais só se precisar

– --ref: instala um git ref específico (branch, tag ou commit) – --auto-update: ativa a atualização automática – --pre-release: permite instalar versões pré-lançamento

6. Reinicie a sessão do Gemini CLI

Operações de gerenciamento de extensão só aparecem nas sessões ativas depois de reiniciar

Erro comum deste passo: deixar a sessão aberta desde antes do install e achar que a extensão não instalou. Ela instalou, a sessão é que não sabe ainda haha

7. Confirme que ela carregou

No terminal:

   gemini extensions list

Dentro da sessão interativa:

   /extensions list

Depois chame um comando da extensão pelo nome que vem da estrutura de pastas dela (tipo /deploy ou /gcs:sync no exemplo lá de cima). Se ele responder, tá tudo certo 😀

Escopo de usuário ou de projeto: onde a extensão vale

Por padrão a extensão vale em todo lugar: ela fica em ~/.gemini/extensions e é habilitada globalmente

Pra mudar isso, tu usa enable e disable com --scope, que aceita user ou workspace:

gemini extensions enable <name> --scope <user|workspace>
gemini extensions disable <name> --scope <user|workspace>

O exemplo oficial pra habilitar num workspace é:

gemini extensions enable extension-name --scope=workspace

Caso prático: tu quer a extensão só num projeto, e não em todos

1. Desative no escopo de usuário, pra ela parar de valer em todo lugar:

   gemini extensions disable extension-name --scope=user

2. Habilite só no workspace onde ela deve valer:

   gemini extensions enable extension-name --scope=workspace

3. Reinicie a sessão e confira com /extensions list

Outro detalhe: ao iniciar, o CLI carrega todas as extensões e mescla as configurações delas. Se der conflito, a configuração do workspace prevalece

Erro comum: esperar que o install já seja por projeto. Não é! A instalação vai pra ~/.gemini/extensions e o escopo se controla depois, no enable e no disable

E não confunda isso com o Gemini Code Assist das IDEs, que é outro produto. Se o teu problema é ele no editor, o caminho é desativar o Gemini Code Assist, não mexer em extensão do CLI

Como listar, atualizar e desinstalar extensões

Tudo pelo terminal, com gemini extensions + o subcomando

# lista as instaladas
gemini extensions list

# atualiza uma extensão
gemini extensions update <name>

# atualiza todas
gemini extensions update --all

# remove
gemini extensions uninstall <name>

Por que o update é tão importante?

Porque na instalação o Gemini CLI cria uma CÓPIA da extensão. Mudou alguma coisa na origem, seja pasta local ou GitHub? Só chega no CLI depois do update

Pra quem desenvolve a própria extensão, tem mais três:

# vincula uma extensão local pra desenvolvimento
gemini extensions link <path>

# cria uma extensão a partir de um template
gemini extensions new <path>

# valida a estrutura
gemini extensions validate <path>

E depois de qualquer uma dessas operações: reinicia a sessão, beleza?

Erro comum: editar a pasta de origem e esperar que o CLI pegue a mudança sozinho. Ele tá rodando a cópia, então roda o update

A extensão não aparece no Gemini CLI: como resolver

Na maioria das vezes é sessão não reiniciada ou escopo desabilitado

Bora ver os casos mais comuns, um por um

Não aparece em /extensions list?

Causa: a sessão já estava aberta quando tu instalou

Solução: fecha e abre o Gemini CLI de novo

Como prevenir: instala primeiro, abre a sessão depois

Instalou, mas está desabilitada?

Causa: a extensão foi desativada em user ou não foi habilitada no workspace atual

Solução: confere com gemini extensions list e ajusta com enable ou disable + --scope

Como prevenir: anota em qual escopo tu ligou cada extensão

O install não funciona dentro da sessão?

Causa: gemini extensions install não roda no modo interativo

Solução: sai da sessão e roda no terminal

Como prevenir: dentro da sessão, use só /extensions list pra conferir

A instalação pelo GitHub falha?

Causa: git não instalado

Solução: instala o git e roda o install de novo

Como prevenir: checa o git antes de qualquer install por URL

Não consigo instalar, atualizar nem remover?

Causa: Trusted Folders ativo e pasta não confiável, o que deixa o CLI em safe mode. Nesse modo os comandos .toml também ficam desabilitados

Solução: gerencia as extensões a partir de uma pasta confiável

Como prevenir: se tu ligou o Trusted Folders, marca como confiáveis as pastas onde tu realmente trabalha

O comando da extensão sumiu ou mudou de nome?

Causa: comando de extensão tem a menor precedência. Se existe um comando de usuário ou de projeto com o mesmo nome, o da extensão ganha o prefixo dela

Solução: procura por /<extensao>.<comando>, tipo /gcp.deploy pra uma extensão chamada gcp

Como prevenir: evita criar comandos próprios com o mesmo nome dos comandos das extensões

A extensão não enxerga uma variável de ambiente?

Causa: por segurança, variáveis sensíveis são filtradas e a extensão só acessa as declaradas no manifesto via settings/envVar (detalhe explicado no blog de desenvolvedores do Google)

Solução: confere quais settings ela declara e configura com gemini extensions config <name>

Como prevenir: lê a seção de settings do manifesto antes de instalar

Mudei a origem e nada mudou?

Causa: o CLI usa a cópia criada na instalação

Solução: gemini extensions update <name> e reinicia a sessão

Como prevenir: pra desenvolvimento, usa gemini extensions link <path>

Minha extensão própria não carrega?

Causa: estrutura ou manifesto com problema (por exemplo, um name fora do padrão de minúsculas, números e hífens)

Solução: roda gemini extensions validate <path>

Como prevenir: valida antes de cada install ou link

Cuidados de segurança antes de instalar uma extensão de terceiros

Antes do install, abre o gemini-extension.json do repositório e lê. Leva poucos minutos e mostra exatamente o que vai entrar no seu agente

Checklist rapidinho:

• Quais mcpServers ele sobe? Eles iniciam junto com o CLI, toda vez
• Quais comandos estão em commands/? Abre os .toml e vê o que cada um faz
• Que contexto ele injeta? Olha o contextFileName ou o GEMINI.md, porque isso entra em TODA sessão
• Quais settings e envVar ele pede? Só essas variáveis ficam acessíveis pra extensão, então se ela pede uma chave que não tem nada a ver com o que promete, desconfia
• Fixe a versão revisada: use --ref com a tag ou o commit que tu leu
• Segure o --auto-update e o --consent em código que tu não auditou, senão tu revisa uma versão e roda outra no futuro
• Considere ligar o Trusted Folders pra limitar onde o gerenciamento de extensões funciona
• Comece pela galeria oficial pra descobrir extensões, lembrando que estar lá não significa que alguém revisou o código por você

É o famoso "next, next e finish" que a gente precisa evitar aqui 😛

Vídeo: o Gemini CLI em projetos pesados

Se tu quer ver o Gemini CLI rodando em projeto de verdade, no canal tem um vídeo com ele encarando projetos pesados

Próximo passo: monte o seu primeiro escopo por projeto

Escolhe uma extensão na galeria, lê o manifesto dela com o checklist acima e instala pelo terminal

Depois desativa no escopo user, habilita só no workspace do projeto, reinicia e confere com /extensions list. Se ela aparecer ali e sumir nos outros projetos, tu dominou o escopo =)

até o próximo post!

Quer aprender mais sobre inteligência artificial e programação na prática? Conheça o canal Hora de Codar no YouTube e acompanhe os próximos vídeos.