# `runner wizard` (CLI) — v2.17.0+

Wizard interativo de linha de comando para gerar .deploy.yml (e opcionalmente .runner/secrets.enc) a partir do que ja existe no repositorio. Funciona em qualquer cenario:

• Repositorio cru (so README) — constroi do zero
• Repositorio com Dockerfile — pre-preenche image/port
• Repositorio com docker-compose.yml — detecta multi-service e pergunta qual e o app principal
• Repositorio com .env/.env.example — extrai vars e classifica secrets automaticamente

Existe versao web tambem: se voce ainda nao instalou o runner em nenhum servidor, use o Wizard Web — formulario guiado de 10 passos no navegador, gera o mesmo .deploy.yml. Diferenca: a versao web nao detecta arquivos do repo automaticamente; voce responde tudo manualmente. A versao CLI tem deteccao + multi-service compose + geracao de secrets.enc.

# Quando usar

# Sintaxe

runner wizard [OPTIONS]

# Opcoes

# `--answers` schema (v2.18.0+)

{
  "project": "middleware-241",
  "system": "api",
  "type": "docker-build",
  "port": 5000,
  "image": "php:8.3-fpm",
  "instance": "production",
  "instance_branch": "dev",
  "instance_domain": "app.example.com",
  "keep_versions": 3,
  "healthcheck_mode": "http",
  "healthcheck_path": "/health",
  "env_overrides": {
    "APP_ENV": "production",
    "APP_DEBUG": "false"
  },
  "skip_env": ["AWS_*", "MAIL_*", "MEMCACHED_*"],
  "secret_keys": ["DB_PASSWORD", "JWT_SECRET"],
  "non_secret_keys": ["LOG_LEVEL"]
}

Todos os campos sao opcionais. Combina com auto-deteccao: detection roda primeiro, answers sobrescrevem os campos providos. Util para IA/CI gerar manifestos validos sem TTY.

# Exemplos

# Wizard interativo padrao

runner wizard --path /tmp/meu-repo

Inicia conversa pergunta-a-pergunta. Saida final:

━━━ Runner Deploy Wizard ━━━
  repo_dir: /tmp/meu-repo
  detectado: linguagem=python
  detectado: type sugerido=sys
  detectado: Dockerfile (EXPOSE 5000)
  detectado: 5 env pairs

? Slug do projeto: meu-repo
? Sistema: sys
? Tipo de deploy: sys
? Imagem: python:3.12-slim
? Port: 5000
...

━━━ Preview do .deploy.yml ━━━
  project: meu-repo
  system: sys
  ...

  🔒 2 secrets serao encriptados:
    - DB_PASSWORD
    - JWT_SECRET

? Confirma e salva? [Y/n]

# Repo remoto

runner wizard --repo devborlot/meu-app --branch main --token ghp_xxx

# Forcar geracao com defaults (CI)

runner wizard --path . --accept-defaults --json

Sem perguntas. Aceita todos os defaults da deteccao. Util em scripts.

# Dry-run para inspecao

runner wizard --path . --accept-defaults --dry-run --json

Mostra o YAML que seria gerado sem escrever nada. Combinacao perfeita para validar ou debug.

# Gerar com ckey explicita

runner wizard --path . --ckey "minha-ckey-segura"

Ou random:

runner wizard --path . --ckey

A ckey gerada e mostrada uma unica vez no fim. Anote.

# O que o wizard detecta

# Linguagem e tipo

* docker-build apenas se houver Dockerfile; senão sys.

A detecção de Laravel busca laravel/framework ou laravel/laravel no composer.json e analisa routes/api.php/routes/fasttrack.php + resources/views/ (v2.18.0+).

# Imagem e porta

# Variaveis de ambiente

Extraidas de:

1. docker-compose.yml services (lista ou mapa)
2. Dockerfile ENV
3. .env, .env.example, .env.template (na ordem)

Para cada variavel, o wizard pergunta:

• manter como esta (default para nao-secrets)
• editar valor
• marcar como secret (encriptar) — vai pra secrets:
• remover

# Deteccao de secrets

Chaves contendo: PASSWORD, TOKEN, SECRET, PRIVATE, JWT, API_KEY, APIKEY, ACCESS_KEY, AWS_SECRET, DB_PASS, REDIS_PASS, MYSQL_PASS, POSTGRES_PASS sao automaticamente sugeridas como secrets.

# Curadoria de `.env.example` — Perfil de Producao (v2.18.0+)

Quando o wizard detecta valores tipicos de dev no .env.example:

Em modo interativo, o wizard pergunta antes de aplicar. Em --accept-defaults ou --answers, aplica silenciosamente.

Pruning automatico de placeholders comuns vazios (sem perguntar): AWS_*, MAIL_*, MEMCACHED_*, PUSHER_*, VITE_PUSHER_*, PUSHER_APP_*. Evita poluir o manifesto com dezenas de chaves vazias do template Laravel/outros frameworks.

Motivacao: APP_DEBUG=true em producao expõe stacktrace e variaveis sensiveis em paginas de erro — vetor real de leak.

# Multi-service docker-compose

Se o docker-compose.yml tem multiplos services, o wizard precisa saber qual e o app principal (1 repo = 1 container no Runner):

⚠ Compose tem 3 services; preciso saber qual e o app principal:
  ? App principal:
    > api (python:3.12-slim)
      worker (python:3.12-slim)
      redis (redis:7) [asset]

Services como redis, postgres, mysql, mongo, rabbitmq, etc. sao automaticamente marcados como [asset]. Apos a escolha, o wizard mostra:

⚠ services nao incluidos (assets provaveis):
    - redis
    - postgres
    → use deployally ou rode-os manualmente fora do CI/CD

⚠ services nao incluidos (parecem outras apps):
    - worker
    → cada app extra precisa de um `runner add` separado

# Auto-trigger no `runner add`

Em modo interativo (TTY, sem --json), runner add chama o wizard automaticamente quando o repo nao tem .deploy.yml e nao tem Dockerfile/docker-compose:

$ runner add --repo user/repo-sem-deploy --branch main
[runner] Cloning shallow...

⚠ Repositorio sem perfil de deploy detectado.
  motivo: no_deploy_profile: repo sem perfil de deploy detectado.
? Executar wizard interativo agora? [Y/n] y

━━━ Runner Deploy Wizard ━━━
...
✔ Wizard concluido. Continuando o registro...

Em pipe/script (--json ou stdin nao-TTY), o add falha direto com mensagem instrutiva — sem travar em prompt.

# Arquivos gerados

<repo_dir>/
├── .deploy.yml              # Configuracao de deploy
└── .runner/
    └── secrets.enc          # Bundle encriptado (so se houver secrets literais)

.runner/secrets.enc usa o mesmo formato que o Runner ja decifra:

• Algoritmo: AES-256-GCM
• Chave: SHA-256(ckey)
• Layout binario: [12 bytes nonce][N bytes ciphertext]
• Plaintext interno: ---ENV---\n\n---SECRETS---\n{KEY=VALUE\n}*

# Proximos passos

Apos o wizard:

# 1) Commit no repo
git add .deploy.yml .runner/secrets.enc
git commit -m "chore: add runner deploy config"
git push

# 2) No servidor com runner instalado
runner add --repo user/repo --branch main --ckey "<sua-ckey>"

# Subcomando relacionado: `runner template`

Inspeciona o template embutido (mesmo schema do wizard web):

runner template            # listagem human
runner template --json     # schema parseado
runner template --raw      # YAML cru

Use para verificar quais campos o wizard pede em sua versao instalada — util para debug e para sincronizar o web wizard.

# Ver tambem

• generator de .deploy.yml — geracao automatica nao-interativa (perfis A-D)
• Wizard web — versao browser, mesmo schema
• Secrets e encriptacao — como o .secrets.enc e usado no deploy