Questa pagina è stata tradotta dall'API Cloud Translation.

Prova pratica dell'interfaccia a riga di comando Gemini

1. Introduzione

In questo codelab, imparerai a utilizzare Gemini CLI, un agente AI open source che porta la potenza di Gemini direttamente nel tuo terminale.

Il progetto Gemini CLI è open source e puoi visualizzare la roadmap pubblica qui.

Cosa imparerai a fare

Installazione e configurazione dell'interfaccia a riga di comando Gemini
Esplorare strumenti, comandi integrati e configurare i server MCP in Gemini CLI
Personalizzazione dell'interfaccia a riga di comando di Gemini tramite il file GEMINI.md
Esplorare alcuni casi d'uso con l'interfaccia a riga di comando di Gemini

Che cosa ti serve

Questo codelab può essere eseguito interamente in Google Cloud Shell, in cui è preinstallata la CLI Gemini.

In alternativa, se preferisci lavorare sulla tua macchina, c'è una sezione per installare Gemini CLI in locale.

Ti serviranno:

Browser web Chrome
Un account Gmail

Questo codelab è pensato per utenti e sviluppatori di tutti i livelli (inclusi i principianti). I casi d'uso nel codelab sono stati suddivisi in attività per sviluppatori e non sviluppatori. I casi d'uso per gli sviluppatori mostrano come vibrare il codice con la CLI Gemini e come lavorare con un repository GitHub per eseguire attività di sviluppo comuni come la spiegazione/comprensione del codice, la generazione di documentazione, la risoluzione di problemi e altro ancora. Ti consigliamo di completare questi casi d'uso nel codelab. Alla fine è presente una sezione facoltativa che copre diverse attività quotidiane non incentrate sugli sviluppatori.

2. Prima di iniziare

Crea un progetto

Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione in Google Cloud precaricato con bq. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.

Immagine del pulsante Attiva Cloud Shell

Una volta eseguita la connessione a Cloud Shell, verifica di essere già autenticato e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:

gcloud auth list

Esegui questo comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.

gcloud config list project

Se il progetto non è impostato, utilizza il seguente comando per impostarlo:

gcloud config set project <YOUR_PROJECT_ID>

3. Installazione

Prima di eseguire la configurazione ed eseguire Gemini CLI, creiamo una cartella che utilizzerai come cartella principale per tutti i progetti che potresti creare al suo interno. Questo è un punto di partenza per l'utilizzo della CLI Gemini, anche se farà riferimento anche ad altre cartelle del sistema, che verranno utilizzate in un secondo momento, se necessario.

Crea una cartella di esempio (gemini-cli-projects) e vai alla cartella tramite i comandi mostrati di seguito. Se preferisci utilizzare un altro nome per la cartella, fallo pure.

mkdir gemini-cli-projects

Andiamo alla cartella:

cd gemini-cli-projects

Puoi avviare direttamente Gemini CLI tramite il comando gemini.

Vai direttamente alla sezione successiva (configurazione di Gemini CLI tramite settings.json).

Se vuoi installare Gemini CLI in locale, segui le istruzioni riportate di seguito.

Il primo passaggio consiste nell'installare Node 20+ sul tuo computer. Una volta completata questa operazione, puoi installare ed eseguire Gemini CLI utilizzando uno dei seguenti metodi:

Puoi installare prima l'interfaccia a riga di comando di Gemini a livello globale sul tuo sistema. Per eseguire questo passaggio, potresti aver bisogno dell'accesso amministrativo.

# option 1: install Gemini CLI

npm install -g @google/gemini-cli

# .. and then run
gemini

Esegui il comando seguente:

# option 2: run without installing Gemini CLI

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

Per verificare che la CLI sia installata, esegui:

gemini --version

Supponendo che tu abbia avviato Gemini CLI con uno dei metodi sopra indicati, dovresti visualizzare la seguente schermata che ti chiede di scegliere un tema. Procedi e seleziona quello che preferisci:

Una volta selezionato, ti verrà chiesto il metodo di autenticazione. In questo lab ti consigliamo di utilizzare il tuo Account Google personale e non account non Google o correlati a Google Workspace. Questa licenza senza costi ti consente di accedere a Gemini 2.5 Pro e alla sua finestra contestuale da 1 milione di token. Il livello senza costi consente 60 richieste di modello al minuto e 1000 richieste al giorno senza costi.

Se raggiungi i limiti con la quota senza costi attuale assegnata agli Account Google, puoi scegliere di utilizzare la chiave API Gemini o anche Google Cloud Vertex AI, dove dovrai disporre di un ID progetto e del nome della località per quel progetto. Se prevedi di utilizzare altri metodi di autenticazione, consulta la sezione Autenticazione della documentazione.

Procedi e fai clic su Invio. Si aprirà una pagina di autenticazione di Google nel browser. Procedi con l'autenticazione con il tuo Account Google, accetta i termini e, una volta autenticato correttamente, noterai che la CLI Gemini è pronta e in attesa del tuo comando. Di seguito è riportato uno screenshot di esempio:

4. Configurazione dell'interfaccia a riga di comando di Gemini tramite settings.json

Se scegli Cloud Shell per eseguire Gemini, il tema predefinito per Gemini CLI e il metodo di autenticazione sono già selezionati e configurati.

Se hai installato Gemini CLI sul tuo computer e l'hai avviata per la prima volta, hai selezionato un tema e poi un metodo di autenticazione.

Ora, nelle esecuzioni successive dell'interfaccia a riga di comando di Gemini, non ti verrà più chiesto di selezionare un tema e un metodo di autenticazione. Ciò significa che viene salvato da qualche parte e il file che utilizza si chiama settings.json ed è il modo per personalizzare Gemini CLI.

Le impostazioni vengono applicate con la seguente priorità (Cloud Shell rende disponibili solo le impostazioni utente):

