CLI do Qwen Code: Um guia com exemplos

A Alibaba lançou o Qwen3-Coder, um modelo de codificação agênte disponível em vários tamanhos, sendo a variante mais forte o Qwen3-Coder-480B-A35B-Instruct. Junto com esses modelos, a Alibaba disponibilizou em código abertoo Qwen Code CLI, uma ferramenta de linha de comando para codificação agênica.

O Qwen Code CLI é um fork do Gemini CLI e foi adaptado especialmente para usar com o modelo Qwen3-Coder em tarefas de codificação agênica.

Neste blog, vou explicar passo a passo como configurar e usar o Qwen Code CLI. Vamos usar isso pra explorar bases de código, refatorar código e muito mais.

A gente mantém nossos leitores atualizados sobre as últimas novidades em IA enviando o The Median, nosso boletim informativo gratuito às sextas-feiras, que traz as principais notícias da semana. Inscreva-se e fique por dentro em só alguns minutos por semana:

O que é o Código Qwen?

Qwen Code é uma interface de linha de comando feita pra facilitar tarefas de codificação de agentes. Ele usa prompts personalizados e protocolos de chamada de função otimizados para o Qwen3-Coder. Com o Qwen Code, você pode:

• Navegue e entenda bases de código complexas
• Detectar e corrigir problemas de codificação
• Gerar código e testes unitários
• Criar documentação e fluxogramas

Fonte: QwenLM

Agora, vamos configurar o Qwen3-Coder e usá-lo para explorar e corrigir problemas em um projeto de código aberto no qual trabalhei recentemente.

Passo 1: O que você precisa saber antes de começar

Antes de configurar o Qwen Code, certifique-se de que o Node.js (versão 20 ou superior) está instalado. Você pode instalar o Node.js executando:

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

Depois, dá uma olhada na instalação executando o seguinte:

node -v
npm -v

Passo 2: Configurando o Qwen Code

Nesta etapa, vamos ver várias opções para instalar e autenticar o Qwen Code no nosso dispositivo.

Passo 2.1: Instalação via npm

Com o Node.js instalado, configura o Qwen Code globalmente e dá uma olhada na versão instalada também:

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

Esse código instala o Qwen Code CLI globalmente usando o gerenciador de pacotes do Node.js. Depois de instalar, o comando qwen --version dá uma olhada e mostra a versão instalada do Qwen CLI pra garantir que tá tudo certo e pronto pra usar.

Vamos rodar o Qwen Code:

qwen

Clique em Enter para escolher o tema padrão e aplicar nas configurações do usuário. Depois, precisamos configurar a autenticação.

Passo 2.2: Instalação a partir do código-fonte (opcional)

Se preferir, você pode instalar o Qwen Code direto do repositório GitHub deles:

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

Esse código clona o repositório GitHub do Qwen Code CLI para o seu computador usando o comando ` git clone `. Depois, a gente vai pro diretório clonado e instala todas as dependências do projeto que estão no repositório, no arquivo “ package.json ”. 

Observação: -g significa que está disponível em todo o sistema, não só no diretório do projeto local.

Passo 2.3: Autenticação

A CLI precisa de uma chave API do Qwen 3 Coder pra autenticação. A documentação oficial diz que você pode se autenticar pedindo uma chave API em https://bailian.console.aliyun.com/ ( se você estiver na China continental).  Se você não estiver na China continental, acesse https://modelstudio.console.alibabacloud.com/ para solicitar sua chave API.

Mas, se você mora na Índia, essas opções não estão disponíveis pra você. Em vez disso, você pode escolher o OpenRouter, que dá aos usuários acesso a várias chaves API para vários modelos. Aqui estão os passos para configurar uma chave API para o Qwen 3 Coder com ela:

• Crie uma conta em https://openrouter.ai/
• Vá até a aba Modelos e procure por “Qwen 3 Coder”. Você pode escolher uma versão gratuita se precisar de menos de 128k tokens, caso contrário, escolha a versão paga (US$ 0,302/M tokens de entrada e saída).

• Desça a página e clique em Criar chave API. Preencha o nome da chave e o limite de crédito (opcional) e clique em Criar. Guarde essa chave API pra usar depois. 

• Depois, dá uma olhada na aba Créditos e adiciona os dados do teu cartão ou conta bancária. Você também pode pagar com o Amazon Pay. Pra essa demonstração, eu adicionei cerca de US$ 15, o que foi suficiente.

Passo 2.4: Configurando o ambiente

Agora dá pra usar a chave API na CLI. Volta para a CLI a partir da etapa 2.1 e clica em Enter.

Depois, passa a chave API da etapa anterior, seguida da URL base e do nome do modelo, como mostrado abaixo:

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

