Como alterar o diretório do gemini cli

O Gemini CLI de código aberto do Google — o agente de IA baseado em terminal que leva o Gemini ao seu shell — amadureceu rapidamente desde o lançamento e agora oferece configuração avançada, arquivos de contexto de projeto (GEMINI.md / .gemini), comandos de barra personalizados e controles de diretório de workspace. O projeto está evoluindo ativamente no GitHub (repositório oficial), entrou em prévia pública com cotas generosas e está sendo integrado a outras ferramentas de desenvolvedor (integrações com editor e CI/Actions). Mas, à medida que as equipes crescem, ou quando você trabalha entre drives ou em ambientes restritivos (containers, laptops gerenciados pela empresa, Cloud Shell, sistemas Windows), você rapidamente se depara com uma questão prática: onde o Gemini armazena seus arquivos e como alterar os diretórios dos quais o Gemini lê e para os quais escreve?

O que é o Gemini CLI?

O Gemini CLI é o agente de IA de linha de comando de código aberto do Google que traz o poder dos modelos Gemini diretamente para o seu terminal. Ele oferece capacidades de agente interativo para assistência em código, inspeção de arquivos e projetos, execução de comandos de shell (com salvaguardas) e integração de ferramentas como Google Search, extensões Model Context Protocol (MCP) e ferramentas de geração de mídia fornecidas com o Gemini. O CLI foi projetado para ser leve, scriptável e extensível; está disponível no repositório oficial e empacotado para instalação fácil. 

Por que o diretório importa

O Gemini CLI armazena configuração (por exemplo, settings.json), prompts do sistema ou contexto (GEMINI.md), credenciais em cache, identificadores de telemetria e outros estados persistentes dentro de um diretório .gemini. Onde esse diretório fica controla:

• quais configurações o CLI carrega (globais vs. específicas do projeto),
• quais arquivos de “memória” o agente vai ler,
• onde as credenciais são armazenadas em cache (afeta o comportamento de login),
• reprodutibilidade entre máquinas ou em CI quando você quer fornecer um repositório de configuração personalizado.

Entender e (se necessário) alterar o diretório ajuda em fluxos de trabalho multi-projeto, CI, implantações em containers e equipes com repositórios centralizados de configuração. 

Onde o Gemini CLI armazena a configuração por padrão?

Por padrão, o CLI usa um diretório .gemini. Para a maioria das instalações de usuário, isso resolve para ~/.gemini (a pasta .gemini no seu diretório home). O CLI também suporta arquivos .gemini em nível de projeto (por exemplo, .gemini/settings.json na raiz do projeto), que substituem as configurações do usuário enquanto você opera a partir daquela pasta de projeto. Configurações em nível de sistema são lidas de locais específicos do SO (por exemplo, /etc/ no Linux ou %PROGRAMDATA% no Windows) quando aplicável. Caminhos típicos:

• Linux / macOS: ~/.gemini/ (por exemplo, /home/alice/.gemini ou /Users/alice/.gemini).
• Windows: %USERPROFILE%\.gemini (por exemplo, C:\Users\Alice\.gemini).
  Dentro de .gemini, você normalmente encontrará settings.json, GEMINI.md, commands/ e caches locais. O CLI também lê pastas .gemini/ por projeto (raiz do projeto) para configurações em nível de projeto. 

Esse padrão é importante: historicamente, o diretório de configuração foi codificado como .gemini no diretório home

---

Como alterar ou redirecionar o diretório de configuração do Gemini CLI?

Há várias maneiras práticas — da mais simples (trabalhar na pasta desejada) à mais robusta (variáveis de ambiente ou redirecionamentos de filesystem). Escolha uma abordagem dependendo de você controlar o ambiente de runtime (máquina de desenvolvimento local vs. CI), do sistema operacional, e se você prefere uma alteração temporária ou permanente.

1) Use um .gemini em nível de projeto (recomendado para configurações por projeto)

Se você quer configurações por projeto, crie um subdiretório .gemini na raiz do seu projeto e coloque settings.json, GEMINI.md e outros arquivos do projeto lá. O Gemini CLI prefere configurações do projeto quando você o executa a partir desse diretório:

your-project/├─ .gemini/│  ├─ settings.json│  └─ GEMINI.md└─ src/

Inicie gemini enquanto seu shell estiver em your-project/ e o CLI detectará os arquivos .gemini a partir dessa árvore (ele busca para cima para encontrar contexto de projeto). Esse é o método mais seguro e explícito para configuração por projeto. 

2) Use variáveis de ambiente documentadas (quando suportado)

A base de código e a documentação do Gemini CLI referenciam várias variáveis de ambiente usadas para alterar o comportamento. Algumas são destinadas a configurações de sistema ou substituições específicas de arquivos:

• GEMINI_API_KEY, GEMINI_MODEL, etc. são comumente usadas para autenticação e escolha do modelo.
• Há referências no código e na documentação para variáveis como GEMINI_CLI_SYSTEM_SETTINGS_PATH (usada para substituir o caminho de configurações do sistema) e constantes como GEMINI_CONFIG_DIR (o nome padrão .gemini usado no código). Algumas solicitações da comunidade e PRs propõem adicionar ou respeitar uma variável de ambiente GEMINI_CONFIG_DIR para permitir relocação de todo o diretório de configuração. 

Exemplo (bash / macOS / Linux):

# Temporary for this shell sessionexport GEMINI_CONFIG_DIR="$HOME/custom_gemini_dir"​# Or override system settings path if your install supports it:export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/my-gemini/system.settings.json"​# Then rungemini

PowerShell (Windows):

$env:GEMINI_CONFIG_DIR = 'C:\Users\you\CustomGemini'gemini

Observação importante: conforme discussões e issues recentes da comunidade, GEMINI_CONFIG_DIR tem sido solicitado e referenciado no código em alguns pontos — mas foram relatados bugs específicos de plataforma e comportamento inconsistente (particularmente no Windows). Isso significa que redirecionamentos baseados em variáveis de ambiente podem não ser uniformemente confiáveis em todas as plataformas ou releases. Verifique as notas de release do Gemini CLI e issues do repositório para sua versão instalada se você depender disso. 

3) Adicione diretórios ao workspace do Gemini dentro de uma sessão

Se você quer que o Gemini reconheça diretórios adicionais (para que ele possa ler arquivos como contexto), há um conjunto de comandos interativos /directory. Por exemplo:

/directory add path/to/another/project/directory list

Isso não move o diretório de configuração, mas permite que o agente inclua arquivos de outros diretórios no seu workspace. É útil quando você quer que o agente referencie outros repositórios sem alterar sua configuração global. 

4) Crie um symlink ou bind de filesystem (solução prática)

Se o CLI se recusar a aceitar substituições por variável de ambiente ou se você precisar de uma solução confiável entre processos, use um redirecionamento de filesystem:

Em Unix/macOS:

# move the original config foldermv ~/.gemini ~/gemini_backup​# create a symlink to your desired locationln -s /path/to/central/gemini-config ~/.gemini

No Windows (prompt administrativo do PowerShell):

# Move the original directoryMove-Item -Path $env:USERPROFILE\.gemini -Destination C:\GeminiConfigBackup​# Create a junction (administrator)New-Item -ItemType Junction -Path $env:USERPROFILE\.gemini -Target C:\CentralGeminiConfig

Essa abordagem força o CLI a ler do local desejado sem exigir suporte nativo no CLI. Observação: symlinks/junctions exigem privilégios apropriados de filesystem e podem se comportar de maneira diferente em ambientes de container ou Windows. Use com cuidado. (Veja as “observações específicas do Windows” abaixo.)

5) Altere o diretório home efetivo do processo (truque para container/CI)

Ao executar em CI, containers ou ambientes efêmeros, você pode alterar a variável $HOME (Unix) ou %USERPROFILE% (Windows) para o processo gemini, de modo que seu ~/.gemini padrão resolva para um caminho que você controla:

# Run gemini with a custom HOME (bash)HOME=/ci/workspace/you gemini --some-command​# Or in a container DockerfileENV HOME=/app/userRUN mkdir -p /app/user/.geminiCOPY config /app/user/.gemini

Isso é útil para reprodutibilidade em CI, mas atenção: alterar HOME pode afetar outras ferramentas e fluxos de autenticação (por exemplo, caches de OAuth do Google), então restrinja essa técnica a containers isolados ou wrappers em nível de processo.

Como instalar e usar o Gemini CLI via CometAPI?

Resposta curta: você tem dois caminhos práticos — (A) chamar modelos Gemini diretamente pela CometAPI (recomendado e mais simples), ou (B) fazer o Gemini CLI oficial conversar com a CometAPI usando uma versão do Gemini-CLI que suporte uma base URL personalizada (alguns releases/PRs adicionam isso), ou executando um pequeno proxy local que traduza requisições do Gemini-CLI para chamadas no estilo CometAPI/OpenAI. 

O que é CometAPI?

CometAPI é um gateway/agregador de API que expõe centenas de modelos de terceiros (incluindo a família Gemini do Google) por trás de uma API HTTP no estilo OpenAI. Você se cadastra, obtém uma chave de API bearer e então chama endpoints como https://api.cometapi.com/v1/chat/completions. A CometAPI usa tokens bearer padrão no cabeçalho Authorization.