Sistema: /etc/gemini-cli/settings.json (si applica a tutti gli utenti, sostituisce le impostazioni utente e dello spazio di lavoro).
Workspace: .gemini/settings.json (override delle impostazioni utente).
Utente: ~/.gemini/settings.json.

Utente Windows: %USERPROFILE%.gemini\settings.json (che in genere si espande a C:\Users<YourUsername>.gemini\settings.json)

Sistema: %ProgramData%\gemini-cli\settings.json (che in genere si espande a C:\ProgramData\gemini-cli\settings.json)

Utente Mac: ~/.gemini/settings.json (che si espande in /Users/<YourUsername>/.gemini/settings.json)

Sistema: /etc/gemini-cli/settings.json

Se ricordi, al momento della selezione del tema, hai scelto di salvare le impostazioni nelle Impostazioni utente. Visita la pagina ~/.gemini folder e noterai il file settings.json.

Di seguito è riportato il mio file settings.json. Se avessi selezionato un altro tema, ne vedresti il nome.

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal" or "cloud-shell"
}

5. La nostra prima interazione con Gemini CLI

Iniziamo a utilizzare l'interfaccia a riga di comando di Gemini e digitiamo la prima query come mostrato di seguito:

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

La risposta prevista è mostrata di seguito:

Noterai che la nostra query ha generato uno strumento GoogleSearch (uno strumento integrato nell'interfaccia a riga di comando di Gemini) che è stato richiamato. In altre parole, hai già utilizzato uno dei potenti strumenti integrati di Gemini CLI, ovvero GoogleSearch, che basa le sue risposte sulle informazioni che ottiene dal web. Scoprirai di più sugli strumenti nella sezione successiva.

Un modo rapido per comprendere la CLI Gemini e i vari comandi che supporta è digitare /help (barra) per visualizzare una serie di comandi e scorciatoie da tastiera, come mostrato di seguito:

Per ora chiudiamo l'interfaccia a riga di comando di Gemini. Puoi farlo tramite il comando /quit oppure puoi eseguire Ctrl-C due volte nella sessione del terminale interattivo della CLI Gemini.

6. Interfaccia a riga di comando di Gemini - Parametri dei comandi

Quando avvii Gemini CLI, puoi fornire alcuni parametri della riga di comando. Per visualizzare un elenco completo delle opzioni, puoi utilizzare --help come mostrato di seguito.

gemini --help

Dovrebbe essere visualizzata l'intera gamma di opzioni disponibili. Ti invitiamo a consultare la documentazione qui.

Diamo un'occhiata ad alcuni. Il primo consiste nel configurare l'interfaccia a riga di comando di Gemini in modo da utilizzare il modello Pro o Flash. Al momento della stesura di questo lab, questi sono gli unici due modelli supportati. Per impostazione predefinita viene utilizzato il modello Gemini 2.5 Pro, ma se vuoi utilizzare il modello Flash, puoi farlo quando avvii Gemini CLI tramite il parametro -m, come mostrato di seguito:

gemini -m "gemini-2.5-flash"

Se inizi nel modo sopra descritto, puoi controllare il modello in basso a destra del terminale Gemini CLI, come mostrato di seguito:

Modalità non interattiva

Un'opzione interessante è eseguire l'interfaccia a riga di comando di Gemini in modalità non interattiva. Ciò significa che fornisci direttamente il prompt e Gemini risponderà senza aprire il terminale interattivo di Gemini CLI. Questa opzione è molto utile se prevedi di utilizzare l'interfaccia a riga di comando di Gemini in modo automatico nell'ambito dello script o di qualsiasi altro processo di automazione. Utilizzi il parametro -p per fornire il prompt all'interfaccia a riga di comando di Gemini come mostrato di seguito:

gemini -p "What is the gcloud command to deploy to Cloud Run"

Tieni presente che non è possibile continuare la conversazione con domande di follow-up. Questa modalità non consente inoltre di autorizzare strumenti (incluso WriteFile) o di eseguire comandi shell.

7. Interfaccia a riga di comando di Gemini - Strumenti integrati

La CLI Gemini include un insieme di strumenti integrati e la documentazione degli strumenti afferma che "il modello Gemini utilizza questi strumenti per interagire con il tuo ambiente locale, accedere alle informazioni ed eseguire azioni. Questi strumenti migliorano le funzionalità della CLI, consentendole di andare oltre la generazione di testo e di assistere in un'ampia gamma di attività".

Per ottenere un elenco degli strumenti integrati attuali, richiama il comando /tools come mostrato di seguito:

Una delle prime cose che dovresti chiederti è se l'interfaccia a riga di comando di Gemini può semplicemente chiamare questi strumenti quando vuole. La risposta predefinita è no, quando si tratta di operazioni sensibili che potrebbero comportare la scrittura nel sistema locale, la lettura da un sistema esterno, l'accesso alla rete esterna e così via.

Sebbene sia disponibile un --yolomode quando avvii la CLI (in genere non consigliato), vedrai che la CLI Gemini ti chiederà l'autorizzazione per eseguire lo strumento che ha scelto. Puoi rifiutare l'autorizzazione, consentire l'esecuzione una sola volta o concedere l'autorizzazione generale per l'esecuzione continua. Sei e dovresti avere il pieno controllo della situazione.

Utilizziamo un prompt che farà scegliere a Gemini CLI uno degli strumenti integrati da eseguire e che ti darà una buona comprensione di come funziona il tutto.

Immagina uno scenario in cui vuoi ricevere informazioni sulle ultime notizie finanziarie in tutto il mondo e salvarle in un file nella directory di lavoro locale da cui hai avviato Gemini CLI. Utilizza il seguente prompt:

Search for the latest headlines today in the world of finance and save them in a file named finance-news-today.txt

Immagina per un momento cosa dovrebbe fare. Idealmente, deve eseguire una ricerca su Google per ottenere notizie da alcune fonti di informazioni pertinenti che possono fornirgli notizie finanziarie. Dopodiché, deve creare un file denominato finance-news-today.txt (un'operazione di scrittura sul sistema locale che richiederà la tua autorizzazione) con i relativi contenuti.

Vediamo cosa succede (dovresti procedere allo stesso modo sulla tua macchina).

La prima cosa che fa è richiamare lo strumento GoogleSearch per cercare sul web.

Una volta completata la ricerca, i dati vengono recuperati come mostrato di seguito:

Una volta fatto, è pronto per scrivere nel file e utilizzerà lo strumento WriteFile, ma poiché si tratta di un'operazione sensibile (scrittura), ti chiederà l'autorizzazione. Puoi decidere il tipo di autorizzazione, ad esempio Consenti una volta, Consenti sempre e così via. Per ora, seleziona Consenti una volta.

Le informazioni verranno scritte nel file e di seguito verrà visualizzato un messaggio di operazione riuscita:

Come si verifica se il file è scritto o meno? Puoi utilizzare @file per chiedere di leggere i contenuti. Mentre digiti @, viene visualizzato un elenco di file nella cartella corrente e il file appena creato. Selezionala e invia il prompt. Il mio prompt è mostrato di seguito:

read the contents of @finance-news-today.txt

In questo modo vengono richiamati gli strumenti richiesti (ReadManyFiles, ReadFile) e i contenuti vengono visualizzati come mostrato di seguito:

8. Interfaccia a riga di comando di Gemini - Modalità shell

È il momento giusto per imparare a lavorare direttamente con la shell da Gemini CLI. Puoi passare alla modalità shell premendo ! nella casella del messaggio. Verrà attivata una modalità Shell. Puoi tornare indietro premendo di nuovo ! o il tasto ESC.

In modalità shell, vedrai ! all'inizio del prompt, come mostrato di seguito:

Puoi eseguire il controllo direttamente utilizzando comandi standard come pwd e ls, come mostrato di seguito. Tieni presente che i comandi presuppongono un sistema operativo di tipo Linux. Se utilizzi un altro sistema operativo (Windows), utilizza comandi equivalenti come (cd, dir e type). Tieni presente che l'output di queste chiamate è incluso nella finestra contestuale del modello.

Oggi puoi stampare i contenuti del file tramite il comando cat.

Esercizio: ecco un breve esercizio da provare. Scegli un feed RSS a tua scelta. Fornisci un prompt all'interfaccia a riga di comando di Gemini per recuperare i contenuti del feed RSS e formattare i risultati in un modo specifico. È un buon modo per automatizzare qualcosa all'inizio della giornata. Puoi anche chiedere a Gemini CLI di scoprire se esiste un feed RSS per un'area specifica, ad esempio le note di rilascio di Google Cloud.

Di seguito è riportato un esempio di prompt:

Get the latest release notes for Google Cloud from its RSS Feed and display the key points in a well-formatted list.

Idealmente, questo prompt dovrebbe prima richiamare lo strumento GoogleSearch per trovare il feed RSS di Google Cloud Platform e poi utilizzare lo strumento WebFetch per recuperare i contenuti del feed RSS e visualizzarli.

9. Configurazione dei server Model Context Protocol (MCP)

Un server MCP è un'applicazione che espone strumenti e risorse alla CLI Gemini tramite il Model Context Protocol, consentendole di interagire con sistemi e origini dati esterni. I server MCP fungono da ponte tra il modello Gemini e il tuo ambiente locale o altri servizi come le API.

Un server MCP consente all'interfaccia a riga di comando di Gemini di rilevare ed eseguire strumenti, estendendo così le funzionalità dell'interfaccia a riga di comando di Gemini per eseguire azioni oltre alle funzionalità integrate, come l'interazione con database, API, script personalizzati o workflow specializzati.

La CLI Gemini supporta la configurazione dei server MCP per scoprire e utilizzare strumenti personalizzati. Se hai avviato l'interfaccia a riga di comando di Gemini, puoi controllare i server MCP configurati tramite il comando /mcp, come mostrato di seguito:

Se non hai configurato alcun server MCP, verrà avviata la documentazione del server MCP di Gemini CLI.

Puoi configurare i server MCP a livello globale nel file ~/.gemini/settings.json o nella directory principale del progetto. Crea o apri il file .gemini/settings.json. All'interno del file, devi aggiungere il blocco di configurazione mcpServers, come mostrato di seguito:

"mcpServers": {
    "server_name_1": {},
    "server_name_2": {},
    "server_name_n": {}
 }

Ogni configurazione del server supporta le seguenti proprietà ( documentazione di riferimento):

Obbligatorio (uno dei seguenti)

command (string): percorso dell'eseguibile per il trasporto Stdio
url (stringa): URL endpoint SSE (ad es. "http://localhost:8080/sse")
httpUrl (stringa): URL dell'endpoint di streaming HTTP

Facoltativo

args (string[]): argomenti della riga di comando per il trasporto Stdio
headers (oggetto): intestazioni HTTP personalizzate quando si utilizza url o httpUrl
env (oggetto): variabili di ambiente per il processo del server. I valori possono fare riferimento alle variabili di ambiente utilizzando la sintassi $VAR_NAME o ${VAR_NAME}
cwd (stringa): directory di lavoro per il trasporto Stdio
timeout (numero): timeout della richiesta in millisecondi (valore predefinito: 600.000 ms = 10 minuti)
trust (booleano): se è true, ignora tutte le conferme di chiamata dello strumento per questo server (valore predefinito: false)
includeTools (string[]): elenco dei nomi degli strumenti da includere da questo server MCP. Se specificato, da questo server saranno disponibili solo gli strumenti elencati qui (comportamento della whitelist). Se non specificato, tutti gli strumenti del server sono attivati per impostazione predefinita.
excludeTools (string[]): elenco dei nomi degli strumenti da escludere da questo server MCP. Gli strumenti elencati qui non saranno disponibili per il modello, anche se sono esposti dal server. Nota: excludeTools ha la precedenza su includeTools. Se uno strumento è presente in entrambi gli elenchi, verrà escluso.

Procediamo con la configurazione di uno dei server MCP chiave di cui potresti aver bisogno se utilizzi GitHub. Probabilmente ti starai chiedendo: se ho già configurato Git e altri strumenti correlati sul mio sistema, ho comunque bisogno del server GitHub MCP?

Gemini CLI richiamerà gli strumenti git presenti nel sistema e potrai anche istruire Gemini CLI a utilizzarli. Tieni presente che Gemini CLI ti aiuterà a tradurre le query in linguaggio naturale in strumenti equivalenti che potresti avere sul tuo sistema e potrebbe richiedere che tu lo specifichi esplicitamente nel prompt.

Potresti non aver bisogno della sezione successiva per configurare un server MCP GitHub se hai già configurato quanto segue sul tuo sistema:

Strumenti Git (ciò significa che puoi eseguire comandi come git init, git add e così via sul tuo sistema)
gh : si tratta di GitHub sulla riga di comando. Porta le richieste pull, i problemi e altri concetti di GitHub nel terminale accanto a dove lavori già con Git e il tuo codice. Installalo da qui e convalida la configurazione tramite alcuni comandi, in particolare per l'autenticazione a GitHub dal tuo computer.

Se vuoi comunque provare il server Github MCP, consulta la sezione successiva o puoi saltarla.

Server MCP GitHub

Il server MCP ufficiale di GitHub fornisce una documentazione sufficiente sugli strumenti che espone e su come configurarli. Puoi scegliere se eseguirlo in locale o in remoto, poiché Gemini CLI supporta anche i server MCP remoti.

Questo tutorial illustra l'opzione Remote MCP Server in GitHub. Per farlo, devi prima disporre di un token di accesso personale (PAT) di GitHub.

Una volta ottenuto, devi aggiungere l'oggetto server MCP nel file settings.json. Di seguito è riportato il file settings.json completo sul mio sistema. Potresti avere altre impostazioni, ma l'oggetto mcpServers deve essere come indicato di seguito:

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal",
  "mcpServers": {
       "github": {
            "httpUrl": "https://api.githubcopilot.com/mcp/",
            "headers": {
                "Authorization": "GITHUB_PAT"
            },
            "timeout": 5000
       }
  }
}

Puoi riavviare Gemini CLI o eseguire un comando /mcp refresh dopo aver aggiornato settings.json con la configurazione del server GitHub MCP. Lo screenshot seguente evidenzia il server Github MCP configurato sul mio computer e i vari strumenti ora disponibili per la CLI Gemini per interagire con MCP.

Iniziamo con un prompt che richiamerà uno degli strumenti del server GitHub MCP. Digita il seguente prompt:

Tieni presente che verrà selezionato lo strumento corretto dal server GitHub MCP, ma come per altri strumenti integrati, sarà necessario fornire l'autorizzazione esplicita per richiamare lo strumento. Continua e vedi che output ottieni.

Ora devi lavorare con uno dei tuoi progetti GitHub. Fornisci le query in linguaggio naturale, ad esempio:

Descrivimi <repo-name>.
Clona <repo-name> sulla mia macchina locale.
Descrivi @<nome file> o @<nome directory>/
Quali sono i diversi componenti di questo repository?
Ho apportato le modifiche necessarie. Puoi eseguire il push delle modifiche su GitHub e utilizzare gli strumenti del server GitHub MCP per farlo.

Più avanti nel lab troverai un esercizio per lavorare in dettaglio con il server GitHub MCP.

Server MCP Context7

Context7 fornisce documentazione aggiornata per LLM ed editor di codice AI. Se vuoi fornire il contesto all'LLM con la documentazione più recente per il framework che preferisci, il server Context7 MCP è una buona opzione da configurare.

Assicurati che la tua biblioteca sia elencata nella home page di Context7.

Ecco il server MCP che devi aggiungere nel file settings.json.

"context7": {
      "httpUrl": "https://mcp.context7.com/mcp"
    }

Una volta configurato il server MCP e caricata correttamente la CLI Gemini, dovresti essere in grado di visualizzare gli strumenti Context7 come mostrato di seguito:

Ora puoi essere specifico nel prompt e chiedere all'interfaccia a riga di comando di Gemini di utilizzare Context7 per la documentazione più recente durante la generazione dell'applicazione o dello snippet di codice, utilizzando un framework XYZ specifico.

Ecco un esempio di prompt in cui voglio scrivere un agente utilizzando l'Agent Development Kit (ADK) di Google. Nel prompt specifico di cercare la documentazione relativa tramite il server MCP Context7.

I am working on coding an Agent using the Agent Development Kit (ADK) from Google. I would like to know how to create the LLMAgent in Python. Use Context7 for the latest documentation on ADK and specifically use /google/adk-python, /google/adk-docs and adk.wiki

Ecco l'output ricevuto:

Server MCP di Presentazioni Google

Il progetto GitHub all'indirizzo https://github.com/matteoantoci/google-slides-mcp fornisce un server MCP per interagire con l'API Google Slides. Consente di creare, leggere e modificare le presentazioni Google in modo programmatico.

I passaggi per configurare il server MCP sono indicati nel progetto. Avrai bisogno di un ambiente Node.js in cui creare il server, configurare un progetto Google Cloud e i token OAuth 2.0, quindi configurare il server MCP nel file settings.json.

Una volta configurato, puoi eseguire prompt come:

Estrai le informazioni più recenti da "web_url", riassumile in punti chiave e crea una presentazione denominata "my_presentation".

Prova anche tu!

Altri server MCP

Ecco un elenco aggiuntivo di server MCP che potrebbero interessarti:

Server Firebase MCP
Servizi multimediali Google Gen AI (Imagen, Veo, Lyria)
MCP Toolbox for Databases (lavora con i database Firestore, BigQuery e Google Cloud)
Server MCP di Google Workspace (funziona con Documenti, Fogli, Calendar e Gmail)

Le istruzioni per configurare i server MCP sopra indicati sono pubblicate in questo post del blog.

10. Personalizzare l'interfaccia a riga di comando di Gemini con GEMINI.md

Se hai notato il tuo utilizzo dell'interfaccia a riga di comando di Gemini finora, avrai notato che davamo solo il prompt e ci aspettavamo che l'interfaccia a riga di comando di Gemini lo eseguisse, a volte con risultati non conformi alle nostre aspettative. In alcuni prompt, hai fornito istruzioni specifiche su cosa fare e le hai incluse nel prompt.

Questo potrebbe funzionare bene in base a ciò che stai chiedendo a Gemini CLI di fare e ai risultati che ottieni. Tuttavia, in molti casi, vuoi assicurarti che rispetti le regole. Queste regole potrebbero riguardare linguaggi di programmazione o framework specifici da utilizzare. Potrebbero anche essere strumenti specifici. Potrebbero essere stili di codifica. Non si tratta solo di generazione, ma potresti anche voler che Gemini CLI sia rigorosamente in modalità "pianificazione" e che presenti solo un piano e non generi codice o modifichi file sul sistema.

Inserisci GEMINI.md. Questo è il file di contesto (per impostazione predefinita GEMINI.md, ma configurabile tramite la proprietà contextFileName nel file settings.json) fondamentale per configurare il contesto didattico (chiamato anche "memoria") fornito al modello Gemini. Questo file ti consente di fornire all'AI istruzioni specifiche per il progetto, guide di stile di codifica o qualsiasi informazione di base pertinente, rendendo le sue risposte più personalizzate e accurate in base alle tue esigenze.

Il file GEMINI.md è in formato Markdown e viene caricato in modo gerarchico, combinando più posizioni.

L'ordine di caricamento è:

Contesto globale:**~/.gemini/GEMINI.md** (per le istruzioni che si applicano a tutti i tuoi progetti).
Contesto progetto/elemento principale: la CLI esegue la ricerca dalla directory corrente fino alla radice del progetto per i file GEMINI.md.
Contesto della sottodirectory:la CLI esegue la scansione anche delle sottodirectory alla ricerca di file GEMINI.md, consentendo istruzioni specifiche per i componenti.

Puoi utilizzare /memory show per visualizzare il contesto combinato finale inviato al modello.

Che aspetto ha un GEMINI.md? Ne abbiamo creato uno dalla documentazione ufficiale:

# Project: My Awesome TypeScript Library

## General Instructions:

- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 20+.

## Coding Style:

- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).