Se quiser, você também pode configurar essas variáveis como variáveis de ambiente. Abra um novo terminal e execute a seguinte linha por linha.

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 você estiver usando uma chave API da Alibaba Cloud, configure suas variáveis de ambiente da seguinte maneira:

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"

Depois de definir essas variáveis de ambiente, clique em Enter e você poderá começar a experimentar a CLI.

Passo 3: Experimentando o Qwen Code CLI

Nesta seção, vou mostrar como usei o Qwen Code CLI pra interagir com um projeto real hospedado no GitHub. Com só algumas dicas, o Qwen me ajudou a entender o código, otimizar funções, adicionar novos recursos, automatizar testes e manter a documentação.

Usando dicas bem pensadas, consegui:

• Analisar a arquitetura da base de código
• Otimize funções específicas para eficiência de memória
• Gerar e rodar testes unitários automaticamente
• Aumente a funcionalidade integrando novos componentes
• Envie atualizações com versão para o GitHub
• Crie um fluxograma visual das interações entre os módulos.
• Documente todas as alterações em um formato de registro de alterações estruturado.

Vamos ver cada uma dessas etapas.

Explorando e entendendo a base de código

Vamos começar pedindo ao Qwen Code para dar uma olhada e explicar como é a arquitetura do código. Mas, primeiro, clona o repositório do GitHub e vai até a pasta do projeto usando o seguinte comando:

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

Aqui tá o prompt que usei pra entender o repositório clonado:

Prompt:  Explica a arquitetura dessa base de código.

O Qwen CLI verificou arquivos como app.py, config.py, requirements.txt e um notebook Colab. Depois, ele me mostrou uma descrição clara da estrutura do projeto junto com um resumo geral dos principais módulos, poupando o tempo que eu levaria pra abrir e ler cada arquivo manualmente.

Reestruturação e otimização do código

Depois de entender a arquitetura, usei o Qwen Code CLI pra analisar áreas que poderiam ser melhoradas no código.

Prompt: Que partes deste módulo podem ser melhoradas?

O Qwen trouxe uma lista organizada de sugestões em várias áreas: desempenho, eficiência de memória, facilidade de manutenção e experiência do usuário. Ele não só identificou problemas, mas também sugeriu mudanças no código que podem ser feitas.

Seguindo as orientações, consegui:

• Dá uma reduzida no uso da memória e da CPU
• Melhorar o tratamento de erros
• Melhorar o feedback dos usuários
• Simplificar a estrutura do código para o desenvolvimento futuro

Na próxima etapa, vou mostrar como apliquei uma dessas otimizações (uso de memória) e testei usando o próprio Qwen CLI.

Implementando e testando a otimização do código

Depois de ver várias áreas que podiam ser melhoradas, decidi tentar uma das sugestões mais legais: melhorar o uso da memória na função “ transcribe_audio ”. Então, eu pedi pro Qwen CLI pegar aquele arquivo específico aqui embaixo:

Prompt: Otimiza o uso da memória na função transcribe_audio em @app.py

Qwen focou só no app.py usando a sintaxe @ para edições com escopo. Essa segmentação precisa é útil quando você quer que as alterações sejam aplicadas de forma isolada, sem afetar partes não relacionadas do código-base. A CLI reescreveu a função para:

1. Transmita e processe trechos de áudio em vez de carregar tudo na memória
2. Dá uma reduzida nas atualizações da interface do usuário atualizando a barra de progresso só a cada 10 blocos.
3. Tira a necessidade de calcular antes o número total de pedaços.

Ele também atualizou automaticamente o arquivo CHANGELOG.md pra mostrar essa melhoria com uma nova tag de versão.

Gerando e executando testes

Depois que a otimização do uso da memória foi aplicada à função “ transcribe_audio ”, usei o Qwen Coder CLI para gerar e validar automaticamente os testes de unidade para a nova implementação.

Prompt: Escreva um teste de unidade pytest para as alterações recentes.

Qwen começou verificando a estrutura do projeto pra ver se tinha um diretório de teste e se pytest estava listado em requirements.txt. Como os dois estavam faltando, isso:

• Adicionado pytest>=7.0.0 a requirements.txt
• Criei um novo diretório chamado “ tests/ ”.
• Gerou um módulo de teste: tests/test_transcribe_audio.py

Qwen fez os testes e confirmou que todos os quatro foram aprovados. Para manter um histórico de versões claro, Qwen também adicionou uma nova entrada “Corrigido” em CHANGELOG.md na versão v0.2.0.

Com só um comando, o Qwen CLI gerou testes automaticamente, identificou casos extremos, ajudou a corrigir um bug de lógica e garantiu que o código estava certo com uma validação bem rigorosa.

Implementando um novo componente

Pra dar mais funcionalidade pro Voxtral Audio Assistant (codebase), pedi pro Qwen Code CLI integrar suporte pra vídeos do YouTube.

