0 · Setup e installazione

Tempo stimato: 30 minutiPrerequisiti: un abbonamento Claude Pro, Max, Team o Enterprise. Se non hai mai usato un terminale, leggi prima Le basi: dieci minuti e sei pronto.

In questo modulo installi Claude Code e gli parli per la prima volta. Alla fine avrai fatto il giro completo: un programma installato, un login fatto, una domanda posta sul tuo codice, una modifica proposta da un’AI e salvata nella storia del progetto. È il modulo più “meccanico” del corso — tanti comandi da copiare, poca teoria — e va bene così: la teoria comincia al modulo 3, quando avrai qualcosa di funzionante davanti.

Obiettivi

• Verificare che la tua macchina soddisfi i requisiti di sistema di Claude Code.
• Installare la CLI su macOS o Windows con l’installer nativo, e sapere quando conviene invece Homebrew, WinGet o npm.
• Installare l’app desktop Claude e capire come convive con la CLI.
• Autenticarti con il tuo account, senza mai configurare una API key a pagamento.
• Aprire la prima sessione su un progetto reale e chiudere il primo ciclo: domanda, modifica, commit.

Concetti chiave

Se parti da zeroTerminale, CLI, comandi: le tre parole di questo modulo

Il terminale è la finestra in cui dai ordini al computer scrivendo invece di cliccare (come si apre). Una CLI (Command Line Interface) è un programma pensato per essere usato da lì: Claude Code lo è. “Eseguire un comando” significa: copiarlo nel terminale e premere Invio. Tutto il resto del modulo è questo, ripetuto.

Claude Code è un motore, non una singola app. Lo stesso motore gira in quattro posti: nel terminale (la CLI), nell’app desktop, dentro VS Code e JetBrains, e sul web. Condividono la stessa configurazione — CLAUDE.md, server MCP, hook, skills e settings — quindi installare la CLI e l’app desktop non significa mantenere due setup separati: è lo stesso setup con due interfacce. In questo modulo installi CLI e desktop; VS Code e Antigravity li vediamo nel modulo 1.

Serve un abbonamento a pagamento. Claude Code richiede un piano Pro, Max, Team, Enterprise o un account Claude Console. Il piano gratuito di Claude.ai non include Claude Code. In tutto il corso usiamo il login con l’account: non serve, e non chiederemo mai, una API key a consumo.

L’installer nativo è la via consigliata. “Nativo” vuol dire che scarica un programma già pronto per il tuo sistema (un binario), senza bisogno di altri strumenti installati, e lo mette in ~/.local/bin/claude su macOS e Linux, in %USERPROFILE%\.local\bin\claude.exe su Windows. Il vantaggio pratico è l’auto-update in background: le installazioni native si tengono aggiornate da sole, mentre Homebrew, WinGet e i package manager Linux richiedono un aggiornamento manuale. Se scegli uno di quelli, mettiti in calendario un brew upgrade claude-code o winget upgrade Anthropic.ClaudeCode ogni tanto.

C’è anche un pacchetto npm — il gestore di pacchetti del mondo JavaScript, cioè lo “store” da cui gli sviluppatori installano librerie e strumenti. Se npm fa già parte della tua giornata, npm install -g @anthropic-ai/claude-code ti dà lo stesso identico binario nativo; se non sai cosa sia npm, ignora questa strada e usa l’installer nativo. Dalla v2.1.198 il pacchetto richiede Node.js 22 o superiore.

Su Windows hai due strade. Windows nativo funziona senza altro, ma Git for Windows è consigliato: fornisce Git Bash, che abilita il tool Bash. Senza Git for Windows, Claude Code esegue i comandi tramite il tool PowerShell. In alternativa puoi lavorare dentro WSL 2 (Windows Subsystem for Linux: un Linux completo che gira dentro Windows, si installa dal Microsoft Store). È l’unica configurazione Windows che supporta il sandboxing, cioè il “recinto” che limita cosa i comandi possono toccare: se scegli questa strada, installi e lanci claude dentro il terminale WSL, non da PowerShell.