## Specific Component: `src/api/client.ts`

- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.

## Regarding Dependencies:

- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.

Noterai che fornisce alcune istruzioni generali, oltre a istruzioni molto specifiche per lo stile di codifica, la gestione delle dipendenze e altro ancora. Sebbene questo sia un file GEMINI.md di esempio per i progetti TypeScript, puoi scrivere il tuo in base al linguaggio di programmazione, al framework, allo stile di codifica e ad altre preferenze.

Puoi provare a utilizzare un file GEMINI.md personalizzato. Questo esempio è tratto da un gist pubblicato che mostra come utilizzare Gemini CLI solo in modalità Pianifica. Il file viene riprodotto qui:

# Gemini CLI Plan Mode
You are Gemini CLI, an expert AI assistant operating in a special 'Plan Mode'. Your sole purpose is to research, analyze, and create detailed implementation plans. You must operate in a strict read-only capacity.

Gemini CLI's primary goal is to act like a senior engineer: understand the request, investigate the codebase and relevant resources, formulate a robust strategy, and then present a clear, step-by-step plan for approval. You are forbidden from making any modifications. You are also forbidden from implementing the plan.

## Core Principles of Plan Mode
*   **Strictly Read-Only:** You can inspect files, navigate code repositories, evaluate project structure, search the web, and examine documentation.
*   **Absolutely No Modifications:** You are prohibited from performing any action that alters the state of the system. This includes:
    *   Editing, creating, or deleting files.
    *   Running shell commands that make changes (e.g., `git commit`, `npm install`, `mkdir`).
    *   Altering system configurations or installing packages.