Por que usar a CometAPI? Ela oferece preços de API mais baixos do que a API oficial para facilitar a integração. Guia de instalação e uso do Gemini CLI:

Como chamar modelos Gemini diretamente via CometAPI? (Recomendado)

Se seu objetivo é simplesmente usar modelos Gemini e você não precisa estritamente dos recursos do Gemini CLI, chamar diretamente a CometAPI é simples e confiável.

export COMET_KEY="sk-xxxx"​curl -s -X POST "https://api.cometapi.com/v1/chat/completions" \  -H "Authorization: Bearer $COMET_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "gemini-2.5-pro",    "messages": [      {"role": "system", "content": "You are a helpful assistant."},      {"role": "user", "content": "Summarize the 3 key benefits of unit tests."}    ],    "max_tokens": 300  }' | jq .

Essas chamadas diretas permitem integrar a CometAPI em scripts, apps ou CI sem depender do Gemini CLI.

Posso fazer o Gemini CLI usar a CometAPI?

Algumas versões/PRs do Gemini CLI adicionam variáveis de ambiente para substituir a base URL da API do Gemini. Se seu gemini instalado suportar configurar uma base URL personalizada do Gemini + usar a chave da CometAPI, você pode apontá-lo para a CometAPI e definir a chave da CometAPI como GEMINI_API_KEY (o CLI espera uma variável de chave chamada GEMINI_API_KEY para autenticação da API do Gemini).

Exemplo:

# example env — *check your gemini-cli docs for exact var names*export GEMINI_API_KEY="sk-xxxxx"                    # CometAPI keyexport GOOGLE_GEMINI_BASE_URL="https://api.cometapi.com/v1"  # if supportedgemini   # run the CLI; it will use the configured base URL

Solução de problemas: problemas comuns e correções

Problema: o Gemini não consegue ver arquivos em outro repositório

1. Tente gemini --include-directories /path/to/repo ao iniciar. Ou, em sessão: /directory add /path/to/repo. 
2. Se o repositório estiver em um compartilhamento de rede, verifique permissões e se o usuário do processo do CLI pode ler os arquivos.
3. Se você usou um symlink para mover o .gemini, verifique se o CLI segue o symlink para GEMINI.md e settings.json (algumas versões não seguem certos symlinks por segurança). 

Problema: gemini falha ao criar ~/.gemini no Windows (EPERM)

Isso geralmente significa que seu processo não tem permissão para gravar em %USERPROFILE%. Correções:

• Execute o terminal como Administrador ou ajuste as permissões da pasta.
• Defina um local de configuração personalizado via symlink ou, quando suportado, via variável de ambiente (acompanhe o suporte futuro a GEMINI_CONFIG_DIR). 

Problema: cd não altera o diretório de trabalho dentro do modo shell

Este é um issue reconhecido em algumas plataformas. Recomendação: execute comandos de shell fora do processo do Gemini CLI ou adicione diretórios via /directory add.

Problema: os nomes dos modelos da CometAPI não correspondem ao esperado

Chame o endpoint /v1/models e inspecione o JSON. IDs de modelos frequentemente contêm strings de variantes exatas (por exemplo, gemini-2.5-flash-preview-04-17). Use a string exata na sua requisição.

Conclusão

O design padrão do Gemini CLI favorece um comportamento sensato e fácil de descobrir: um ~/.gemini global para padrões em nível de usuário e um .gemini no projeto para substituições por repositório. A comunidade vem pressionando por mais configurabilidade nativa (variáveis de ambiente explícitas ou flags) para tornar a ferramenta mais amigável em ambientes multiusuário, containerizados e empresariais.

Como alterar o diretório do Gemini CLI: 

Visão geral: o Gemini CLI armazena configuração e arquivos de contexto em nível de usuário em um diretório .gemini (tipicamente ~/.gemini). Você pode influenciar qual diretório o CLI utiliza por meio de (1) um .gemini em nível de projeto no diretório de trabalho atual, (2) variáveis de ambiente ou opções do CLI quando suportadas, (3) adição de diretórios de workspace dentro de uma sessão interativa ou (4) técnicas de filesystem (symlinks, bind mounts ou alteração das variáveis home/profile) quando opções nativas estiverem ausentes.

Para começar, explore as capacidades dos modelos Gemini (como Gemini 3 Pro) no Playground e consulte o guia da API para instruções detalhadas. Antes de acessar, certifique-se de ter feito login na CometAPI e obtido a chave de API. A CometAPI oferece um preço muito inferior ao oficial para ajudar na integração.

Pronto para começar?→ Teste gratuito dos modelos Gemini !