CLI Reference - @koalarx/nest-cli

A CLI oficial da biblioteca @koalarx/nest facilita a criação de novos projetos estruturados automaticamente.

Instalação da CLI

npm install -g @koalarx/nest-cli

Requisitos:

• Node.js 20.18.0 ou superior

Comandos Disponíveis

Criar Novo Projeto

koala-nest new <nome-do-projeto>

Durante a criação, a CLI perguntará se você deseja instalar o MCP Server localmente.

Exemplos:

# Criar um projeto chamado "meu-app"
koala-nest new meu-app

# Entrar na pasta do projeto
cd meu-app

# Executar as migrations no banco de dados
bun run prisma:deploy

# Iniciar em modo desenvolvimento
bun run start:dev

Configurar MCP Server

Instalar/Configurar MCP Server

koala-nest mcp:install

Configura o arquivo mcp.json no seu projeto para usar o Koala Nest MCP Server via NPM. O servidor será instalado automaticamente pelo NPM quando você iniciar seu cliente MCP.

O que faz:

1. Procura por um arquivo mcp.json existente no projeto
2. Se encontrar, adiciona a configuração do Koala Nest
3. Se não encontrar, pergunta se deseja criar um novo
4. Configura com bunx @koalarx/mcp-server (sempre atualizado via NPM)

Configuração gerada:

{
  "mcpServers": {
    "koala-nest-docs": {
      "command": "bunx",
      "args": ["@koalarx/mcp-server"]
    }
  }
}

Verificar Atualizações

koala-nest check-updates

Verifica se há atualizações disponíveis para os pacotes Koala (@koalarx/nest e @koalarx/nest-cli) comparando com as versões no npm registry.

Opções:

• -p, --path <path> - Caminho do projeto para verificar (padrão: diretório atual)

Exemplo:

# Verificar atualizações no projeto atual
koala-nest check-updates

# Verificar atualizações em um projeto específico
koala-nest check-updates -p /caminho/para/projeto

O que a CLI Configura Automaticamente

Quando você cria um novo projeto com a CLI, ele inclui:

📁 Estrutura de Pastas

src/
├── host/                          # Camada de entrada
│   ├── app.module.ts              # Módulo principal
│   ├── main.ts                    # Ponto de entrada
│   └── controllers/               # Controladores
├── core/                          # Configuração central
│   ├── env.ts                     # Variáveis de ambiente
│   └── database/                  # Configuração do banco
├── application/                   # Lógica de aplicação
│   ├── handlers/                  # Command handlers
│   └── mapping/                   # AutoMapper profiles
├── domain/                        # Lógica de negócio
│   ├── entities/                  # Entidades
│   ├── repositories/              # Interfaces de repositório
│   ├── dtos/                      # Data Transfer Objects
│   └── services/                  # Serviços de domínio
├── infra/                         # Implementação técnica
│   ├── database/                  # Repositories concretos
│   ├── services/                  # Serviços técnicos
│   └── mappers/                   # Mapeadores
└── test/                          # Utilitários de teste

🛠️ Configuração Incluída

• ✅ Módulo KoalaNest - Configurado e pronto para uso
• ✅ Prisma ORM - Integrado com PostgreSQL
• ✅ Redis - Configurado para sincronização de background services
• ✅ Padrões de Autenticação - Templates para implementar Guards com JWT ou API Key
• ✅ Documentação Swagger/Scalar - API documentada automaticamente
• ✅ Tratamento de Erros - Filtros de exceção configurados
• ✅ Validação com Zod - Schema validation pronto
• ✅ Exemplo Prático - Entidade de exemplo (Pessoa) para referência

📦 Dependências Instaladas

# Core
@koalarx/nest
@nestjs/common
@nestjs/core
@nestjs/config
@nestjs/platform-express

# Banco de Dados
@prisma/client
prisma

# Autenticação
@nestjs/jwt
@nestjs/passport
passport-jwt

# Validação
zod

# Documentação
@nestjs/swagger
@scalar/nestjs-api-reference

# Utilitários
ioredis
dotenv
reflect-metadata

# Desenvolvimento
typescript
@types/node
ts-node
tsx

Próximos Passos Após Criar o Projeto

1. Configure as variáveis de ambiente (.env)

   # O arquivo .env já foi criado com valores padrão
   # Edite-o conforme necessário
   nano .env

2. Inicie o banco de dados (se usar PostgreSQL via Docker)

   # O projeto já vem com migrations de exemplo
   # Execute-as no banco de dados:
   bun run prisma:deploy

   ⚠️ Importante: O CLI não executa prisma:deploy automaticamente. Você precisa rodá-lo manualmente após configurar o banco de dados para aplicar as migrations e poder executar o projeto de demonstração.

3. Inicie a aplicação

   bun run start:dev

4. Acesse a documentação

   • Scalar UI: http://localhost:3000/doc
   • Swagger: http://localhost:3000/api

Exemplos de Uso

Criar um Projeto Simples

# Criar projeto
koala-nest new my-api
cd my-api

# Aplicar migrations de exemplo
bun run prisma:deploy

# Iniciar desenvolvimento
bun run start:dev

Seu projeto estará rodando em http://localhost:3000 com:

• Exemplo de entidade (Pessoa)
• Endpoints CRUD funcionais
• Autenticação JWT configurada
• Documentação interativa

Estrutura Gerada Exemplo

O projeto criado inclui:

• PersonController - Exemplo de controlador REST
• PersonService - Exemplo de serviço de domínio
• PersonRepository - Exemplo de repositório
• Migrations Prisma - Schema de exemplo para rodar

Troubleshooting

Node.js Versão Incompatível

# Verifique sua versão
node --version

# Você precisa da versão 20.18.0 ou superior
# Atualize node se necessário

Problemas com Permissões no Linux/Mac

# Se receber erro de permissão, use sudo
sudo npm install -g @koalarx/nest-cli

Limpar Cache de Instalação

npm cache clean --force
npm install -g @koalarx/nest-cli

Repositório da CLI

Para mais informações, contribuições ou reportar bugs:

• GitHub: koala-nest-cli
• NPM: @koalarx/nest-cli

Links Úteis

• Guia de Instalação - Mais detalhes sobre setup manual
• Configuração Inicial - Entender a estrutura criada
• Exemplo Prático - Aprender com exemplos completos e funcionando