## Steps
1.  **Acknowledge and Analyze:** Confirm you are in Plan Mode. Begin by thoroughly analyzing the user's request and the existing codebase to build context.
2.  **Reasoning First:** Before presenting the plan, you must first output your analysis and reasoning. Explain what you've learned from your investigation (e.g., "I've inspected the following files...", "The current architecture uses...", "Based on the documentation for [library], the best approach is..."). This reasoning section must come **before** the final plan.
3.  **Create the Plan:** Formulate a detailed, step-by-step implementation plan. Each step should be a clear, actionable instruction.
4.  **Present for Approval:** The final step of every plan must be to present it to the user for review and approval. Do not proceed with the plan until you have received approval. 

## Output Format
Your output must be a well-formatted markdown response containing two distinct sections in the following order:

1.  **Analysis:** A paragraph or bulleted list detailing your findings and the reasoning behind your proposed strategy.
2.  **Plan:** A numbered list of the precise steps to be taken for implementation. The final step must always be presenting the plan for approval.

NOTE: If in plan mode, do not implement the plan. You are only allowed to plan. Confirmation comes from a user message.

Salva i contenuti riportati sopra in un file denominato GEMINI.md e salvalo in ~/.gemini/GEMINI.md. Si tratta della stessa cartella in cui hai creato il file settings.json. Puoi anche conservare il file GEMINI.md nella cartella <current project folder>/.gemini o avere più file GEMINI.md nelle sottodirectory se hai istruzioni diverse.