Requisiti di sistema. macOS 13.0+, Windows 10 1809+ o Windows Server 2019+, oppure Ubuntu 20.04+ / Debian 10+ / Alpine 3.19+. Servono 4 GB di RAM, un processore x64 o ARM64 e una connessione a internet. Le shell supportate sono Bash, Zsh, PowerShell e CMD.

L’app desktop include già Claude Code. Non devi installare Node né la CLI per usarla. Ha tre tab — Chat, Cowork e Code — e in questo corso ci interessa la tab Code: sessioni parallele, diff visuale, terminale integrato, anteprima dell’app. Se vuoi anche il comando claude nel terminale, la CLI va installata a parte: sono due installazioni distinte che condividono la configurazione.

Esempio guidato

1. Controlla cosa hai già installato.

   Se claude risponde, hai già un’installazione: annota la versione e salta al passo 4.

   macOS

   claude --version

   Windows

   claude --version

   Un’installazione funzionante stampa un numero di versione seguito da (Claude Code):

   2.1.211 (Claude Code)

   Se ottieni command not found: claude (macOS) o 'claude' is not recognized (Windows), prosegui: devi ancora installarlo.

2. Installa la CLI con l’installer nativo.

   Il comando qui sotto fa due cose in una: scarica lo script ufficiale di installazione (curl è lo strumento che scarica cose da internet) e lo esegue subito, passandoglielo con una pipe (|). È la forma di installazione più comune nel mondo degli sviluppatori — e va usata solo con indirizzi di cui ti fidi, come questo, che è quello ufficiale di Anthropic.

   macOS

   # scarica lo script di installazione da claude.ai e lo esegue
   curl -fsSL https://claude.ai/install.sh | bash

   In alternativa, con Homebrew (il gestore di pacchetti più usato su macOS — se non lo hai già, salta questa alternativa):

   brew install --cask claude-code

   Homebrew offre due cask: claude-code segue il canale stable (tipicamente una settimana indietro, salta le release con regressioni gravi), claude-code@latest segue il canale latest. Nessuno dei due si auto-aggiorna.

   Windows

   In PowerShell:

   irm https://claude.ai/install.ps1 | iex

   In CMD (comando diverso, non intercambiabile):

   curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

   Non serve eseguire come Amministratore. Come capire in quale shell sei: il prompt mostra PS C:\ in PowerShell e C:\ senza PS in CMD.

   In alternativa, con WinGet:

   winget install Anthropic.ClaudeCode

   WinGet non si auto-aggiorna: dovrai lanciare winget upgrade Anthropic.ClaudeCode periodicamente.

3. Verifica l’installazione.

   macOS

   claude --version
   claude doctor

   Windows

   claude --version
   claude doctor

   claude doctor stampa una diagnostica in sola lettura di installazione e impostazioni — senza avviare una sessione — inclusi lo stato dell’installazione, eventuali errori di validazione dei file di settings e i warning con i suggerimenti per risolverli. È il primo comando da lanciare ogni volta che qualcosa non torna.

