Qwen Code CLI: una guida con esempi

Alibaba ha rilasciato Qwen3-Coder, un modello di coding agentico disponibile in varie dimensioni, con la variante più potente Qwen3-Coder-480B-A35B-Instruct. Insieme a questi modelli, Alibaba ha reso open-source Qwen Code CLI, uno strumento da riga di comando per il coding agentico.

Qwen Code CLI è un fork di Gemini CLI ed è stato adattato specificamente per l’uso con il modello Qwen3-Coder in attività di coding agentico.

In questo blog ti spiegherò passo dopo passo come configurare e usare Qwen Code CLI. Lo useremo per esplorare codebase, fare refactoring del codice e altro ancora.

Teniamo i lettori aggiornati sulle ultime novità dell’AI con The Median, la nostra newsletter gratuita del venerdì che riassume le notizie chiave della settimana. Iscriviti e resta sul pezzo in pochi minuti a settimana:

Che cos’è Qwen Code?

Qwen Code è un’interfaccia a riga di comando progettata per facilitare attività di coding agentico. Usa prompt personalizzati e protocolli di function calling ottimizzati per Qwen3-Coder. Con Qwen Code puoi:

• Navigare e comprendere codebase complesse
• Individuare e correggere problemi di codice
• Generare codice e unit test
• Creare documentazione e flowchart

Fonte: QwenLM

Ora configuriamo Qwen3-Coder e usiamolo per esplorare e risolvere problemi in un progetto open source su cui ho lavorato di recente.

Passo 1: Prerequisiti

Prima di configurare Qwen Code, assicurati di avere installato Node.js (versione 20 o superiore). Puoi installare Node.js eseguendo:

curl -qL https://www.npmjs.com/install.sh | sh

Poi verifica l’installazione eseguendo quanto segue:

node -v
npm -v

Passo 2: Configurare Qwen Code

In questo passo vedremo diverse opzioni per installare e autenticare Qwen Code sul nostro dispositivo.

Passo 2.1: Installazione via npm

Con Node.js installato, configura Qwen Code a livello globale e controlla anche la versione installata:

npm install -g @qwen-code/qwen-code
qwen --version

Questo comando installa globalmente la Qwen Code CLI usando il package manager di Node.js. Dopo l’installazione, il comando qwen --version controlla e mostra la versione installata della Qwen CLI per verificare che sia configurata correttamente e pronta all’uso.

Eseguiamo Qwen Code:

qwen

Premi Invio per selezionare il tema predefinito e applicarlo alle impostazioni utente. Ora dobbiamo configurare l’autenticazione.

Passo 2.2: Installazione da sorgente (opzionale)

In alternativa, puoi scegliere di installare Qwen Code direttamente dal repository GitHub:

git clone https://github.com/QwenLM/qwen-code.git
cd qwen-code
npm install
npm install -g .

Questo comando clona il repository GitHub di Qwen Code CLI sulla tua macchina locale usando git clone. Poi entriamo nella directory clonata e installiamo tutte le dipendenze del progetto specificate nel package.json del repository. 

Nota: -g significa che è disponibile a livello di sistema, non solo nella directory locale del progetto.

Passo 2.3: Autenticazione

La CLI richiede una API key di Qwen 3 Coder per l’autenticazione. La documentazione ufficiale suggerisce di richiederla su https://bailian.console.aliyun.com/  (se ti trovi nella Cina continentale). Se non ti trovi nella Cina continentale, visita https://modelstudio.console.alibabacloud.com/ per richiedere la tua API key.

Tuttavia, se ti trovi in India, queste opzioni non sono disponibili. In alternativa, puoi usare OpenRouter, che fornisce accesso a più API key per numerosi modelli. Ecco i passaggi per impostare una API Key per Qwen 3 Coder con questo servizio:

• Crea un account su https://openrouter.ai/
• Vai alla scheda Models e cerca “Qwen 3 Coder”. Puoi scegliere la versione gratuita se ti servono meno di 128k token, altrimenti scegli la versione a pagamento (0,302 $/M token in input e output).

• Scorri verso il basso e clicca su Create API Key. Inserisci il nome della chiave e il limite di credito (opzionale), quindi clicca Create. Salva questa API key per usi futuri. 

• Poi vai alla scheda Credits e aggiungi i dati della tua carta o del tuo conto. Puoi anche pagare con Amazon Pay. Per questa demo, ho aggiunto circa 15 $, che sono stati sufficienti.

Passo 2.4: Configurazione dell’ambiente

Ora possiamo usare la API key all’interno della CLI. Torna alla CLI dal passo 2.1 e premi Invio.

Poi inserisci la API key del passo precedente, seguita dalla base URL e dal nome del modello come indicato di seguito:

API_KEY >Qwen_API_KEY_FROM_OPENROUTER
BASE_URL >https://openrouter.ai/api/v1
MODEL >qwen/qwen3-coder

In alternativa, puoi impostare queste variabili anche come variabili d’ambiente. Apri un nuovo terminale ed esegui quanto segue riga per riga.