Fornisci un prompt per generare un'applicazione e osserva come risponde.

Ecco un altro file GEMINI.md ( modalità Spiega di Gemini) che puoi studiare e poi riutilizzare in base alle tue esigenze. L'obiettivo è rendere GEMINI CLI una guida interattiva che aiuti gli utenti a comprendere codebase complesse attraverso un processo di scoperta conversazionale.

Il file GEMINI.md è fondamentale per fare in modo che Gemini CLI segua le tue preferenze. Ti consigliamo di dare un'occhiata a questa serie pratica "Practical Gemini CLI", che approfondisce questo argomento, spiega come generare automaticamente un file per il tuo progetto, come personalizzare anche il prompt di sistema e altro ancora.

Tieni presente che puoi anche creare il file GEMINI.md mentre interagisci con l'interfaccia a riga di comando di Gemini. In qualsiasi momento, puoi utilizzare il comando /memory add <some instruction/rule> e l'interfaccia a riga di comando Gemini lo aggiungerà al file GEMINI.md. Puoi anche utilizzare il linguaggio naturale per chiedere a Gemini CLI di aggiungere informazioni alla sua memoria, ad esempio GEMINI.md, tramite prompt come "Ricorda <alcune istruzioni/regole>" o "Aggiungi alla memoria <alcune istruzioni/regole>".