4. Fai login con il tuo account.

   Spostati nella cartella di un progetto e avvia una sessione. Il punto importante: Claude Code lavora sulla cartella da cui lo avvii — è il suo perimetro. Sostituisci il percorso dell’esempio con una tua cartella vera (un progetto di codice se ce l’hai; altrimenti una cartella qualsiasi con dei file di testo va benissimo per cominciare).

   macOS

   # cd = "change directory": entra nella cartella del progetto
   cd ~/progetti/il-mio-progetto
   # avvia Claude Code in quella cartella
   claude

   Windows

   # cd = "change directory": entra nella cartella del progetto
   cd $env:USERPROFILE\progetti\il-mio-progetto
   # avvia Claude Code in quella cartella
   claude

   Al primo avvio Claude Code apre il browser per il login — è il meccanismo “accedi con” che conosci da mille altri servizi: autorizzi dal browser, senza mai scrivere la password nel terminale. Scegli Claude Pro/Max (o l’account del tuo team) e completa l’accesso. Quando il login va a buon fine, il terminale mostra Login successful e ti chiede di premere Enter per continuare.

   Se il browser non si apre da solo, premi c per copiare l’URL di login negli appunti e incollalo a mano. Se il browser ti mostra un codice invece di tornare al terminale, incollalo al prompt Paste code here if prompted: succede quando il browser non riesce a raggiungere il server di callback locale, tipico di WSL2, sessioni SSH e container.

   Niente API key

   Una API key è una chiave segreta che paga le richieste a consumo — è l’altro modo di usare Claude, pensato per i programmi, e in questo corso non ci serve mai: usiamo l’abbonamento. Se in passato ne hai impostata una nella variabile d’ambiente ANTHROPIC_API_KEY, Claude Code la userebbe al posto del login (e pagheresti a consumo senza accorgertene). Rimuovila dalla sessione corrente con unset ANTHROPIC_API_KEY (macOS) o Remove-Item Env:\ANTHROPIC_API_KEY (PowerShell), e verifica con /status che il metodo attivo sia il tuo abbonamento. Attenzione: unset vale solo per la finestra di terminale aperta — se la chiave è impostata in modo permanente (una riga export ANTHROPIC_API_KEY=... in ~/.zshrc o nelle variabili d’ambiente di Windows), alla prossima apertura tornerà: in quel caso va tolta la riga da lì.

5. Fai la prima domanda.

   Sei dentro la sessione. Il prompt mostra versione, modello attivo e directory di lavoro. Scrivi in linguaggio naturale:

   what does this project do?

   (= “cosa fa questo progetto?” — ai modelli puoi scrivere anche in italiano, ma nel corso i prompt sono in inglese perché è la lingua in cui i modelli lavorano meglio sul codice)

   Claude legge i file che gli servono da solo: non devi aggiungere contesto a mano. Prova anche:

   explain the folder structure

   (= “spiegami com’è organizzata questa cartella”)

6. Fai la prima modifica e il primo commit.

   add a hello world function to the main file

   Claude trova il file giusto, ti mostra le modifiche proposte e — a seconda della modalità di permesso attiva — ti chiede l’approvazione prima di scrivere. Sui piani Pro, Max e Team la modalità di partenza è auto (un supervisore controlla le azioni in background e blocca quelle rischiose); in modalità default ti viene chiesta conferma a ogni modifica. Con Shift+Tab cicli tra le modalità. Le vediamo tutte in dettaglio nel modulo 6.

   Poi chiudi il ciclo chiedendo un commit — il “salvataggio firmato” di git che registra la modifica nella storia del progetto (se git è un mistero, due minuti su Le basi e torna qui):

   commit my changes with a descriptive message

   (in italiano: “salva le mie modifiche con un messaggio descrittivo”)

   Per uscire, /exit oppure Ctrl+D due volte.

7. Installa l’app desktop.

   Scarica l’installer e lancialo:

   macOS

   Download per macOS — build universale per Intel e Apple Silicon. Apri il .dmg, trascina Claude nella cartella Applicazioni e avvialo da lì.

   Windows

   Download per Windows x64 — oppure installer ARM64 se hai un PC ARM. Lancia il setup e avvia Claude dal menu Start.

   Perché le sessioni locali funzionino su Windows deve essere installato Git.

   Fai il sign in con lo stesso account, poi clicca la tab Code in alto al centro. Scegli Local, premi Select folder e seleziona lo stesso progetto di prima: ritroverai il tuo CLAUDE.md, i server MCP e le skill, perché desktop e CLI condividono la configurazione.

Esercizio

Prepara la tua postazione e verificala in modo verificabile, non a occhio.

1. Installa la CLI con l’installer nativo e conferma che claude --version stampi una versione.
2. Lancia claude doctor e leggi l’output: quale metodo di installazione riporta? Si auto-aggiorna?
3. Assicurati che il tuo login sia quello dell’abbonamento e non una API key.
4. Crea una cartella claude-tutorial-esercizi/, entraci, avvia claude e fatti creare un README.md che descriva il corso in tre righe.

Soluzione

Passi 1–2.

macOS

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor

Windows

irm https://claude.ai/install.ps1 | iex
claude --version
claude doctor

