---
name: coolify-operator
description: Operador mestre do Coolify para plataforma self-hosted de deployment. Use quando o usuário mencionar 'coolify', 'deploy no coolify', 'listar/reiniciar/redeploy aplicações', 'ver logs coolify', 'API/CLI coolify', 'gerenciar servidores/databases/apps coolify', ou 'coolify context'. Automatiza deployments e gerenciamento via API REST ou CLI oficial.
metadata:
  author: ft.ia.br
  version: "1.1"
  date: 2026-03-08
  license: MIT
---

# Coolify Operator

Skill para operar instâncias Coolify através da **API REST** ou **CLI oficial**. Coolify é uma plataforma self-hosted open-source alternativa ao Heroku/Vercel/Netlify para deploy de aplicações, databases e serviços.

## Quando usar este skill

- Conectar em instâncias Coolify (via API ou CLI)
- Listar e gerenciar aplicações, serviços, databases e servidores
- Fazer deploy, restart ou stop de aplicações
- Ver logs e status de deployments
- Gerenciar variáveis de ambiente
- Operar múltiplas instâncias Coolify (contexts)
- Troubleshooting de conexão com Coolify

## Conceitos fundamentais

### Autenticação

**API REST:**
- Endpoint base: `https://SEU-HOST/api/v1` (sempre com `/api/v1` no final)
- Autenticação: `Authorization: Bearer SEU_TOKEN`
- Token obtido em: Coolify Dashboard → Keys & Tokens → API Tokens

**CLI:**
- Instala contextos que armazenam HOST + TOKEN
- HOST no contexto é SEM `/api/v1` (só a URL base)
- CLI adiciona `/api/v1` automaticamente

### Configuração com pipe no token

⚠️ **IMPORTANTE**: Tokens do Coolify frequentemente contêm `|` (ex: `3|abc123...`). Nunca use `source .env` pois isso quebra no shell.

**Leitura segura do .env:**
```bash
COOLIFY_KEY=$(sed -n 's/^COOLIFY_KEY=//p' .env)
COOLIFY=$(sed -n 's/^COOLIFY=//p' .env)
```

**Formato esperado no .env:**
```bash
COOLIFY_KEY=3|abc123def456...
COOLIFY=http://192.168.1.XXX:8000/api/v1
```

### UUIDs

Coolify usa UUIDs para identificar recursos:
- Applications: `app-uuid`
- Servers: `server-uuid`
- Databases: `db-uuid`
- Services: `service-uuid`

## Operações com CLI

### Setup inicial

```bash
# Ler token do .env de forma segura
COOLIFY_KEY=$(sed -n 's/^COOLIFY_KEY=//p' .env)

# Adicionar contexto (URL SEM /api/v1)
coolify context add -d -f meu-coolify http://192.168.1.XXX:8000 "$COOLIFY_KEY"

# Usar o contexto
coolify context use meu-coolify

# Verificar conexão
coolify context verify

# Ver versão da API
coolify context version
```

### Gerenciamento de contextos

```bash
# Listar contextos
coolify context list

# Adicionar múltiplos contextos
coolify context add prod https://prod.coolify.io "$PROD_TOKEN" --default
coolify context add staging https://staging.coolify.io "$STAGING_TOKEN"
coolify context add dev https://dev.coolify.io "$DEV_TOKEN"

# Trocar contexto padrão
coolify context use staging

# Usar contexto específico em um comando
coolify --context=prod app list

# Atualizar token de um contexto
coolify context set-token prod new-token-here

# Remover contexto
coolify context delete dev
```

### Operações com applications

```bash
# Listar todas as aplicações
coolify app list

# Ver detalhes de uma aplicação
coolify app get <uuid>

# --- LIFECYCLE ---
# Iniciar (deploy) aplicação
coolify app start <uuid>

# Parar aplicação
coolify app stop <uuid>

# Reiniciar aplicação
coolify app restart <uuid>

# --- LOGS ---
# Ver logs da aplicação
coolify app logs <uuid>

# --- VARIÁVEIS DE AMBIENTE ---
# Listar variáveis de ambiente
coolify app env list <uuid>

# Criar variável de ambiente
coolify app env create <uuid> --key API_KEY --value secret123

# Sincronizar variáveis de arquivo .env
coolify app env sync <uuid> --file .env
coolify app env sync <uuid> --file .env.production --build-time --preview
```