11. Interfaccia a riga di comando di Gemini - Comandi slash personalizzati

Hai appena visto come personalizzare GEMINI.md per creare una modalità di pianificazione. La sezione precedente ti ha fornito anche i link a una modalità Spiega.

Cosa succede se vuoi configurare entrambe le modalità e istruire Gemini CLI a passare a una di queste modalità tramite i comandi slash /plan o /explain. Questo è esattamente lo scopo dei comandi slash personalizzati dell'interfaccia a riga di comando di Gemini.

Come indicato nella documentazione, "I comandi personalizzati ti consentono di salvare e riutilizzare i prompt preferiti o utilizzati più di frequente come scorciatoie personali all'interno di Gemini CLI. Puoi creare comandi specifici per un singolo progetto o comandi disponibili a livello globale in tutti i tuoi progetti, semplificando il flusso di lavoro e garantendo la coerenza."

Creiamo un paio di comandi personalizzati: /plan e /explain.

Il passaggio successivo consiste nel capire da dove l'interfaccia a riga di comando di Gemini recupera i comandi personalizzati. Come indicato nella documentazione, rileva i comandi da due posizioni, caricati in un ordine specifico:

Comandi utente (globali): si trovano in ~/.gemini/commands/. Questi comandi sono disponibili in qualsiasi progetto su cui stai lavorando.
Project Commands (locale): si trova in <your-project-root>/.gemini/commands/. Questi comandi sono specifici per il progetto corrente e possono essere archiviati nel controllo della versione per essere condivisi con il tuo team.

Scegliamo la cartella del progetto corrente da cui hai avviato Gemini CLI. Quindi, questa sarà la cartella <your-project-root>/.gemini/commands/. Procedi e crea la struttura delle cartelle.

Che cosa dobbiamo creare all'interno di questa cartella? Abbiamo bisogno di due file TOML (plan.toml e explain.toml). Se vuoi, puoi leggere di più sugli spazi dei nomi e sulle convenzioni di denominazione qui.

Ogni file TOML deve avere due campi : description e prompt. Assicurati che la descrizione sia breve e concisa, in quanto verrà visualizzata accanto al comando nella CLI Gemini. L'esempio di file TOML riportato di seguito è tratto dal post del blog ufficiale sui comandi personalizzati.

Di seguito è riportato un esempio di file plan.toml. Tieni presente che il prompt contiene un segnaposto speciale {{args}}. La CLI sostituirà questo segnaposto esatto con tutto il testo digitato dall'utente dopo il nome del comando.

description="Investigates and creates a strategic plan to accomplish a task."
prompt = """
Your primary role is that of a strategist, not an implementer.
Your task is to stop, think deeply, and devise a comprehensive strategic plan to accomp{{lish the following goal: args}}

You MUST NOT write, modify, or execute any code. Your sole function is to investigate the current state and formulate a plan.

Use your available "read" and "search" tools to research and analyze the codebase. Gather all necessary context before presenting your strategy.

Present your strategic plan in markdown. It should be the direct result of your investigation and thinking process. Structure your response with the following sections:

1.  **Understanding the Goal:** Re-state the objective to con&firm your understanding.
2.  **Investigation  Analysis:** Describe the investigative steps you would take. What files would you need to read? What would you search for? What critical questions need to be answered before any work begins?
3.  **Proposed Strategic Approach:** Outline the high-level strategy. Break the approach down into logical phases and describe the work that should happen in each.
4.  **Verification Strategy:** Explain how the success of this plan would be measured. What should be tested to ensure the goal is met without introduci&ng regressions?
5.  **Anticipated Challenges  Considerations:** Based on your analysis, what potential risks, dependencies, or trade-offs do you foresee?

Your final output should be ONLY this strategic plan.
"""

Prova a creare anche un file explain.toml. Puoi fare riferimento alla modalità Spiega di Gemini per scegliere alcuni contenuti.

Riavvia l'interfaccia a riga di comando di Gemini. Ora vedrai che ha un comando slash (/plan), come mostrato di seguito:

12. Casi d'uso da provare

L'interfaccia a riga di comando di Gemini può essere applicata a un'ampia gamma di casi d'uso che riguardano sia gli sviluppatori che gli utenti non sviluppatori. Di seguito sono riportati alcuni scenari che puoi provare a seconda della tua area di interesse.

In ognuno di questi casi, viene fornito il prompt. Puoi provare questa funzionalità in modalità interattiva o non interattiva dell'interfaccia a riga di comando di Gemini tramite il parametro -p al momento dell'avvio dell'interfaccia a riga di comando di Gemini.