export OPENAI_API_KEY="Qwen_API_KEY_FROM_OPENROUTER"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_MODEL="qwen/qwen3-coder"

Se stai usando una API key di Alibaba Cloud, configura le variabili d’ambiente come segue:

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
export OPENAI_MODEL="qwen3-coder-plus"

Una volta impostate queste variabili d’ambiente, premi Invio e puoi iniziare a sperimentare con la CLI.

Passo 3: Sperimentare con Qwen Code CLI

In questa sezione ti mostro come ho usato Qwen Code CLI per interagire con un progetto reale ospitato su GitHub. Con pochi prompt, Qwen mi ha aiutato a comprendere il codebase, ottimizzare funzioni, aggiungere nuove capacità, automatizzare test e mantenere la documentazione.

Con prompt ben congegnati, sono riuscito a:

• Analizzare l’architettura del codebase
• Ottimizzare funzioni specifiche per l’efficienza della memoria
• Generare ed eseguire automaticamente unit test
• Estendere le funzionalità integrando nuovi componenti
• Pubblicare aggiornamenti versionati su GitHub
• Generare un flowchart visivo delle interazioni tra moduli
• Documentare tutte le modifiche in un changelog strutturato

Entriamo nel dettaglio di ciascun passaggio.

Esplorare e comprendere il codebase

Iniziamo chiedendo a Qwen Code di esplorare e spiegare l’architettura del codebase. Ma prima clona il repository da GitHub e spostati nella directory del progetto con il seguente comando:

git clone https://github.com/AashiDutt/Voxtral_with_vLLM.git
cd Voxtral_with_vLLM

Ecco il prompt che ho usato per comprendere il repository clonato:

Prompt: Spiega l’architettura di questo codebase.

La CLI di Qwen ha analizzato file come app.py, config.py, requirements.txt e un notebook Colab. Ha poi restituito una chiara scomposizione della struttura del progetto con un riepilogo di alto livello dei moduli chiave, evitandomi di aprire e leggere manualmente ogni file.

Refactoring e ottimizzazione del codice

Dopo aver compreso l’architettura, ho usato Qwen Code CLI per analizzare le possibili aree di miglioramento nel codebase.

Prompt: Quali parti di questo modulo possono essere ottimizzate?

Qwen ha restituito un elenco strutturato di suggerimenti su più dimensioni: prestazioni, efficienza della memoria, manutenibilità ed esperienza utente. Non si è limitato a identificare i problemi, ma ha anche proposto modifiche al codice attuabili.

Seguendo le sue indicazioni, sono riuscito a:

• Ridurre l’uso di memoria e CPU
• Rafforzare la gestione degli errori
• Migliorare il feedback all’utente
• Semplificare la struttura del codice per gli sviluppi futuri

Nel passo successivo mostrerò come ho applicato una di queste ottimizzazioni (uso della memoria) e l’ho testata usando la stessa Qwen CLI.

Implementare e testare l’ottimizzazione del codice

Dopo aver individuato diverse aree di ottimizzazione, ho deciso di applicare uno dei suggerimenti più impattanti: migliorare l’uso della memoria nella funzione transcribe_audio. Ho quindi chiesto alla CLI di Qwen di intervenire su quello specifico file:

Prompt: Applica l’ottimizzazione dell’uso della memoria alla funzione transcribe_audio in @app.py

Qwen si è concentrato esclusivamente su app.py usando la sintassi @ per modifiche mirate. Questo targeting preciso è utile quando vuoi applicare cambiamenti isolati senza impattare parti non correlate del codebase. La CLI ha riscritto la funzione per:

1. Effettuare lo streaming ed elaborare chunk audio invece di caricarli tutti in memoria
2. Ridurre gli aggiornamenti della UI aggiornando la barra di avanzamento solo ogni 10 chunk
3. Eliminare la necessità di precomputare il numero totale di chunk

Ha inoltre aggiornato automaticamente il file CHANGELOG.md per riflettere questo miglioramento sotto un nuovo tag di versione.

Generare ed eseguire i test

Una volta applicata l’ottimizzazione dell’uso della memoria alla funzione transcribe_audio, ho usato Qwen Coder CLI per generare e validare automaticamente gli unit test per la nuova implementazione.

Prompt: Scrivi un unit test pytest per le modifiche recenti.

Qwen ha iniziato analizzando la struttura del progetto per verificare se esisteva una directory dei test e se pytest fosse elencato in requirements.txt. Poiché mancavano entrambi, ha:

• Aggiunto pytest>=7.0.0 a requirements.txt
• Creato una nuova directory tests/
• Generato un modulo di test: tests/test_transcribe_audio.py

Qwen ha eseguito i test e confermato che tutti e quattro sono passati con successo. Per mantenere una cronologia delle versioni chiara, Qwen ha anche aggiunto una nuova voce "Fixed" a CHANGELOG.md sotto la versione v0.2.0.

