@neetru/cli

Developer Kit oficial da Neetru — scaffolding, IA Neetru-aware, deploy de produtos SaaS, gestão de workspaces, bancos isolados por produto, e mais 40+ comandos pra operar todo o ecossistema Neetru via terminal.

Instalação

npm install -g @neetru/cli

Bootstrap completo da máquina dev (Node, gcloud, Docker, Firebase CLI, deps NPM, GCP ADC):

neetru bootstrap

Login no Core via OAuth Device Code Flow:

neetru login

Validar estado:

neetru doctor

Quickstart — criar produto SaaS novo

neetru new gestovendas --env=dev --tier=dev --customer=neetru

Cria produto + workspace + scaffold local Next.js 15 + instala deps + abre cockpit no browser.

Comandos principais

| Comando | O que faz | |---|---| | neetru bootstrap | Setup da máquina dev (binários + deps + ADC) | | neetru login / logout / whoami | Auth OAuth Device Code Flow | | neetru doctor | Diagnóstico saúde (5 checks rápidos) | | neetru new <slug> | Criar produto completo (registry + workspace + scaffold) | | neetru init <name> | Só scaffold local Next.js + Firebase | | neetru add <feature> | Adicionar features ao scaffold (auth, billing, etc) | | neetru deploy | Pipeline de deploy interativo (cloud-run / vm / workspace) | | neetru build | Empacotar produto em tarball pra deploy | | neetru promote | Promover dev → staging → prod | | neetru env switch <target> | Trocar NEETRU_ENV no .env.local | | neetru env set --service=X --set KEY=VAL | Setar env vars de serviço Cloud Run | | neetru ar create <name> | Criar repositório Artifact Registry | | neetru hosting create-mapping --service=X --domain=Y | Domain mapping | | neetru admin database create --product-id=X --engine=cloud-sql-postgres | Registrar banco isolado por produto (staff control plane) | | neetru admin database engines | Listar engines suportados (firestore-instance, cloud-sql-postgres, cloud-sql-mysql, vm-postgres-single, vm-mysql-single, nosql-vm, …) | | neetru db init / apply / migrations | Banco por produto no fluxo dev (registra + schema + migrations) | | neetru dev | Banco Docker local + watch de schema (salvar = aplicado) | | neetru dev up | Emulador local completo — Firebase Emulators + Core, 100% offline | | neetru dev exec <script> | Roda <script> com emuladores ativos (CI sem credencial cloud) | | neetru cloud-run pause/resume/delete <service> | Controle Cloud Run | | neetru products list/create/update | Registry de produtos | | neetru workspaces create/list/get/advance | Instâncias por cliente | | neetru deployments create/rollback | Histórico de deploys | | neetru tenants list/create/update/suspend | Gerenciar tenants | | neetru audit tail | Tail de audit_logs/ em tempo real | | neetru billing summary | Resumo de billing | | neetru servers list/provision/deactivate | Gerenciar servidores | | neetru agent release/yank/canary | Gerenciar releases do agente | | neetru support tickets list/reply/assign | Suporte inbox staff | | neetru dns zones list / hosting list | Listar DNS + customer domains | | neetru builds list | Listar Cloud Build | | neetru dr exports/restore | Disaster Recovery | | neetru logs | Ver logs de produtos | | neetru status | Visão geral do ecossistema | | neetru open <produto> | Abrir cockpit do produto no browser | | neetru ai | REPL IA Neetru-aware (Claude/OpenAI/Gemini) | | neetru ui | Menu interativo do CLI | | neetru publish | Publicar produto no catálogo público | | neetru upgrade | Auto-update do CLI | | neetru autocomplete <bash\|zsh\|pwsh> | Gerar script autocomplete |

Atalhos: neetru ar = artifact-registry, neetru menu = ui.

40+ subcomandos. Quase todos suportam --json pra automação.

Dev local — emulador (neetru dev up)

Ambiente de desenvolvimento 100% offline, estilo Firebase Emulator Suite — sem tocar GCP/staging:

# Na raiz do Core (onde tem firebase.json):
neetru dev up
#  → sobe Firebase Emulators (Firestore :8080, Auth :9099, Functions :5001)
#  → sobe o Core Next.js (:9003) apontando pros emuladores
#  → Ctrl-C encerra os dois em cascata

