Gemini CLI: una guida con esempi pratici

Ora vediamo come ho utilizzato Gemini CLI per esplorare, correggere problemi e implementare modifiche in un progetto open source.

Passo 1: Prerequisiti

Per iniziare, installa Node.js (versione 18 o superiore). Puoi anche scaricare l’installer che preferisci qui, oppure eseguire i seguenti comandi bash nel terminale:

# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
# in lieu of restarting the shell
\. "$HOME/.nvm/nvm.sh"
# Download and install Node.js:
nvm install 22
# Verify the Node.js version:
node -v # Should print "v22.17.0".
nvm current # Should print "v22.17.0".
# Verify npm version:
npm -v # Should print "10.9.2".

Per configurare l’ambiente per Gemini CLI:

• Installa NVM (Node Version Manager) eseguendo lo script di installazione ufficiale
• Poi inizializzalo nella sessione di terminale corrente usando source
• Infine, usa NVM per installare Node.js v22 e verifica l’installazione con i comandi node -v, nvm current e npm -v

Questa configurazione assicura che il tuo sistema sia pronto a eseguire Gemini CLI senza problemi.

Passo 2: Configurare Gemini CLI 

Ora che abbiamo i prerequisiti, possiamo configurare Gemini CLI sul nostro sistema.

Passo 2.1: Installa Gemini CLI

Una volta installati e verificati Node.js e npm, installa Gemini CLI eseguendo il seguente comando nel terminale:

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

Oppure usa npm per eseguirla:

npm install -g @google/gemini-cli
gemini

Dopo l’installazione di gemini-cli, digita gemini nel terminale per accedervi.

Passo 2.2: Autenticazione

Puoi usare il tuo account Google personale per autenticarti quando richiesto. Questo ti garantirà fino a 60 richieste al minuto e 1.000 richieste al giorno ai modelli Gemini.

Accesso con Google è l’opzione che ho usato in questo tutorial, ma puoi anche usare la chiave API (impostata come variabile d’ambiente) o Vertex AI per l’autenticazione. Per generare una nuova chiave API, accedi a AI Studio con il tuo account Google e fai clic su Create API key. Puoi anche usare una chiave esistente da un progetto Google Cloud per accedere a modelli specifici o richiedere limiti di utilizzo più alti.

export GEMINI_API_KEY=”Your_API_Key”

Oppure crea un file .env

GEMINI_API_KEY=”Your_API_Key”

Puoi usare /auth nella casella di testo per cambiare l’autenticazione quando necessario.

Una volta autenticato, troverai una casella di testo per interagire gratuitamente con la CLI direttamente dal terminale.

Passo 3: Configurare un progetto su Gemini CLI

Quando la CLI è in esecuzione, possiamo iniziare a interagire con Gemini dal terminale. Ci sono due modi per lavorare a un progetto con la CLI.

1. Avviare un nuovo progetto

Per avviare un progetto da zero, esegui i seguenti comandi:

cd new-project/
gemini

All’interno della CLI, usa un prompt per risolvere un problema che ti interessa, ad esempio:

> Write the encoder code for a transformer from scratch.

Questo comando creerà una nuova directory di progetto e inizializzerà Gemini nel terminale. Poi potrai chiedere a Gemini di popolare la nuova directory con il codice.

2. Lavorare con un progetto esistente

Se hai già una codebase esistente, puoi lavorarci con i seguenti comandi:

git clone https://github.com/AashiDutt/Google-Agent-Development-Kit-Demo
cd Google-Agent-Development-Kit-Demo
gemini

All’interno della CLI, usa un prompt come:

> Give me a summary of all of the changes made to the codebase today.

Se lavori con una codebase esistente, clonata da GitHub o già presente in locale, puoi eseguire Gemini CLI all’interno della directory del progetto.

In alternativa, dopo aver avviato Gemini, puoi inserire il percorso completo della directory del codice nella casella di testo del prompt usando il comando /path per caricare manualmente il progetto locale.

Passo 4: Sperimentare con la Gemini CLI

In questo tutorial lavoreremo con un progetto esistente che ho usato per scrivere un tutorial sul Google Agent Development Kit (ADK). Il repository è ospitato su GitHub. Con Gemini CLI faremo:

1. Esplorazione e comprensione della codebase
2. Individuazione di un bug o di un problema su GitHub o in un file
3. Refactoring del codice e generazione di unit test
4. Creazione di un report in markdown delle modifiche apportate
5. Visualizzazione della codebase generando un flowchart o un diagramma

Esplorare e comprendere la codebase

Cominciamo chiedendo a Gemini di esplorare e spiegare la codebase.

Prompt: Esplora la directory corrente e descrivi l’architettura del progetto.

Gemini CLI ha restituito un riepilogo strutturato, spiegando come:

• agents/ contiene le implementazioni dei singoli agenti
• shared/ definisce gli schemi comuni usati da tutti gli agenti
• common/ include funzioni utility A2A riutilizzabili per la messaggistica tra agenti

Questo mi ha aiutato a orientarmi senza leggere manualmente ogni file.

Analizzare e correggere una issue su GitHub

Esploriamo alcune issue aperte dal repository GitHub. Puoi usare lo strumento /compress per comprimere il contesto sostituendolo con un riepilogo. Questo ci aiuta a far passare più informazioni in un contesto di lunghezza limitata.