claude doctor distingue l’installazione nativa dalle altre. Se hai installato con l’installer nativo, l’auto-update è attivo in background e non devi fare nulla. Se hai usato Homebrew o WinGet, l’aggiornamento è manuale: brew upgrade claude-code oppure winget upgrade Anthropic.ClaudeCode.

Passo 3. Prima di avviare la sessione, togli di mezzo un’eventuale API key nell’ambiente:

macOS

echo $ANTHROPIC_API_KEY   # se stampa qualcosa, è impostata
unset ANTHROPIC_API_KEY

Windows

$env:ANTHROPIC_API_KEY    # se stampa qualcosa, è impostata
Remove-Item Env:\ANTHROPIC_API_KEY

Poi, dentro la sessione, /status: la riga Login method deve mostrare il tuo account di abbonamento. Se compare anche una riga API key, la key è ancora attiva e vince lei: nella scala di precedenza di Claude Code, una chiave nella variabile d’ambiente batte il login fatto col browser. È il motivo per cui l’abbiamo rimossa prima di controllare.

Passo 4.

macOS

# crea la cartella e, SE la creazione riesce ("&&"), entraci
mkdir claude-tutorial-esercizi && cd claude-tutorial-esercizi
claude

Windows

# crea la cartella, poi entraci (";" = esegui in sequenza)
mkdir claude-tutorial-esercizi; cd claude-tutorial-esercizi
claude

Poi, al prompt:

create a README.md describing this folder as my Claude Code course exercises, three lines max

Claude ti mostra il contenuto proposto e chiede conferma prima di scrivere il file. Approva e verifica con /exit seguito da cat README.md (macOS) o type README.md (Windows).

Errori comuni e troubleshooting

Sintomo	Causa	Soluzione
command not found: claude / 'claude' is not recognized	La directory di installazione non è nel PATH	Vedi sotto: aggiungi ~/.local/bin (macOS) o %USERPROFILE%\.local\bin (Windows) al PATH e riapri il terminale
'irm' is not recognized as an internal or external command	Stai usando il comando PowerShell dentro CMD	Usa il comando CMD, o passa a PowerShell
The token '&&' is not a valid statement separator	Stai usando il comando CMD dentro PowerShell	Usa irm https://claude.ai/install.ps1 | iex
'bash' is not recognized as the name of a cmdlet	Hai incollato il comando macOS su Windows	Usa il comando PowerShell o CMD
syntax error near unexpected token '<' oppure curl: (22) ... error: 403	L’installer ha restituito HTML invece dello script (proxy o captive portal)	Verifica che la rete raggiunga downloads.claude.ai, poi ripeti
Claude Code on Windows requires either Git for Windows (for bash) or PowerShell	Manca una shell utilizzabile	Installa Git for Windows
Error: claude native binary not installed	Install npm incompleto: le dipendenze opzionali non sono state scaricate	Reinstalla permettendo le dipendenze opzionali
Login: il browser mostra un codice invece di tornare al terminale	Il browser non raggiunge il server di callback locale (WSL2, SSH, container)	Incolla il codice al prompt Paste code here if prompted
Il login funziona ma le risposte falliscono con errori di autorizzazione	ANTHROPIC_API_KEY nell’ambiente ha la precedenza sull’abbonamento	unset ANTHROPIC_API_KEY, poi controlla con /status
App unavailable in region	Claude Code non è disponibile nel tuo paese	Vedi i paesi supportati

Sistemare il PATH

Prima il concetto, poi i comandi. Il PATH è l’elenco delle cartelle in cui il terminale cerca i programmi quando scrivi un nome: digiti claude, e il terminale scorre quelle cartelle finché non trova un file chiamato così. Se l’installer ha messo claude in una cartella che non è nell’elenco, il programma esiste ma il terminale non lo trova — ed ecco il command not found. La cura è aggiungere quella cartella all’elenco. È una modifica piccola ma permanente al tuo ambiente: i comandi qui sotto sono commentati riga per riga proprio per questo.

macOS

Controlla se la cartella è già nel PATH:

# stampa il PATH, un percorso per riga, e cerca la riga esatta "~/.local/bin"
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