Vibe coding con l'interfaccia a riga di comando di Gemini

Utilizziamo l'interfaccia a riga di comando di Gemini per creare il codice di un'applicazione. In questa attività, chiederai a Gemini CLI di generare un'applicazione e poi eseguire il push della versione iniziale in un repository GitHub.

Prerequisito

Per eseguire le attività in questa sezione, sono necessari alcuni prerequisiti:

Git
Interfaccia a riga di comando di Gemini con il server GitHub MCP (operazione eseguita in precedenza) o se hai configurato gh ( strumento GitHub CLI), anche questo funzionerà.
Familiarità con le nozioni di base di Git e un po' di conoscenze di programmazione

Supporremo che tu abbia avviato Gemini CLI in una cartella specifica a tua scelta. Assicurati che i server MCP siano stati avviati correttamente, in particolare il server MCP di GitHub.

Inizia con un prompt iniziale. Puoi modificarlo come preferisci. Tieni presente che durante la sessione con Gemini CLI, ti verrà chiesto di concedere le autorizzazioni per creare i file e così via. Concedi le autorizzazioni richieste.

In questa attività, non vogliamo che l'interfaccia a riga di comando di Gemini esegua l'applicazione o la provi per noi, perché vorremmo un po' più di controllo. Ma spetta completamente a te decidere come farlo.

Generate a website for a 1-day event filled with technical talks. There are going to be 6 talks in a single track of 1 hour each. Each talk has the following information: title, 1 or maximum of 2 speakers, category (1 or maximum of 3 keywords), duration and a description. The website has a single page where users can see the schedule for the entire day with the timings. There will be one lunch break of an hour and the event starts at 10:00 AM. Keep a 10 minute transition between talks. I would like to use Node.js on the server side and standard HTML, JavaScript and CSS on the front-end. The users should be able to search the talks based on category.

I would like you to proceed in the following way: 
1. Plan out how you would design and code this application.
2. Ask me for any clarifications along the way.
3. Once I am fine with it, do generate the code and provide me instructions to run and test locally.

I seguenti prompt e risposte sono un flusso di esempio osservato. Potresti ricevere una risposta completamente diversa, quindi esamina il piano e interagisci con Gemini CLI in base alle esigenze.

Abbiamo notato che a volte Gemini CLI cerca di fare di più e potrebbe persino fornirti i comandi che vorrebbe eseguire. Per questo esercizio, è consigliabile non farlo, in modo da avere un maggiore controllo su come viene svolta l'attività e su cosa vuoi convalidare personalmente.

Ad esempio, se ti viene chiesto di eseguire i comandi, puoi semplicemente uscire e dare un messaggio come mostrato di seguito:

Dopo aver seguito le istruzioni per avviare il server e passare alla home page, abbiamo ottenuto un sito di esempio come mostrato di seguito (se hai utilizzato lo stesso prompt, dovresti visualizzare una variante di un sito simile):

Puoi continuare ad apportare altre modifiche con l'aiuto di Gemini CLI. Una volta soddisfatto delle modifiche, puoi eseguirne il push in un repository GitHub.

Per prima cosa, creiamo un file .gitignore con l'aiuto di Gemini CLI.

Create a .gitignore file for this project.

Il passaggio successivo consiste nel dare istruzioni all'interfaccia a riga di comando di Gemini per eseguire il push di questo repository nel nostro account GitHub. In questo modo, gli strumenti del server MCP di GitHub verranno eseguiti in background.

Dai un prompt simile a quello riportato di seguito:

Great! I would now like to push all of this to a new repository in my Github account. I would like to name this repository <Your-Name>-event-talks-app

Verranno eseguiti diversi comandi:

Crea il repository.
Utilizzerà più comandi Git : init, add, commit per gestire il repository Git locale.
Verrà quindi configurato il Git remoto e verrà eseguito un push.

Nota:in alcuni casi, Gemini CLI potrebbe andare in timeout o utilizzare un nome utente errato e così via. Interagisci con lo strumento e suggerisci le correzioni.

Se tutto va bene, dovresti avere un repository GitHub. Di seguito è riportato uno screenshot di esempio:

Tieni presente che non hai generato un README.md per questo progetto e che è un buon esercizio per la sezione successiva, in cui lavoreremo con questo repository che hai appena creato.

Utilizzo dell'interfaccia a riga di comando di Gemini per lavorare su un repository GitHub

In questo caso d'uso, utilizzerai la CLI Gemini per lavorare con un repository GitHub. Eseguirai più attività, tra cui:

Comprendere la base di codice
Generazione della documentazione in corso
Implementazione di una nuova funzionalità
Esegui il commit e il push delle modifiche nel repository
Lavorare su un problema di GitHub e implementare le modifiche proposte

In questo modo avrai una base solida per lavorare con i tuoi repository e utilizzare l'interfaccia a riga di comando di Gemini come assistente per queste attività specifiche per gli sviluppatori.

Prerequisito

Per eseguire le attività in questa sezione, devi:

Git
Interfaccia a riga di comando di Gemini con il server GitHub MCP (operazione eseguita in precedenza) o se hai configurato gh ( strumento GitHub CLI), anche questo funzionerà.
Familiarità con le nozioni di base di Git e un po' di conoscenze di programmazione (in questo esempio utilizzeremo Node.js, poiché potresti già avere l'ambiente pronto sul tuo computer grazie all'installazione della CLI Gemini). Tuttavia, in un secondo momento puoi scegliere un repository a tua scelta con un linguaggio di programmazione e un framework diversi.
Dovresti aver completato la sezione precedente e avere a portata di mano il repository in cui abbiamo creato un sito web Event Talks.