# Seed portátil (compartilhe o estado entre devs via git):
neetru dev up --import .neetru-dev/seed --export-on-exit .neetru-dev/seed

# Só os emuladores (sem o Core):
neetru dev up --skip-core

# CI / teste de integração sem credencial cloud (propaga o exit code do script):
neetru dev exec "npm run test:integration"

Contexto do projeto local:

# Projeto ligado a um produto já existente no Core:
neetru dev use --product meu-produto --sync

# Protótipo local ainda não cadastrado no Core:
neetru dev use --prototype meu-rascunho

# Ver o contexto efetivo que dev up/dev exec vão usar:
neetru dev status

# Sincronizar bancos dev-local do Core para .neetru/db.json:
neetru dev sync --write-db

neetru dev (sem subcomando) mantém o modo legado: banco Docker local + watch de schema. Flags: --only firestore,auth,functions, --core-port 9003, --core-path <dir>. O arquivo .neetru/dev.json guarda o contexto local: produto Core ou protótipo, Core path e emuladores padrão.

Configuração

Token Bearer fica em ~/.config/neetru-cli/auth.json (chmod 0600 em Unix, NTFS ACL em Windows) — gerado por neetru login via OAuth Device Code Flow. Configs gerais ficam em ~/.config/neetru-cli/config.json (Linux/macOS) ou %APPDATA%\neetru-cli\config.json (Windows):

| Chave | Valor | |---|---| | neetruApiUrl | URL base do Core (default https://api.neetru.com). Allowlist desde 2.11.0: *.neetru.com + localhost; demais hosts exigem --allow-untrusted-url | | defaultModel | claude / openai / gemini / auto (REPL neetru ai) | | telemetry.enabled | Telemetry opt-in (default false) — desde 2.11.0 emite eventos anônimos pra /api/sdk/v1/telemetry/log | | neetruApiKey | (legado) Token em Conf — substituído por auth.json. Será removido em 2.12.0 |

neetru config set telemetry.enabled true
neetru config get neetruApiUrl
neetru config path           # mostra caminho do config file
neetru config set neetruApiUrl https://staging.neetru.com   # subdomínio neetru.com — OK
neetru config set neetruApiUrl http://my-proxy.local --allow-untrusted-url   # explicit opt-in

Output JSON

neetru products list --json | jq '.[] | select(.status == "ativo")'
neetru audit tail --json | jq 'select(.action | startswith("billing"))'

Auth & Segurança

• OAuth Device Code Flow (RFC 8628) pra login interativo — não armazena password
• Tokens salvos em ~/.config/neetru-cli/auth.json (chmod 0600 em Unix, NTFS ACL em Windows). Desde 2.11.0 o resolver canônico (getActiveTokenSync) prefere esse arquivo sobre o Conf storage legado (que será removido em 2.12.0)
• URL allowlist (desde 2.11.0): neetruApiUrl rejeita hosts fora de *.neetru.com + localhost sem --allow-untrusted-url — fecha vetor de exfiltração do Bearer token
• Rate-limit por método HTTP: GET 120/min, POST/PUT/PATCH 30/min, DELETE 5/min
• Step-up MFA (TOTP) obrigatório em operações destrutivas: --mfa-token <code> ou prompt
• Dry-run disponível em comandos de mutação: --dry-run mostra efeito SEM aplicar
• Telemetry opt-in (desde 2.11.0): habilitando telemetry.enabled=true o CLI emite {command, durationMs, ok, exitCode} anônimo via installId UUID. Zero token/path/email/env vazam

Stack

• TypeScript 5 ESM-first
• Node 20+ (engines.node: >=20; Node 22 LTS recomendado)
• Sem node-fetch/axios: fetch global nativo
• Commander 12 (CLI framework) + Inquirer 10 (prompts) + Chalk 5 + Ora (spinners)

Mais info

• Repo: github.com/Neetru/neetru-core
• Docs: docs.neetru.com
• SDK complementar: npm install @neetru/sdk
• Issues / suporte: abrir issue no repo ou neetru support

Licença

MIT © Neetru