Pare de Configurar Seu Ambiente Manualmente: Como Transformei Scripts em uma CLI Reutilizável

O problema que todo dev ignora (até virar dor)

Existe um tipo de problema que quase todo desenvolvedor aceita como “parte do jogo”:

• configurar ambiente
• instalar dependências
• alinhar versões
• resolver conflitos

E isso sempre acontece nos mesmos momentos:

nova máquina  
novo projeto  
novo time

O problema não é só o tempo gasto.

É o efeito acumulado:

❌ inconsistência entre ambientes  
❌ onboarding lento  
❌ erros difíceis de reproduzir

Esse é o tipo de problema que parece pequeno — até começar a escalar.

A primeira solução (e por que ela não resolve)

Como muitos, comecei com scripts.

Scripts em Python para:

• instalar ferramentas
• configurar o sistema
• preparar ambiente

Funcionava.

Mas tinha um problema estrutural:

scripts automatizam tarefas  
mas não organizam complexidade

Com o tempo, comecei a perceber:

❌ difícil de manter  
❌ difícil de reutilizar  
❌ difícil de evoluir

Eu estava automatizando — mas ainda estava preso ao problema.

A mudança de mentalidade: de tarefas para ambientes

O ponto de virada não foi técnico.

Foi conceitual.

Antes:

instalar python  
instalar node  
instalar banco

Depois:

ambiente backend  
ambiente frontend  
ambiente fullstack

Essa mudança desbloqueou a solução.

A evolução para um CLI

Ao invés de scripts soltos, criei um CLI:

devsetup system
devsetup python
devsetup node

Mas o ganho real veio com a camada de orquestração.

🧠 Profiles: a abstração que resolve o problema real

devsetup profile backend

Esse comando representa:

um ambiente completo  
não uma sequência de comandos

🏗️ Arquitetura do sistema

Separação clara de responsabilidades:

core        → execução e validação  
installers  → lógica de instalação  
profiles    → orquestração  
config      → configuração externa

O problema que ainda existia

Mesmo com profiles:

eles eram hardcoded

Ou seja:

❌ sem customização  
❌ sem reutilização entre projetos  
❌ sem flexibilidade

A virada: config-driven architecture

A solução foi simples — e poderosa:

Mover a definição do ambiente para fora do código.

📦 .devsetup.toml

[profile.backend]
tools = ["system", "git", "python", "node", "java", "postgres"]

[node]
version = 22

[python]
version = "3.12"

Agora o CLI não “decide” mais.

Ele executa o que está declarado.

🔄 Fluxo de execução

🧪 Uso na prática

cp examples/backend.toml .devsetup.toml
devsetup profile backend

👉 ambiente pronto

Engenharia por trás (o que não aparece)

Esse tipo de ferramenta só funciona bem com disciplina:

• validação de configuração
• tratamento de erro claro
• fallback inteligente
• testes automatizados
• lint + formatação
• CI/CD

Sem isso, vira só um script grande.

Trade-offs reais

Nenhuma decisão é neutra.

📦 Uso de apt

✔ simples ✔ direto ❌ não portátil

🔐 Uso de sudo

✔ necessário ❌ não funciona em todos os contextos

🐧 Foco em WSL/Linux

✔ pragmático ✔ reduz complexidade

Lições aprendidas

1. Automatizar não é suficiente

Organizar a abstração é o que importa.

2. O nome das coisas importa

“profile” é melhor que “script”.

3. Configuração > código (em certos contextos)

Flexibilidade vem da separação.

4. Ferramentas internas devem ser tratadas como produto

Isso inclui:

• testes
• pipeline
• distribuição
• documentação

Quando isso faz sentido

• onboarding de times
• ambientes padronizados
• ensino técnico
• múltiplos stacks

Quando não faz

• projetos simples
• setups descartáveis

O que esse projeto realmente é

Não é só um CLI.

É:

uma forma de modelar ambientes de desenvolvimento

Conclusão

Esse projeto evoluiu de:

scripts → CLI → profiles → config-driven

Mas o verdadeiro avanço foi:

de tarefas → para ambientes  
de execução → para declaração

Repositório

👉 https://github.com/sobraljhonata/dev-setup-cli