Continuiamo a utilizzare Gemini CLI dalla cartella/directory che hai utilizzato per generare l'applicazione Event Talks o, se necessario, puoi clonare il repository sulla tua macchina locale e quindi avviare Gemini CLI da quella directory. Prova gli scenari elencati di seguito:

Comprendere la base di codice

Vorrei capire meglio questo progetto. Aiutami a capire le funzionalità principali e poi suddividile in lato server e lato client. Prendi un flusso di esempio e mostrami come funziona la richiesta e la risposta.
Spiega @server.js

Generazione di un file README

Genera un file README per questo progetto.

In questo caso, Gemini CLI non solo ha generato il file README, ma ha anche voluto eseguire i comandi per aggiungerlo al repository Git e inviare le modifiche al repository remoto. Se lo fa, puoi consentirgli di farlo.

In alcuni casi, potrebbe persino offrirti di generare il file LICENSE. Puoi decidere se farlo. A seconda del risultato, troverai i file README e/o LICENSE generati e le modifiche sono state inviate a GitHub.

Implementazione di una nuova funzionalità

Vorrei implementare una nuova funzionalità che consenta all'utente di eseguire ricerche anche in base a un oratore specifico. Innanzitutto mostrami un piano di come implementeresti questa modifica, poi possiamo generare il codice.

Dovrebbe fornirti un piano che puoi approvare. Una volta approvate, l'interfaccia a riga di comando di Gemini procederà con le modifiche. Prova le modifiche e, se ci sono bug (probabile), chiedi a Gemini CLI di correggerli.

Una volta che le modifiche ti soddisfano, puoi seguire gli stessi passaggi per eseguirne il commit e il push al repository remoto.

Genera problemi in base alle funzionalità suggerite

Proviamo qualcosa di interessante. Chiederai a Gemini CLI in che modo può migliorare l'esperienza utente di questa applicazione e, in base alla sua valutazione, può creare questi suggerimenti come problemi nello stesso repository GitHub. Utilizzerà lo strumento "create_issue" del server MCP di GitHub.

Prova il seguente prompt:

Vorrei che valutassi l'applicazione dal punto di vista dell'esperienza utente. Facilità d'uso, reattività, messaggi utili e altro ancora. Crea un elenco di miglioramenti e poi crea i problemi nel repository GitHub.

Idealmente, condividerà prima i miglioramenti con te e poi procederà con la tua autorizzazione per creare i problemi nel repository GitHub. Ecco uno screenshot di esempio della nostra corsa:

Lavorare su un problema di GitHub e implementare le modifiche proposte

Ora puoi prendere uno dei problemi generati in precedenza e chiedere a Gemini CLI di risolverlo e implementarlo.

Di seguito è riportato un problema di esempio generato:

Prendi l'intero URL del problema e fornisci un prompt come questo:

Esamina il problema: <YOUR_ISSUE_URL> e comprendi quali modifiche devono essere apportate. Innanzitutto, discuti il piano e poi mostra le modifiche proposte nel codice.

Puoi approvare le modifiche e inviarle al repository. Puoi anche chiedere di chiudere il problema.

(Facoltativo) Attività quotidiane

I casi d'uso riportati di seguito sono attività che potresti finire per svolgere regolarmente. Queste includono l'organizzazione dei file in cartelle, il recupero e il riepilogo dei contenuti dal web, l'elaborazione dei file immagine e l'estrazione dei contenuti, l'utilizzo dei database e altro ancora.

Esplora i casi d'uso che preferisci.

Organizzare file/cartelle

Puoi utilizzare la CLI Gemini per organizzare i file in base ai tipi in varie cartelle, a seconda delle necessità. Vai a una cartella sul tuo computer che contiene diversi file .txt, .png, .jpg, .pdf, .mp4 e altri. Probabilmente si tratta del desktop o della cartella Download.

Ecco una cartella di esempio e i relativi contenuti (potresti avere altri file):

Vai alla cartella e avvia l'interfaccia a riga di comando di Gemini. Chiederai a Gemini CLI di creare prima alcune cartelle: Immagini, Documenti, Video e poi chiederai a Gemini CLI di organizzare i file nelle cartelle.

La CLI Gemini spesso ti chiede l'autorizzazione prima di eseguire i comandi, in particolare quelli che modificano il file system (come la scrittura, lo spostamento o l'eliminazione di file). Controlla sempre attentamente questi prompt prima di concedere l'autorizzazione. È la tua rete di sicurezza.

Create the following folders "Images","Documents","Videos"

Poi, inserisci il seguente prompt:

Go through all the files in this folder and then organize them by moving all the files ending with .jpg, .jpeg, .gif into the "Images" folder. Move all ".txt" files into the "Documents" folder. Move all the ".mp4" files in the "Videos" folder.

Di seguito è riportato un esempio di come dovrebbe essere lo stato finale della cartella. Dovresti vedere le nuove sottocartelle create e i file spostati nelle rispettive sottocartelle a seconda del tipo.

Di seguito sono riportati alcuni altri scenari di organizzazione (le richieste sono riportate accanto a ogni scenario):

Riepilogo:per ogni documento nella cartella "Documenti", crea un file txt nella stessa cartella denominato "summary_ORIGINAL_FILENAME.txt" che contenga un riepilogo di tre frasi dei punti principali del documento.
Categorizzazione per tipo:scansiona tutti i file PDF e DOCX in questa directory. Sposta tutti i file con la parola "fattura" nel nome o nel contenuto nella cartella "Finanziario/Fatture". Sposta i file con "ricevuta" in "Finanziario/Ricevute". Tutti gli altri file .docx vengono inseriti in "Report".
Estrazione delle informazioni chiave (e "tagging"): per ogni file PDF nella cartella "Finanziario/Fatture", leggi i contenuti. Se trovi una data, rinomina il file in modo che la includa nel formato AAAA-MM-GG, ad esempio ‘invoice_2025-07-26_original_name.pdf'.