@perma-tools/cli

🚀 CLI moderna e interativa para geração rápida de projetos frontend e backend com configurações personalizadas.

📦 Instalação

Uso com npx (Recomendado - sem instalação)

npx @perma-tools/cli@latest

Instalação Global

npm install -g @perma-tools/cli
# ou
pnpm add -g @perma-tools/cli
# ou
yarn global add @perma-tools/cli

🚀 Uso Rápido

Modo Interativo

npx @perma-tools/cli@latest

A CLI irá guiá-lo através de perguntas interativas para configurar seu projeto.

Modo CLI com Flags

npx @perma-tools/cli@latest \
  --name meu-app \
  --type frontend \
  --framework nextjs-15 \
  --http-client ky \
  --linter biome \
  --libs tanstack-query,zod,react-hook-form \
  --with-shadcn \
  --shadcn-color slate \
  --install

✨ Características

• ✅ Suporte completo para Frontend (NextJS 15) e Backend (em desenvolvimento)
• ✅ Escolha entre ky, axios ou fetch nativo como cliente HTTP
• ✅ Configuração automática de Biome ou ESLint + Prettier
• ✅ Instalação e configuração de bibliotecas populares com versões específicas testadas
• ✅ Integração completa com shadcn/ui
• ✅ Sistema de providers com injeção automática robusta
• ✅ Criação automática de repositório no GitHub com GitHub CLI
• ✅ Deploy automático na Vercel para projetos frontend
• ✅ Instalação automática de dependências
• ✅ Validação completa de nomes de projetos (seguindo regras do npm)
• ✅ Verificação de projetos existentes para evitar sobrescritas
• ✅ Compatibilidade total com Windows, Linux e macOS

🚀 Git & Deploy Automático

A CLI oferece configuração automática de repositório e deploy, adaptando-se automaticamente às ferramentas disponíveis no seu sistema:

Pré-requisitos

• GitHub CLI (gh): Instalar e autenticar
  • Obrigatório para criação de repositórios
  • Se não estiver instalado, a opção de Git setup será ocultada
• Vercel CLI (opcional): npm i -g vercel && vercel login
  • Necessário apenas para deploy automático
  • Se não estiver instalado, apenas a opção "criar repo" será mostrada

Detecção Automática de Ferramentas

A CLI detecta automaticamente quais ferramentas estão instaladas e ajusta as opções disponíveis:

| GitHub CLI | Vercel CLI | Opções Mostradas | |------------|------------|------------------| | ✅ Instalado | ✅ Instalado | Repo + Deploy, Repo only, Nenhum | | ✅ Instalado | ❌ Não instalado | Repo only, Nenhum | | ❌ Não instalado | ✅/❌ Qualquer | Nenhum (pula essa etapa) |

Comportamento inteligente:

• Se você não tem GitHub CLI, a CLI pula completamente a configuração de Git
• Se você só tem GitHub CLI, mostra apenas a opção de criar repositório
• Se você tem ambas e é um projeto frontend, mostra todas as opções

Opções Disponíveis

1. Criar repo e deploy na Vercel: Cria repositório no GitHub e configura deploy automático (frontend apenas, requer ambas CLIs)
2. Apenas criar repo: Cria repositório no GitHub sem deploy (requer apenas GitHub CLI)
3. Não configurar agora: Pula a configuração (pode fazer manualmente depois)

Criação em Organizações

A CLI detecta automaticamente suas organizações do GitHub e permite escolher onde criar o repositório:

• Perfil Pessoal: github.com/seu-usuario/repo
• Organização: github.com/sua-org/repo

Se você tiver acesso a múltiplas organizações, poderá selecioná-las interativamente.

Como Funciona

Após criar o projeto, a CLI:

• 🔧 Inicializa o repositório Git local
• 📍 Pergunta onde criar (perfil pessoal ou organização)
• 🏢 Lista suas organizações do GitHub (se aplicável)
• 📦 Cria repositório no GitHub (público ou privado)
• 🚀 Faz push do código inicial
• ⏳ Aguarda o GitHub processar o repositório (3 segundos)
• ⚡ Configura deploy na Vercel (se selecionado)

# A CLI faz tudo isso automaticamente:
git init
git add .
git commit -m "chore: initial commit from @perma-tools/cli"
gh repo create my-org/my-repo --public --source . --push  # Com org
# ou
gh repo create my-repo --public --source . --push  # Perfil pessoal
vercel --prod --yes  # Se deploy estiver habilitado

🏗️ Estrutura do Projeto Gerado

Providers e Client Components

Quando você seleciona bibliotecas que usam Context API (TanStack Query, nuqs, etc.), a CLI:

1. Cria um arquivo src/app/providers.tsx com a diretiva 'use client'
2. Injeta automaticamente os providers necessários
3. Mantém a estrutura aninhada corretamente

'use client';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <>
      <QueryClientProvider>
        <NuqsAdapter>
          {children}
        </NuqsAdapter>
      </QueryClientProvider>
    </>
  );
}

Por que 'use client'?
Providers que usam hooks do React (useState, useContext, etc.) precisam ser Client Components no Next.js 15.

📄 Licença

MIT