Come cambiare la directory della CLI di Gemini

La Gemini CLI open source di Google—l'agente AI basato su terminale che porta Gemini nella tua shell—si è evoluta rapidamente dal lancio e ora supporta configurazioni avanzate, file di contesto di progetto (GEMINI.md / .gemini), comandi slash personalizzati e controlli delle directory dell'area di lavoro. Il progetto è in rapida evoluzione su GitHub (repository ufficiale), è entrato in anteprima pubblica con quote generose ed è in fase di integrazione con altri strumenti per sviluppatori (integrazioni per editor e CI/Actions). Ma quando i team crescono, o quando lavori tra unità o ambienti restrittivi (container, laptop gestiti dall'azienda, Cloud Shell, sistemi Windows), ti imbatterai rapidamente in una domanda pratica: dove archivia Gemini i suoi file e come puoi modificare le directory che Gemini legge e scrive?

Che cos'è Gemini CLI?

Gemini CLI è l'agente AI open source a riga di comando di Google che porta la potenza dei modelli Gemini direttamente nel tuo terminale. Offre funzionalità di agente interattivo per assistenza al codice, ispezione di file e progetti, esecuzione di comandi shell (con misure di sicurezza) e integrazione di strumenti come Google Search, estensioni Model Context Protocol (MCP) e strumenti di generazione di media forniti con Gemini. La CLI è pensata per essere leggera, scriptabile ed estensibile; è disponibile dal repository ufficiale e distribuita in pacchetti per un'installazione semplice.

Perché la directory è importante

Gemini CLI archivia la configurazione (per esempio settings.json), prompt di sistema o contesto (GEMINI.md), credenziali in cache, identificatori di telemetria e altri stati persistenti all'interno di una directory .gemini. La posizione di quella directory determina:

• quali impostazioni carica la CLI (globali vs. specifiche del progetto),
• quali file di “memoria” l'agente leggerà,
• dove vengono memorizzate in cache le credenziali (influisce sul comportamento di accesso),
• la riproducibilità tra macchine o in CI quando vuoi fornire un repository di configurazione personalizzato.

Comprendere e (se necessario) modificare la directory aiuta nei flussi di lavoro multi-progetto, in CI, nelle distribuzioni containerizzate e per i team con archivi di configurazione centralizzati.

Dove Gemini CLI archivia la configurazione per impostazione predefinita?

Per impostazione predefinita la CLI utilizza una directory .gemini. Nella maggior parte delle installazioni utente questo corrisponde a ~/.gemini (la cartella .gemini nella tua home). La CLI supporta anche file .gemini a livello di progetto (ad esempio .gemini/settings.json nella radice del progetto) che sovrascrivono le impostazioni utente quando operi da quella cartella di progetto. Le impostazioni a livello di sistema vengono lette da percorsi specifici del sistema operativo (per esempio /etc/ su Linux o %PROGRAMDATA% su Windows) quando applicabile. Percorsi tipici:

• Linux / macOS: ~/.gemini/ (per esempio /home/alice/.gemini oppure /Users/alice/.gemini).
• Windows: %USERPROFILE%\.gemini (ad esempio C:\Users\Alice\.gemini).
  All'interno di .gemini in genere troverai settings.json, GEMINI.md, commands/ e cache locali. La CLI legge anche le cartelle .gemini/ per progetto (radice del progetto) per le impostazioni a livello di progetto.

Questa impostazione predefinita è importante: storicamente la directory di configurazione è stata codificata come .gemini nella home

---

Come posso modificare o reindirizzare la directory di configurazione di Gemini CLI?

Esistono diversi metodi pratici — dal più semplice (lavorare nella cartella desiderata) al più robusto (variabili d'ambiente o reindirizzamenti del filesystem). Scegli l'approccio in base al controllo che hai sull'ambiente di esecuzione (macchina di sviluppo locale vs. CI), al sistema operativo in uso e al fatto che tu preferisca una modifica temporanea o permanente.

1) Usa una .gemini a livello di progetto (consigliato per impostazioni per progetto)

Se desideri impostazioni per progetto, crea una sottodirectory .gemini nella radice del tuo progetto e inserisci settings.json, GEMINI.md e altri file del progetto al suo interno. Gemini CLI privilegia le impostazioni del progetto quando la esegui da quella directory di progetto:

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

Avvia gemini mentre la tua shell si trova in your-project/ e la CLI rileverà i file .gemini da quell'albero (effettua una ricerca verso l'alto per trovare il contesto del progetto). Questo è il metodo più sicuro ed esplicito per la configurazione per progetto.