### Operações com servers

```bash
# Listar servidores
coolify server list

# Ver detalhes de um servidor (incluindo recursos)
coolify server get <uuid> --resources

# Adicionar novo servidor (com validação)
coolify server add myserver 192.168.1.100 <key-uuid> --validate
```

### Operações com team

```bash
# Listar teams disponíveis
coolify team list

# Ver team atual
coolify team current

# Listar membros do team
coolify team members list
```

### Flags globais

```bash
# Especificar contexto
coolify --context <name> ...

# Override do host
coolify --host <fqdn> ...

# Token direto (bypassa contexto)
coolify --token <token> ...

# Formato de saída (table, json, pretty)
coolify --format json ...

# Mostrar dados sensíveis
coolify -s ...
coolify --show-sensitive ...

# Forçar operação
coolify -f ...
coolify --force ...

# Debug mode
coolify --debug ...
```

## Operações com API REST

### Autenticação e teste

```bash
# Ler credenciais do .env de forma segura
COOLIFY_KEY=$(sed -n 's/^COOLIFY_KEY=//p' .env)
COOLIFY=$(sed -n 's/^COOLIFY=//p' .env)

# Testar conexão
curl -sS -i \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/version"

# Resultado esperado: HTTP 200 + {"version": "4.0.0-beta.xxx"}
```

### Applications

```bash
# Listar aplicações
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/applications"

# Ver detalhes de aplicação
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/applications/{uuid}"

# Iniciar (deploy) aplicação
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/applications/{uuid}/start"

# Flags query params:
# ?force=true          - Force rebuild
# ?instant_deploy=true - Skip queue

# Parar aplicação
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/applications/{uuid}/stop"

# Reiniciar aplicação
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/applications/{uuid}/restart"

# Response exemplo:
# {
#   "message": "Restart request queued.",
#   "deployment_uuid": "doogksw"
# }
```

### Deployments

```bash
# Listar todos os deployments em andamento
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/deployments"

# Listar deployments de uma aplicação (com paginação)
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/deployments/applications/{uuid}?skip=0&take=10"
```

### Servers

```bash
# Listar servidores
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/servers"

# Ver detalhes de servidor
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/servers/{uuid}"
```

### Databases

```bash
# Listar databases
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/databases"

# Iniciar database
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/databases/{uuid}/start"

# Parar database
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/databases/{uuid}/stop"

# Reiniciar database
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/databases/{uuid}/restart"
```

### Services

```bash
# Reiniciar serviço
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/services/{uuid}/restart"

# Query params:
# ?latest=true - Pull latest images

# Response:
# {"message": "Service restaring request queued."}
```

## Troubleshooting

### Erro: 403 "You are not allowed to access the API"

**Causa:** Token inválido ou sem permissão para a instância.

**Solução:**
1. Pedir para o usuário validar na instância em <URL_DA_INSTANCIA>/settings/advanced se a API está ativada e com o IP do cliente liberado
2. Regenerar token em: Dashboard → Keys & Tokens → API Tokens
3. Atualizar `.env` ou contexto CLI
4. Verificar que está usando a instância correta

### Erro: 401 "Unauthenticated"

**Causa:** Header de autenticação incorreto ou token não enviado.

**Solução:**
```bash
# Verificar que está usando Bearer (não só "Token")
Authorization: Bearer SEU_TOKEN

# CLI: verificar contexto
coolify context verify
```

### Erro: 404 no context verify

**Causa:** URL do contexto CLI está incorreta (provavelmente com `/api/v1` no lugar errado).

**Solução:**
```bash
# CLI context deve ter URL SEM /api/v1
coolify context add meu-coolify http://192.168.1.XXX:8000 "$TOKEN"

# API direta deve ter URL COM /api/v1
COOLIFY=http://192.168.1.XXX:8000/api/v1
```

### Túnel Cloudflare não é a causa

Se a API já retorna JSON válido do Coolify (mesmo que seja erro de auth), o túnel Cloudflare está funcionando. O problema é autenticação, não conexão.

### Token com pipe (|) quebra shell

```bash
# ❌ ERRADO - quebra com pipe
source .env

# ✅ CORRETO - leitura segura
COOLIFY_KEY=$(sed -n 's/^COOLIFY_KEY=//p' .env)
```

