Interfaces de linha de comando (CLIs) são ferramentas essenciais no dia a dia de desenvolvedores. Elas automatizam tarefas, integram serviços e compõem pipelines. Com agentes de IA, criar uma CLI completa em Node.js se torna um processo rápido e estruturado. Neste tutorial, você vai aprender a construir uma CLI Node.js com agentes de IA usando Claude Code e Codex — do parser de argumentos ao deploy no npm.
O que vamos construir
Vamos desenvolver o TaskCLI, uma ferramenta de linha de comando para gerenciamento de tarefas com as seguintes funcionalidades:
- Adicionar, listar, completar e remover tarefas
- Categorias e prioridades
- Armazenamento local em JSON
- Exportação para CSV e Markdown
- Cores e formatação no terminal
- Comandos aninhados com subcomandos
Imagem sugerida: Terminal mostrando a CLI em ação com comandos coloridos, tabela de tarefas e exemplos de uso.
Setup e arquitetura com Claude Code
Vamos usar Claude Code para configurar a estrutura base da CLI.
Inicialização do projeto
mkdir task-cli cd task-cli npm init -y
Peça ao Claude Code para configurar o projeto:
claude "Configure um projeto Node.js CLI com TypeScript para uma ferramenta de linha de comando de gerenciamento de tarefas. Instale as dependências: commander (parser de argumentos), chalk (cores no terminal), inquirer (prompts interativos), conf (configuração persistente), ora (spinners), cli-table3 (tabelas no terminal), nanoid (IDs únicos). Instale devDependencies: @types/node, typescript, ts-node, jest, @types/jest. Crie tsconfig.json com strict mode. Estrutura de pastas: src/commands, src/handlers, src/utils, src/types, tests/. Configure o entry point como src/index.ts com shebang #!/usr/bin/env node."
Claude Code configura tudo — dependências, TypeScript, estrutura de pastas — em segundos.
Sistema de comandos com Claude Code
Claude Code é ideal para estruturar o sistema de comandos da CLI usando Commander.js.
Program principal
claude "Crie src/index.ts com o programa Commander principal: 1. Nome: task-cli, descrição: 'Task Manager CLI', versão do package.json 2. Comandos: add, list, complete, delete, export, config 3. Global options: --json (saída JSON), --no-color (desativa cores), -v (verbose) 4. Help customizado com exemplos de uso 5. Error handling global: comandos inexistentes mostram sugestões, erros de parse mostram ajuda"
Comandos específicos
Peça ao Claude Code para criar cada comando individualmente:
claude "Crie src/commands/add.ts com o comando 'task-cli add': - Argumento: <title> (obrigatório, descrição da tarefa) - Options: --priority (-p) [low|medium|high|critical], --category (-c) [string], --due (-d) [date] - Deve chamar handler addTask com os argumentos parseados - Exemplos: task-cli add 'Comprar leite', task-cli add 'Estudar TypeScript' -p high -c estudos"
claude "Crie src/commands/list.ts com o comando 'task-cli list': - Options: --status (-s) [todo|done|all], --category (-c) [string], --priority (-p) [string], --sort [date|priority|status] - Exibe tabela formatada com chalk e cli-table3 - Colunas: ID (curto), Título, Prioridade (colorida), Categoria, Status, Data - Suporta --json para saída JSON pura"
claude "Crie src/commands/export.ts com subcomandos:
- task-cli export csv <output-file>: exporta para CSV
- task-cli export markdown <output-file>: exporta para Markdown
- task-cli export json <output-file>: exporta para JSON
Use o handler exportTasks com o formato apropriado"
Handlers e utilitários com Codex
Codex brilha na geração de código padronizado como handlers e utilitários.
Handlers de tarefas
opencode "Crie src/handlers/taskHandler.ts com as funções: 1. addTask(title, options): cria tarefa com nanoid, salva no arquivo JSON, retorna tarefa criada 2. listTasks(filters): lê tarefas do arquivo, aplica filtros (status, categoria, prioridade), ordena 3. completeTask(id): marca tarefa como concluída, registra data de conclusão 4. deleteTask(id): remove tarefa do arquivo 5. exportTasks(format, outputPath): exporta tarefas no formato especificado Use a função readTasks e writeTasks de src/utils/storage.ts. Valide dados com Zod."
Storage utilitário
opencode "Crie src/utils/storage.ts com: 1. TASKS_FILE: path para ~/.task-cli/tasks.json 2. ensureDir(): cria diretório ~/.task-cli se não existir 3. readTasks(): lê e faz parse do JSON, retorna array de tarefas (array vazio se arquivo não existe) 4. writeTasks(tasks): serializa e escreve array no arquivo JSON com indentação 2 5. getStats(): retorna estatísticas (total, concluídas, pendentes, por prioridade) Use fs.promises (async/await) e path do Node.js. Trate erros de permissão e disco cheio."
Tipos e validação
opencode "Crie src/types/task.ts com interfaces TypeScript:
- Priority: 'low' | 'medium' | 'high' | 'critical'
- TaskStatus: 'todo' | 'done'
- Task: { id, title, priority, category, status, dueDate?, createdAt, completedAt? }
- TaskFilters: { status?, category?, priority?, sort? }E src/utils/validation.ts com schemas Zod: createTaskSchema, updateTaskSchema, exportOptionsSchema"
Testes da CLI
Testar uma CLI requer ferramentas específicas. Vamos gerar testes com Codex e Claude Code.
Testes unitários
opencode "Crie tests/handlers/taskHandler.test.ts: 1. addTask: deve criar tarefa com dados válidos, deve lançar erro se título vazio 2. listTasks: deve retornar lista vazia se nenhuma tarefa, deve filtrar por status, deve ordenar por prioridade 3. completeTask: deve marcar tarefa como done, deve lançar erro se ID não existe 4. deleteTask: deve remover tarefa, deve lançar erro se ID não existe Use mocks para as funções de storage."
Testes de integração
opencode "Crie tests/cli.integration.test.ts testando a CLI real: 1. Executar task-cli add 'teste' e verificar saída contém 'Tarefa adicionada' 2. Executar task-cli list e verificar tarefa aparece na lista 3. Executar task-cli complete <id> e verificar status mudou 4. Executar task-cli export json output.json e verificar arquivo foi criado 5. Executar task-cli sem argumentos e verificar help aparece Use execSync do child_process para executar a CLI."
Empacotamento e publicação no npm
Vamos usar Claude Code para preparar a CLI para publicação.
claude "Configure o package.json para publicação:
1. Bin: { 'task-cli': './dist/index.js' }
2. Scripts: build (tsc), prepublish (npm run build), dev (ts-node src/index.ts)
3. Adicione "preferGlobal": true
4. Crie .npmignore: src/, tests/, tsconfig.json, .env
5. Crie README.md com: instalação (npm install -g task-cli), uso, comandos, exemplos, configuração"
Sua CLI Node.js com agentes de IA está pronta para ser instalada com npm install -g task-cli.
FAQ — Perguntas Frequentes
Preciso saber Node.js para criar uma CLI com agentes de IA?
Sim. Embora os agentes gerem a maior parte do código, você precisa entender argumentos de linha de comando, pipes, exit codes e streams para revisar e depurar.
Qual agente usar para criar uma CLI: Claude Code ou Codex?
Claude Code é melhor para arquitetura geral e sistema de comandos. Codex é mais rápido para parsers, templates de saída e testes.
A CLI gerada por IA funciona no Windows, macOS e Linux?
Sim, desde que você use APIs nativas do Node.js sem dependências específicas de SO. Evite comandos shell diretamente.
Como publicar uma CLI gerada por IA no npm?
O Claude Code pode configurar o package.json com bin, criar README e gerar o fluxo de publish. Execute npm publish após revisar.
Dá para orquestrar Claude Code e Codex na mesma CLI?
Sim. Com o Orquestra, Claude Code cria o sistema de comandos enquanto Codex gera handlers e testes. Tudo em paralelo no mesmo canvas.
Construa sua CLI com agentes hoje
Neste tutorial, você aprendeu a construir uma CLI Node.js com agentes de IA usando Claude Code e Codex. Do parser de argumentos ao deploy no npm, cada etapa foi acelerada pelos agentes.
Quer levar essa orquestração para o próximo nível? O Orquestra conecta Claude Code, Codex e outros agentes no mesmo canvas infinito no Windows 11. Baixe o Orquestra e comece seu teste grátis de 7 dias.
Links internos recomendados
- APIs REST com Agentes de IA — crie uma API para sua CLI consumir
- TypeScript React com Agentes de IA — tutorial complementar de TypeScript
- Testes Automatizados com Agentes de IA — aprofunde-se em testes de CLI
Pronto para orquestrar seus agentes?
Baixe o Orquestra para Windows 11 e comece a coordenar seus agentes de IA em um canvas infinito. Grátis por 7 dias.