Con un solo prompt, Qwen CLI ha automatizzato la generazione dei test, identificato casi limite, aiutato a correggere un bug logico e garantito la correttezza del codice con una validazione rigorosa.

Implementare un nuovo componente

Per estendere le funzionalità del Voxtral Audio Assistant (codebase), ho chiesto a Qwen Code CLI di integrare il supporto per i video di YouTube.

Prompt: Estendi l’esempio attuale per supportare i video di YouTube. Quando un utente fornisce un URL di YouTube, estrai l’audio dal video e passalo al modello Voxtral per l’elaborazione. Mantieni invariato il resto della pipeline e dei componenti.

L’obiettivo era permettere agli utenti di inserire un URL di YouTube oltre a caricare file audio. Una volta fornito, l’app dovrebbe estrarre automaticamente l’audio dal video ed elaborarlo come un normale upload, senza modificare la pipeline a valle per trascrizione o Q&A. 

Qwen ha analizzato app.py, config.py e requirements.txt per identificare gli aggiornamenti necessari. Ha rilevato la necessità di yt-dlp e pydub, entrambi già presenti.

Il risultato è un nuovo componente UI che consente di inserire un URL di YouTube. All’invio, l’app estrae l’audio e lo fa passare attraverso la pipeline esistente per la trascrizione. Tuttavia, le modifiche apportate a app.py non erano ancora sufficienti per eseguire l’intero codice senza errori.

Push delle modifiche su GitHub

Una volta completata e testata l’ottimizzazione di transcribe_audio, ho usato la CLI per versionare e fare push delle modifiche su GitHub.

Prompt: Crea un nuovo branch su GitHub e fai commit e push del codice aggiornato come seconda versione con il messaggio: "v2: Optimized transcribe_audio for memory usage".  

Qwen ha automatizzato l’intero flusso Git usando lo strumento WebFlow che aiuta a confrontare i file locali e quelli su GitHub. La CLI ha potuto svolgere più attività, dal branching al commit fino al push, senza passaggi manuali.

Qwen ha usato il suo strumento WebFetch per:

• Creare un nuovo branch
• Stagiare e fare commit delle modifiche
• Eseguire il push del commit
• Verificare l’aggiornamento remoto

Tutto fatto con un solo prompt. La versione aggiornata (v2-optimization) era isolata in sicurezza e disponibile per la revisione tramite pull request. Questa integrazione con GitHub ha reso semplice tracciare i miglioramenti, collaborare sugli aggiornamenti e mantenere una cronologia pulita delle versioni.

Ecco come appare il nuovo branch aggiornato:

Generazione di flowchart

Per visualizzare come interagiscono i vari moduli nel Voxtral Audio Assistant, ho chiesto a Qwen Code CLI di:

Prompt: Crea un flowchart che illustri le interazioni tra moduli. 

Qwen ha generato un dettagliato flowchart in Mermaid.js che mostra l’intera pipeline, dall’upload del file o input da YouTube, all’elaborazione tramite il modello Voxtral, fino all’output finale. Ha anche provato a incorporare il diagramma nel README.md del progetto.

Generare la documentazione 

Una volta completata l’ottimizzazione del codice, ho chiesto a Qwen Code CLI di aiutarmi a documentare le modifiche in un formato strutturato e professionale.

Prompt: Scrivi un riepilogo in Markdown delle modifiche apportate. Formattalo come una voce di changelog sotto "v0.2.0".     

Qwen ha usato il suo strumento WriteFile per aggiungere direttamente la voce a CHANGELOG.md sotto v0.2.0, seguendo le best practice del versioning semantico. Una volta avviato un task di changelog, Qwen lo ricorda ed evita aggiornamenti ridondanti, risparmiando token e prevenendo chiamate ripetitive agli strumenti.

Conclusione

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

• Comprendere e spiegare l’architettura di un codebase
• Applicare ottimizzazioni e miglioramenti mirati
• Generare ed eseguire unit test con minimo overhead
• Estendere le funzionalità con nuovi componenti come l’integrazione YouTube
• Automatizzare il controllo versione e i workflow GitHub
• Visualizzare i flussi di progetto e mantenere una documentazione pulita

Qwen Code CLI riduce in modo significativo il lavoro manuale necessario per comprendere, fare debug ed estendere un codebase. Pur traendo molto da Gemini CLI come base, Qwen Code introduce miglioramenti per i modelli Qwen3-Coder, come parser e supporto agli strumenti potenziati.

Ciò che mi ha colpito di più è la sua capacità di mantenere il contesto tra i task. Una volta assegnato un compito di changelog o un file da monitorare, Qwen lo ricorda ed evita ripetizioni. Inoltre delimita le modifiche con una sintassi come @file.py, rendendolo sicuro da usare in progetti di grandi dimensioni.

Se lavori con progetti Python complessi o mantieni repository open source, questo strumento può farti risparmiare ore di lavoro ripetitivo e rendere il tuo flusso più intelligente e iterativo.