Prompt: Aumente o exemplo atual pra dar suporte a vídeos do YouTube. Quando alguém te passa um link do YouTube, pega o áudio do vídeo e manda pro modelo Voxtral pra ele processar. Mantenha o resto do pipeline e os componentes como estão.

O objetivo era permitir que os usuários inserissem um URL do YouTube além de enviar arquivos de áudio. Depois de fornecido, o aplicativo deve extrair automaticamente o áudio do vídeo e processá-lo como um upload de arquivo normal, sem modificar o pipeline downstream para transcrição ou perguntas e respostas. 

A Qwen deu uma olhada em app.py, config.py e requirements.txt pra ver quais atualizações eram necessárias. Reconheceu a necessidade de incluir “ yt-dlp ” e “ pydub ”, ambos já listados.

Por isso, adicionamos um novo componente à interface do usuário, que permite que você insira um URL do YouTube. Depois de enviado, o app pega o áudio e manda pro pipeline que já existe pra transcrever. Mas, as mudanças feitas em app.py ainda não foram suficientes pra rodar todo o código sem erros.

Enviando alterações para o GitHub

Depois que a otimização do transcribe_audio ficou pronta e testada, usei a CLI pra versionar e enviar as mudanças pro GitHub.

Prompt: Crie um novo branch no GitHub e faça o commit e o push do código atualizado como uma segunda versão com a mensagem: “v2: Otimizamos o transcribe_audio pra usar menos memória.  

Qwen automatizou todo o fluxo do Git usando a ferramenta WebFlow, que ajuda a comparar arquivos locais e hospedados no GitHub. A CLI podia fazer várias coisas, desde ramificar até confirmar e enviar, sem precisar de passos manuais.

A Qwen usou a ferramenta “ WebFetch ” para:

• Criar um novo ramo
• Prepare e confirme as alterações
• Envie o commit
• Confira se a atualização remota deu certo.

Tudo feito com um único comando. A versão atualizada (v2-optimization) foi isolada com segurança e está disponível para revisão por meio de solicitação pull. Essa integração com o GitHub facilitou o acompanhamento das melhorias, a colaboração nas atualizações e a manutenção de um histórico de versões organizado.

Aqui tá como tá a nova ramificação atualizada:

Criação de fluxogramas

Pra visualizar como os diferentes módulos do Voxtral Audio Assistant interagem, pedi pro Qwen Code CLI fazer o seguinte:

: Crie um fluxograma que mostre como os módulos interagem. 

Qwen fez um fluxograma detalhado do fluxo de trabalho ( Mermaid.js ) mostrando todo o processo, desde o upload do arquivo ou a entrada do YouTube, passando pelo processamento pelo modelo Voxtral, até a saída final. Tentou até colocar o diagrama no README.md do projeto.

Gerando documentação 

Depois que a otimização do código ficou pronta, pedi pro Qwen Code CLI ajudar a documentar as mudanças de um jeito estruturado e profissional.

Prompt: Escreva um resumo em Markdown das alterações feitas. Formate como uma entrada de registro de alterações em “v0.2.0”.     

A Qwen usou a ferramenta WriteFile para adicionar a entrada diretamente em CHANGELOG.md em v0.2.0, seguindo as melhores práticas de versionamento semântico. Depois que uma tarefa do changelog é iniciada, o Qwen lembra dela e evita atualizações desnecessárias, economizando tokens e evitando chamadas repetidas da ferramenta.

Conclusão

Resumindo, este tutorial mostrou como o Qwen Code CLI pode ser usado para:

• Entender e explicar a arquitetura de uma base de código
• Aplique otimizações e melhorias direcionadas
• Crie e execute testes unitários com o mínimo de esforço
• Aumente a funcionalidade com novos componentes, como integração com o YouTube.
• Automatize o controle de versão e os fluxos de trabalho do GitHub
• Visualize os fluxos do projeto e mantenha a documentação organizada

O Qwen Code CLI reduz bastante o trabalho manual necessário para entender, depurar e ampliar uma base de código. Embora seja muito parecido com o Gemini CLI, o Qwen Code traz melhorias para os modelos Qwen3-Coder, como um analisador melhorado e suporte a ferramentas.

O que mais me impressionou foi a capacidade de manter o contexto entre as tarefas. Depois de atribuir uma tarefa de changelog ou um arquivo para monitorar, o Qwen lembra disso e evita repetições. Ele também define o escopo das alterações usando uma sintaxe como “ @file.py ”, o que torna seu uso seguro em projetos grandes.

Se você está trabalhando com projetos Python complexos ou mantendo repositórios de código aberto, essa ferramenta pode economizar horas de trabalho repetitivo e tornar seu fluxo de trabalho mais inteligente e iterativo.