2) Usa le variabili d'ambiente documentate (quando supportate)

La base di codice e la documentazione di Gemini CLI fanno riferimento a diverse variabili d'ambiente utilizzate per modificare il comportamento. Alcune di queste sono pensate per impostazioni di sistema o per sostituire percorsi di file speciali:

• GEMINI_API_KEY, GEMINI_MODEL, ecc. sono comunemente usate per l'autenticazione e la scelta del modello.
• Nella codebase e nella documentazione ci sono riferimenti a variabili come GEMINI_CLI_SYSTEM_SETTINGS_PATH (usata per sostituire il percorso delle impostazioni di sistema) e a costanti come GEMINI_CONFIG_DIR (il nome .gemini predefinito usato nel codice). Alcune richieste della community e PR propongono di aggiungere o riconoscere una variabile d'ambiente GEMINI_CONFIG_DIR per consentire agli utenti di trasferire l'intera directory di configurazione.

Esempio (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

Avvertenza importante: dalle ultime discussioni e issue della community, GEMINI_CONFIG_DIR è stata richiesta e citata in alcune parti del codice — ma sono stati segnalati bug specifici per piattaforma e comportamenti incoerenti (in particolare su Windows). Ciò significa che il reindirizzamento basato su variabili d'ambiente potrebbe non essere uniformemente affidabile su tutte le piattaforme o release. Controlla le note di rilascio di Gemini CLI e le issue del repository per la versione installata se fai affidamento su questa funzione.

3) Aggiungi directory all'area di lavoro di Gemini all'interno di una sessione

Se vuoi che Gemini conosca directory aggiuntive (così può leggere file come contesto), esiste un set di comandi interattivi /directory. Per esempio:

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

Questo non sposta la directory di configurazione, ma consente all'agente di includere file da altre directory nel contesto della sua area di lavoro. È utile quando vuoi che l'agente faccia riferimento ad altri repository senza modificare la tua configurazione globale.

4) Crea un symlink o un bind del filesystem (soluzione pratica)

Su Unix/macOS:

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

Su Windows (prompt PowerShell amministrativo):

# 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

Questo approccio obbliga la CLI a leggere dalla posizione desiderata senza richiedere supporto nativo nella CLI. Nota: symlink/junction richiedono privilegi appropriati del filesystem e possono comportarsi diversamente in ambienti container o su Windows. Utilizzare con cautela. (Vedi “Note specifiche per Windows” sotto.)

5) Cambia la home effettiva per il processo (trucco per container/CI)

Quando esegui in CI, container o ambienti effimeri, puoi modificare la variabile d'ambiente $HOME (Unix) o %USERPROFILE% (Windows) per il processo gemini in modo che il suo ~/.gemini predefinito punti a un percorso sotto il tuo controllo:

# 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

Questo è utile per la riproducibilità in CI, ma fai attenzione: modificare HOME può influire su altri strumenti e sui flussi di autenticazione (ad esempio, cache di Google OAuth), quindi limita questa tecnica a container isolati o wrapper a livello di processo.

Come posso installare e usare Gemini CLI tramite CometAPI?

Risposta breve: hai due strade pratiche — (A) chiamare i modelli Gemini direttamente tramite CometAPI (consigliato e più semplice), oppure (B) far parlare la Gemini CLI ufficiale con CometAPI usando una release di Gemini CLI che supporti un URL di base personalizzato (alcune release/PR lo aggiungono), oppure eseguendo un piccolo proxy locale che traduce le richieste di Gemini CLI in chiamate in stile CometAPI/OpenAI.

Che cos'è CometAPI?

CometAPI è un'aggregazione/gateway di API che espone centinaia di modelli di terze parti (inclusa la famiglia Gemini di Google) dietro una API HTTP in stile OpenAI. Ti registri, ottieni una chiave API bearer, quindi chiami endpoint come https://api.cometapi.com/v1/chat/completions. CometAPI utilizza token bearer standard nell'header Authorization.