## Workflows comuns

### Deploy completo de nova aplicação

```bash
# 1. Conectar no Coolify
coolify context add prod https://coolify.seu-dominio.com "$TOKEN" --default
coolify context verify

# 2. Listar servidores disponíveis
coolify server list

# 3. Fazer deploy (via dashboard UI ou API)
# Nota: criação de apps é melhor via UI, API é para operações

# 4. Listar as apps para pegar UUID
coolify app list

# 5. Iniciar a aplicação
coolify app start <uuid>

# 6. Ver logs do deploy
coolify app logs <uuid>
```

### Redeploy com force rebuild

```bash
# Via CLI
coolify app restart <uuid>

# Via API com rebuild forçado
curl -sS \
  -H "Authorization: Bearer $COOLIFY_KEY" \
  "$COOLIFY/applications/{uuid}/start?force=true"
```

### Atualizar variáveis de ambiente

```bash
# Opção 1: Sincronizar de arquivo
coolify app env sync <uuid> --file .env.production

# Opção 2: Criar individual
coolify app env create <uuid> --key API_URL --value https://api.exemplo.com
coolify app env create <uuid> --key API_KEY --value secret123

# 3. Restart para aplicar mudanças
coolify app restart <uuid>
```

### Monitoramento multi-ambiente

```bash
# Produção
coolify --context=prod app list
coolify --context=prod app logs <prod-app-uuid>

# Staging
coolify --context=staging app list
coolify --context=staging app logs <staging-app-uuid>

# Development
coolify --context=dev app list
coolify --context=dev server list
```

## Recursos importantes

### Estrutura de resposta da API

**Application:**
```json
{
  "id": 123,
  "uuid": "app-uuid-123",
  "name": "minha-app",
  "fqdn": "app.exemplo.com",
  "status": "running",
  "git_repository": "https://github.com/user/repo",
  "git_branch": "main",
  "git_commit_sha": "abc123",
  "build_pack": "nixpacks",
  "ports_exposes": "3000",
  "health_check_enabled": true,
  "environment_id": 1,
  "destination_id": 1
}
```

**Server:**
```json
{
  "id": 1,
  "uuid": "server-uuid-123",
  "name": "servidor-principal",
  "ip": "192.168.1.100",
  "user": "root",
  "port": 22,
  "settings": {
    "is_reachable": true,
    "is_usable": true,
    "concurrent_builds": 1
  }
}
```

**Deployment:**
```json
{
  "id": 456,
  "uuid": "deployment-uuid-456",
  "status": "finished",
  "deployment_uuid": "dep-123",
  "application_id": 123
}
```

## Dicas de uso

1. **Sempre verificar UUIDs**: Use `coolify app list` ou API para confirmar UUIDs antes de operações
2. **Contextos para multi-ambiente**: Configure um contexto para cada ambiente (dev/staging/prod)
3. **Logs em tempo real**: Use `coolify app logs <uuid>` durante deploys
4. **Force rebuild quando necessário**: `?force=true` no start garante rebuild completo
5. **Segurança do token**: Nunca commitar tokens. Use `.env` com `.gitignore`
6. **Formato JSON para scripts**: Use `--format json` no CLI para parsear com `jq`

## Quality Checklist

Antes de executar qualquer operação, verificar:

- [ ] Arquivo `.env` presente com `COOLIFY_KEY` e `COOLIFY` corretos
- [ ] Token lido de forma segura (usando `sed` ou método adequado, não `source`)
- [ ] Contexto correto selecionado (`coolify context use <nome>`)
- [ ] Conexão verificada (`coolify context verify`)
- [ ] UUIDs confirmados antes de operações destrutivas
- [ ] Endpoint URL correto (API tem `/api/v1`, contexto CLI não tem)
- [ ] Headers de autenticação incluídos em chamadas API (`Authorization: Bearer <token>`)
- [ ] Tratamento de erros implementado (401, 403, 404, 500)
- [ ] Logs consultados em caso de falha de deploy
- [ ] Operações críticas (delete, stop) executadas com confirmação

## Referências

- **Documentação oficial**: https://coolify.io/docs
- **API Reference**: https://coolify.io/docs/api-reference
- **CLI GitHub**: https://github.com/coollabsio/coolify-cli
- **Coolify Core**: https://github.com/coollabsio/coolify