Nota: Gemini chiederà conferma prima di accedere al repository GitHub. In questo caso, il repo è open source.

Prompt: Ecco una issue di GitHub: [@search https://github.com/AashiDutt/Google-Agent-Development-Kit-Demo/issues/1]. Analizza la codebase e suggerisci un piano di correzione in 3 passaggi. Quali file/funzioni dovrei modificare?

Gemini CLI ha analizzato la issue:

• Usando la funzionalità @search, e ha restituito un piano di correzione in 3 passaggi per la issue su GitHub.
• Ha poi individuato la causa principale in un errore di serializzazione JSON.
• Infine, Gemini ha suggerito modifiche e gestione delle risposte in alcuni file.

Successivamente, la CLI attende l’input dell’utente per valutare le modifiche e, se l’utente acconsente, applicherà le modifiche suggerite. Scegli l’opzione per applicare le modifiche suggerite premendo Invio.

La CLI applica modifiche a ogni file interessato. Una volta completate, restituirà un riepilogo delle modifiche effettuate.

Implementare e testare la correzione

Implementiamo e testiamo le correzioni suggerite da Gemini. Per questo, ho usato il seguente prompt e consentito l’esecuzione.

Prompt: Scrivi un unit test pytest per questa modifica in test_shared.py.

Gemini CLI:

• Ha inserito json.dumps() prima di inviare i payload dei task nei file suggeriti in precedenza.
• Poi ha creato test_agents.py se mancava, per aggiungere unit test.
• Infine, ha aggiunto un nuovo caso di test per validare lo schema e la trasmissione di messaggi annidati tra agenti.

La CLI genera il file test_agents.py e lo esegue usando più script di shell. Tuttavia, a un certo punto Gemini è entrato in un loop ripetendo lo stesso errore. Un prompt affinato, un nuovo tentativo o semplicemente l’uso di un modello diverso tramite API possono risolvere il problema.

Ecco il nuovo file generato da Gemini nella cartella del progetto:

Generare documentazione

Ora che abbiamo effettuato le correzioni, riassumiamo le modifiche apportate e scriviamole in Markdown in un file .txt.

Per questo ho usato il seguente prompt:

Prompt: Scrivi un riepilogo in markdown del bug, della correzione e della copertura dei test. Formattalo come una voce di changelog sotto "v0.2.0".

Per salvare il riepilogo in un documento, ho usato il seguente prompt:

Prompt: Salva questo riepilogo in un file .txt e chiamalo summary.txt

Gemini CLI usa lo strumento WriteFile per salvare il file summary.txt nella directory del progetto.

Ecco il file summary.txt generato da Gemini per questo progetto:

Generare un flowchart con MCP

Questa sezione estende gli esperimenti precedenti, in cui esploro come Gemini CLI usa il Model Context Protocol (MCP) per mantenere riepiloghi a livello di file e cronologia dei task tra i prompt. Questo dà a Gemini una memoria di lavoro all’interno della sessione. Sfruttando questa capacità di Gemini, ho chiesto di generare un flowchart del progetto e convertirlo in un’immagine. 

Ecco il prompt che ho usato:

Prompt: Genera un flowchart che mostri come gli agenti comunicano via A2A e come main.py orchestra il sistema. Evidenzia dove si è verificato il problema e come è stato risolto.

Questa visualizzazione è resa possibile dalla memoria persistente di Gemini, che ha mantenuto il contesto completo della nostra precedente correzione del bug e della struttura degli agenti senza bisogno di ricaricare o fornire suggerimenti sui file.

Sebbene gli strumenti di generazione di immagini non fossero direttamente disponibili nella CLI (potrebbero essere accessibili via API), questa visualizzazione si è rivelata utile per comprendere l’instradamento degli agenti. 

Strumenti disponibili in Gemini CLI 

Alcuni strumenti supportati da Gemini CLI includono:

• ReadFile, WriteFile, Edit
• FindFiles, ReadFolder, ReadManyFiles
• Shell, SaveMemory
• GoogleSearch o Search, WebFetch

Questi strumenti ti aiutano a navigare, interrogare e modificare in modo efficiente codebase di grandi dimensioni.

Per saperne di più su Gemini CLI, ti consiglio di leggere la documentazione ufficiale e la pagina GitHub.

Conclusione

In sintesi, questo tutorial ha mostrato come usare Gemini CLI per:

• Comprendere la struttura di una codebase multi-agente
• Correggere una issue su GitHub
• Generare unit test e documentazione in markdown per le modifiche.
• Visualizzare il flusso dei dati

Gemini CLI ha ridotto il tempo che normalmente passerei a esaminare i file e pianificare manualmente le correzioni. Sebbene sia ancora nelle fasi iniziali e talvolta possa sembrare lento se usato via API, sta già raggiungendo le capacità di Claude Code.

Se sei uno sviluppatore e vuoi aggiungere agenti AI al tuo workflow, dai un’occhiata a questa serie di tutorial in quattro parti su Devin:

1. Setup e prima Pull Request (Parte 1)
2. Rilasciare una vertical slice con Devin (Parte 2) 
3. Integrazioni, test e CI/CD (Parte 3) 
4. Sicurezza, deployment, manutenzione (Parte 4)