Se stampa il percorso, il PATH è a posto e il problema è altrove. Se non stampa nulla, aggiungila. Su macOS la shell di default è Zsh, e il suo file di configurazione personale è ~/.zshrc — viene riletto a ogni nuova finestra del terminale:

# aggiunge UNA riga in fondo a ~/.zshrc (">>" = "appendi, non sovrascrivere"):
# la riga dice "d'ora in poi, cerca i programmi anche in ~/.local/bin"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# ricarica la configurazione nella finestra corrente, senza doverla chiudere
source ~/.zshrc

# verifica: ora deve rispondere con la versione
claude --version

Se sospetti di avere più installazioni in conflitto (ad esempio una vecchia via npm e una nuova nativa):

# elenca TUTTI i "claude" che il terminale trova nel PATH, in ordine di precedenza
which -a claude

Windows

Controlla se la cartella è già nel PATH:

# stampa il PATH spezzato per ";" e cerca le righe che contengono ".local\bin"
$env:PATH -split ';' | Select-String '\.local\\bin'

Se stampa il percorso, il PATH è a posto e il problema è altrove. Se non stampa nulla, aggiungila al PATH del tuo utente (modifica permanente, vale per tutte le finestre future):

# legge il PATH attuale dell'utente...
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
# ...e lo risalva con la cartella di Claude aggiunta in fondo
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Riavvia il terminale (le finestre già aperte non vedono la modifica) e verifica con claude --version.

Se sospetti di avere più installazioni in conflitto:

# elenca TUTTI i "claude" che il terminale trova, in ordine di precedenza
where.exe claude

L'estensione VS Code non basta

L’estensione per VS Code non installa claude nel PATH: usa una copia privata della CLI dentro la directory dell’estensione, per il proprio pannello. Se hai installato solo l’estensione, ~/.local/bin/claude non esiste. Per usare claude dal terminale serve l’installazione standalone.

Cheat-sheet

Comando	Cosa fa
curl -fsSL https://claude.ai/install.sh | bash	Installer nativo — macOS, Linux, WSL
irm https://claude.ai/install.ps1 | iex	Installer nativo — Windows PowerShell
brew install --cask claude-code	Installazione via Homebrew (canale stable)
winget install Anthropic.ClaudeCode	Installazione via WinGet
npm install -g @anthropic-ai/claude-code	Installazione via npm (richiede Node.js 22+)
claude --version	Stampa la versione installata
claude doctor	Diagnostica di installazione e settings, senza avviare una sessione
claude update	Applica subito un aggiornamento disponibile
claude	Avvia una sessione interattiva nella directory corrente
claude "task"	Avvia una sessione eseguendo subito il task indicato
/login	Rifà il login o cambia account, da dentro la sessione
/logout	Esce dall’account e resetta lo stato di primo avvio
/status	Mostra account attivo, metodo di login e configurazione
/help	Elenca i comandi disponibili
/exit o Ctrl+D due volte	Chiude la sessione
Shift+Tab	Cicla tra le modalità di permessi

Dove finiscono le cose

Elemento	macOS / Linux	Windows
Binario CLI	~/.local/bin/claude	%USERPROFILE%\.local\bin\claude.exe
Versioni installate	~/.local/share/claude/versions/	%USERPROFILE%\.local\share\claude
Credenziali	Keychain macOS (cifrato) · su Linux ~/.claude/.credentials.json, mode 0600	%USERPROFILE%\.claude\.credentials.json
Configurazione utente	~/.claude/ e ~/.claude.json	%USERPROFILE%\.claude\ e %USERPROFILE%\.claude.json

Fonti

Pagine ufficiali consultate, verificate il 16 agosto 2026:

• Advanced setup — requisiti di sistema, metodi di installazione, aggiornamenti, disinstallazione
• Quickstart — primo avvio, login, comandi essenziali
• Get started with the desktop app — installazione e prima sessione dell’app desktop
• Authentication — tipi di account, gestione credenziali, precedenza di autenticazione
• Troubleshoot installation and login — errori di installazione e di login
• Supported countries — disponibilità geografica