Perché usare CometAPI? Offre prezzi API inferiori rispetto all'API ufficiale per facilitare l'integrazione. Guida all'installazione e all'uso di Gemini CLI:

Come posso chiamare direttamente i modelli Gemini tramite CometAPI? (Consigliato)

Se il tuo obiettivo è semplicemente usare i modelli Gemini e non hai strettamente bisogno delle funzionalità di Gemini CLI, chiamare direttamente CometAPI è semplice e affidabile.

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 .

Queste chiamate dirette ti consentono di integrare CometAPI in script, app o CI senza fare affidamento su Gemini CLI.

Posso fare in modo che Gemini CLI utilizzi CometAPI?

Alcune versioni/PR di Gemini CLI aggiungono variabili d'ambiente per sostituire l'URL di base dell'API di Gemini. Se la tua installazione di gemini supporta la configurazione di un URL di base personalizzato per Gemini e l'uso della chiave CometAPI, puoi indirizzarla a CometAPI e impostare la chiave CometAPI come GEMINI_API_KEY (la CLI si aspetta una variabile chiave denominata GEMINI_API_KEY per l'autenticazione della chiave dell'API di Gemini).

Esempio:

# 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

Risoluzione problemi: problemi comuni e soluzioni

Problema: Gemini non riesce a vedere i file in un altro repository

1. Prova gemini --include-directories /path/to/repo all'avvio. Oppure in sessione: /directory add /path/to/repo.
2. Se il repository è su un mount di rete, verifica i permessi e che l'utente del processo della CLI possa leggere i file.
3. Se hai usato un symlink per spostare .gemini, verifica che la CLI segua il symlink per GEMINI.md e settings.json (alcune versioni non seguono determinati symlink per motivi di sicurezza).

Problema: gemini non riesce a creare ~/.gemini su Windows (EPERM)

Di solito significa che il tuo processo non ha i permessi per scrivere in %USERPROFILE%. Soluzioni:

• Esegui il terminale come Amministratore oppure regola i permessi della cartella.
• Imposta una posizione di configurazione personalizzata tramite symlink o, quando supportato, tramite variabile d'ambiente (attendi il supporto futuro per GEMINI_CONFIG_DIR).

Problema: cd non cambia la directory di lavoro all'interno della modalità shell

Si tratta di un problema noto su alcune piattaforme. Consigliato: eseguire i comandi della shell al di fuori del processo della Gemini CLI oppure aggiungere directory tramite /directory add.

Problema: i nomi dei modelli CometAPI non corrispondono a quanto ti aspetti

Chiama l'endpoint /v1/models e ispeziona il JSON. Gli ID dei modelli spesso contengono stringhe di variante esatte (ad esempio gemini-2.5-flash-preview-04-17). Usa la stringa esatta nella tua richiesta.

Conclusione

Il design predefinito di Gemini CLI favorisce un comportamento sensato e prevedibile: una ~/.gemini globale per i valori predefiniti a livello utente e una .gemini a livello di progetto per le sostituzioni per repository. La community sta spingendo per una configurabilità più nativa (variabili d'ambiente o flag espliciti) per rendere lo strumento più adatto a ambienti multiutente, containerizzati e aziendali.

Come cambiare la directory di Gemini CLI:

Panoramica: Gemini CLI archivia configurazione e file di contesto a livello utente in una directory .gemini (tipicamente ~/.gemini). Puoi influenzare quale directory utilizza la CLI (1) facendo affidamento su .gemini a livello di progetto nella directory di lavoro corrente, (2) usando variabili d'ambiente o opzioni della CLI quando supportate, (3) aggiungendo directory di workspace all'interno di una sessione interattiva oppure (4) ricorrendo a tecniche del filesystem (symlink, bind mount o modifica delle variabili di home/profilo) quando mancano opzioni native.

Per iniziare, esplora le funzionalità dei modelli Gemini (come Gemini 3 Pro) nel Playground e consulta la guida API per istruzioni dettagliate. Prima di accedere, assicurati di aver effettuato l'accesso a CometAPI e di aver ottenuto la chiave API. CometAPI offre un prezzo molto inferiore rispetto a quello ufficiale per agevolare l'integrazione.

Pronto a iniziare? → Prova gratuita dei modelli Gemini !