coolify

name	coolify
description	Manage Coolify deployments, applications, databases, and services via the Coolify API. Use when the user wants to deploy, start, stop, restart, or manage applications hosted on Coolify.
homepage	https://coolify.io
repository	https://github.com/visiongeist/coolifycli
user-invocable	true
metadata	{"clawdbot":{"emoji":"🚀","requires":{"bins":["node"],"env":["COOLIFY_TOKEN","COOLIFY_API_URL"]},"primaryEnv":"COOLIFY_TOKEN"}}

Coolify API Skill

Repository: github.com/visiongeist/coolifycli

Comprehensive management of Coolify deployments, applications, databases, services, and infrastructure via the Coolify API.

When to Use This Skill

Use this skill when the user needs to:

• Deploy applications to Coolify
• Manage application lifecycle (start, stop, restart)
• View application logs
• Create and manage databases (PostgreSQL, MySQL, MongoDB, Redis, etc.)
• Deploy Docker Compose services
• Manage servers and infrastructure
• Configure environment variables
• Trigger and monitor deployments
• Manage GitHub App integrations
• Configure SSH private keys

Prerequisites

1. Coolify API Token — Generate from Coolify dashboard:

   • Navigate to Keys & Tokens → API tokens
   • Create token with appropriate permissions (read, write, deploy)
   • Set COOLIFY_TOKEN environment variable

2. Coolify API URL (Optional) — For self-hosted instances:

   • Set COOLIFY_API_URL environment variable (default: https://app.coolify.io/api/v1)
   • Example: export COOLIFY_API_URL="https://your-coolify.com/api/v1"

3. Node.js 20+ — Required for running the CLI

4. API Access — Coolify Cloud (app.coolify.io) or self-hosted instance

Quick Start

Basic Commands

# List all applications
{baseDir}/dist/coolify-cli.cjs applications list

# Get application details
{baseDir}/dist/coolify-cli.cjs applications get --uuid abc-123

# Deploy an application
{baseDir}/dist/coolify-cli.cjs deploy --uuid abc-123 --force

# View application logs
{baseDir}/dist/coolify-cli.cjs applications logs --uuid abc-123

# Restart an application
{baseDir}/dist/coolify-cli.cjs applications restart --uuid abc-123

---

Applications

List Applications

{baseDir}/dist/coolify-cli.cjs applications list

Output:

{
  "success": true,
  "data": [
    {
      "uuid": "abc-123",
      "name": "my-app",
      "status": "running",
      "fqdn": "https://app.example.com"
    }
  ],
  "count": 1
}

Get Application Details

{baseDir}/dist/coolify-cli.cjs applications get --uuid abc-123

Application Lifecycle

# Start
{baseDir}/dist/coolify-cli.cjs applications start --uuid abc-123

# Stop
{baseDir}/dist/coolify-cli.cjs applications stop --uuid abc-123

# Restart
{baseDir}/dist/coolify-cli.cjs applications restart --uuid abc-123

View Logs

{baseDir}/dist/coolify-cli.cjs applications logs --uuid abc-123

Environment Variables

# List environment variables
{baseDir}/dist/coolify-cli.cjs applications envs list --uuid abc-123

# Create environment variable
{baseDir}/dist/coolify-cli.cjs applications envs create \
  --uuid abc-123 \
  --key DATABASE_URL \
  --value "postgres://user:pass@host:5432/db" \
  --is-runtime true \
  --is-buildtime false

# Update environment variable
{baseDir}/dist/coolify-cli.cjs applications envs update \
  --uuid abc-123 \
  --env-uuid env-456 \
  --value "new-value"

# Bulk update environment variables
{baseDir}/dist/coolify-cli.cjs applications envs bulk-update \
  --uuid abc-123 \
  --json '{"DATABASE_URL":"postgres://...","API_KEY":"..."}'

# Delete environment variable
{baseDir}/dist/coolify-cli.cjs applications envs delete \
  --uuid abc-123 \
  --env-uuid env-456

Create Applications

# Public Git repository
{baseDir}/dist/coolify-cli.cjs applications create-public \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --git-repository "https://github.com/user/repo" \
  --git-branch main \
  --name "My App"

# Private GitHub App
{baseDir}/dist/coolify-cli.cjs applications create-private-github-app \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --github-app-uuid gh-789 \
  --git-repository "user/repo" \
  --git-branch main

# Dockerfile
{baseDir}/dist/coolify-cli.cjs applications create-dockerfile \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --dockerfile-location "./Dockerfile" \
  --name "My Docker App"

# Docker Image
{baseDir}/dist/coolify-cli.cjs applications create-dockerimage \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --docker-image "nginx:latest" \
  --name "Nginx"

# Docker Compose
{baseDir}/dist/coolify-cli.cjs applications create-dockercompose \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --docker-compose-location "./docker-compose.yml"

---

Databases

List Databases

{baseDir}/dist/coolify-cli.cjs databases list

Get Database Details

{baseDir}/dist/coolify-cli.cjs databases get --uuid db-123

Database Lifecycle

# Start
{baseDir}/dist/coolify-cli.cjs databases start --uuid db-123

# Stop
{baseDir}/dist/coolify-cli.cjs databases stop --uuid db-123

# Restart
{baseDir}/dist/coolify-cli.cjs databases restart --uuid db-123

# Delete
{baseDir}/dist/coolify-cli.cjs databases delete --uuid db-123

Create Databases

# PostgreSQL
{baseDir}/dist/coolify-cli.cjs databases create-postgresql \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-postgres" \
  --postgres-user admin \
  --postgres-password secret \
  --postgres-db myapp

# MySQL
{baseDir}/dist/coolify-cli.cjs databases create-mysql \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-mysql"

# MariaDB
{baseDir}/dist/coolify-cli.cjs databases create-mariadb \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-mariadb"

# MongoDB
{baseDir}/dist/coolify-cli.cjs databases create-mongodb \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-mongo"

# Redis
{baseDir}/dist/coolify-cli.cjs databases create-redis \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-redis"

# KeyDB
{baseDir}/dist/coolify-cli.cjs databases create-keydb \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-keydb"

# ClickHouse
{baseDir}/dist/coolify-cli.cjs databases create-clickhouse \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-clickhouse"

# Dragonfly
{baseDir}/dist/coolify-cli.cjs databases create-dragonfly \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "my-dragonfly"

Backups

# List backup configurations
{baseDir}/dist/coolify-cli.cjs databases backups list --uuid db-123

# Create backup configuration
{baseDir}/dist/coolify-cli.cjs databases backups create \
  --uuid db-123 \
  --frequency "0 2 * * *" \
  --enabled true

# Get backup details
{baseDir}/dist/coolify-cli.cjs databases backups get \
  --uuid db-123 \
  --backup-uuid backup-456

# Update backup
{baseDir}/dist/coolify-cli.cjs databases backups update \
  --uuid db-123 \
  --backup-uuid backup-456 \
  --frequency "0 3 * * *"

# Trigger manual backup
{baseDir}/dist/coolify-cli.cjs databases backups trigger \
  --uuid db-123 \
  --backup-uuid backup-456

# List backup executions
{baseDir}/dist/coolify-cli.cjs databases backups executions \
  --uuid db-123 \
  --backup-uuid backup-456

# Delete backup configuration
{baseDir}/dist/coolify-cli.cjs databases backups delete \
  --uuid db-123 \
  --backup-uuid backup-456

---

Services (Docker Compose)

List Services

{baseDir}/dist/coolify-cli.cjs services list

Get Service Details

{baseDir}/dist/coolify-cli.cjs services get --uuid service-123

Service Lifecycle

# Start
{baseDir}/dist/coolify-cli.cjs services start --uuid service-123

# Stop
{baseDir}/dist/coolify-cli.cjs services stop --uuid service-123

# Restart
{baseDir}/dist/coolify-cli.cjs services restart --uuid service-123

# Delete
{baseDir}/dist/coolify-cli.cjs services delete --uuid service-123

Create Service

{baseDir}/dist/coolify-cli.cjs services create \
  --project-uuid proj-123 \
  --server-uuid server-456 \
  --name "My Service" \
  --docker-compose '{"version":"3.8","services":{"web":{"image":"nginx"}}}'

Environment Variables

# List
{baseDir}/dist/coolify-cli.cjs services envs list --uuid service-123

# Create
{baseDir}/dist/coolify-cli.cjs services envs create \
  --uuid service-123 \
  --key API_KEY \
  --value "secret"

# Update
{baseDir}/dist/coolify-cli.cjs services envs update \
  --uuid service-123 \
  --env-uuid env-456 \
  --value "new-secret"

# Bulk update
{baseDir}/dist/coolify-cli.cjs services envs bulk-update \
  --uuid service-123 \
  --json '{"API_KEY":"secret","DB_HOST":"localhost"}'

# Delete
{baseDir}/dist/coolify-cli.cjs services envs delete \
  --uuid service-123 \
  --env-uuid env-456

---

Deployments

Deploy Application

# Deploy by UUID
{baseDir}/dist/coolify-cli.cjs deploy --uuid abc-123

# Force rebuild
{baseDir}/dist/coolify-cli.cjs deploy --uuid abc-123 --force

# Deploy by tag
{baseDir}/dist/coolify-cli.cjs deploy --tag production

# Instant deploy (skip queue)
{baseDir}/dist/coolify-cli.cjs deploy --uuid abc-123 --instant-deploy

List Deployments

# List all running deployments
{baseDir}/dist/coolify-cli.cjs deployments list

# List deployments for specific application
{baseDir}/dist/coolify-cli.cjs deployments list-for-app --uuid abc-123

Get Deployment Details

{baseDir}/dist/coolify-cli.cjs deployments get --uuid deploy-456

Cancel Deployment

{baseDir}/dist/coolify-cli.cjs deployments cancel --uuid deploy-456

---

Servers

List Servers

{baseDir}/dist/coolify-cli.cjs servers list

Get Server Details

{baseDir}/dist/coolify-cli.cjs servers get --uuid server-123

Create Server

{baseDir}/dist/coolify-cli.cjs servers create \
  --name "Production Server" \
  --ip "192.168.1.100" \
  --port 22 \
  --user root \
  --private-key-uuid key-456

Update Server

{baseDir}/dist/coolify-cli.cjs servers update \
  --uuid server-123 \
  --name "Updated Name" \
  --description "Production environment"

Validate Server

{baseDir}/dist/coolify-cli.cjs servers validate --uuid server-123

Get Server Resources

# List all resources on server
{baseDir}/dist/coolify-cli.cjs servers resources --uuid server-123

# Get domains configured on server
{baseDir}/dist/coolify-cli.cjs servers domains --uuid server-123

Delete Server

{baseDir}/dist/coolify-cli.cjs servers delete --uuid server-123

---

Projects

List Projects

{baseDir}/dist/coolify-cli.cjs projects list

Get Project Details

{baseDir}/dist/coolify-cli.cjs projects get --uuid proj-123

Create Project

{baseDir}/dist/coolify-cli.cjs projects create \
  --name "My Project" \
  --description "Production project"

Update Project

{baseDir}/dist/coolify-cli.cjs projects update \
  --uuid proj-123 \
  --name "Updated Name"

Delete Project

{baseDir}/dist/coolify-cli.cjs projects delete --uuid proj-123

Environments

# List environments
{baseDir}/dist/coolify-cli.cjs projects environments list --uuid proj-123

# Create environment
{baseDir}/dist/coolify-cli.cjs projects environments create \
  --uuid proj-123 \
  --name "staging"

# Get environment details
{baseDir}/dist/coolify-cli.cjs projects environments get \
  --uuid proj-123 \
  --environment staging

# Delete environment
{baseDir}/dist/coolify-cli.cjs projects environments delete \
  --uuid proj-123 \
  --environment staging

---

Teams

List Teams

{baseDir}/dist/coolify-cli.cjs teams list

Get Current Team

{baseDir}/dist/coolify-cli.cjs teams current

Get Team Members

{baseDir}/dist/coolify-cli.cjs teams members

Get Team by ID

{baseDir}/dist/coolify-cli.cjs teams get --id 1

---

Security (Private Keys)

List Private Keys

{baseDir}/dist/coolify-cli.cjs security keys list

Get Private Key

{baseDir}/dist/coolify-cli.cjs security keys get --uuid key-123

Create Private Key

{baseDir}/dist/coolify-cli.cjs security keys create \
  --name "Production Key" \
  --description "SSH key for production servers" \
  --private-key "$(cat ~/.ssh/id_rsa)"

Update Private Key

{baseDir}/dist/coolify-cli.cjs security keys update \
  --uuid key-123 \
  --name "Updated Key Name"

Delete Private Key

{baseDir}/dist/coolify-cli.cjs security keys delete --uuid key-123

---

GitHub Apps

List GitHub Apps

{baseDir}/dist/coolify-cli.cjs github-apps list

Get GitHub App

{baseDir}/dist/coolify-cli.cjs github-apps get --uuid gh-123

Create GitHub App

{baseDir}/dist/coolify-cli.cjs github-apps create \
  --name "My GitHub App" \
  --app-id 123456 \
  --installation-id 789012 \
  --private-key "$(cat github-app-key.pem)"

Update GitHub App

{baseDir}/dist/coolify-cli.cjs github-apps update \
  --uuid gh-123 \
  --name "Updated App Name"

Delete GitHub App

{baseDir}/dist/coolify-cli.cjs github-apps delete --uuid gh-123

List Repositories

{baseDir}/dist/coolify-cli.cjs github-apps repos --uuid gh-123

List Branches

{baseDir}/dist/coolify-cli.cjs github-apps branches \
  --uuid gh-123 \
  --owner myorg \
  --repo myrepo

---

Common Use Cases

Deploy a New Application

1. List available servers:

   {baseDir}/dist/coolify-cli.cjs servers list
   

2. Create application:

   {baseDir}/dist/coolify-cli.cjs applications create-public \
     --project-uuid proj-123 \
     --server-uuid server-456 \
     --git-repository "https://github.com/user/repo" \
     --git-branch main \
     --name "My App"
   

3. Configure environment variables:

   {baseDir}/dist/coolify-cli.cjs applications envs create \
     --uuid <new-app-uuid> \
     --key DATABASE_URL \
     --value "postgres://..." \
     --is-runtime true
   

4. Deploy:

   {baseDir}/dist/coolify-cli.cjs deploy --uuid <new-app-uuid>
   

Set Up Database with Backups

1. Create database:

   {baseDir}/dist/coolify-cli.cjs databases create-postgresql \
     --project-uuid proj-123 \
     --server-uuid server-456 \
     --name "production-db"
   

2. Configure daily backups:

   {baseDir}/dist/coolify-cli.cjs databases backups create \
     --uuid <db-uuid> \
     --frequency "0 2 * * *" \
     --enabled true
   

3. Trigger manual backup:

   {baseDir}/dist/coolify-cli.cjs databases backups trigger \
     --uuid <db-uuid> \
     --backup-uuid <backup-uuid>
   

Monitor Application Health

1. Check application status:

   {baseDir}/dist/coolify-cli.cjs applications get --uuid abc-123
   

2. View recent logs:

   {baseDir}/dist/coolify-cli.cjs applications logs --uuid abc-123
   

3. List recent deployments:

   {baseDir}/dist/coolify-cli.cjs deployments list-for-app --uuid abc-123
   

---

Troubleshooting

"API token not configured"

Cause: COOLIFY_TOKEN environment variable not set.

Solution:

export COOLIFY_TOKEN="your-token-here"

Or configure in Clawdbot config at ~/.clawdbot/clawdbot.json:

{
  "skills": {
    "entries": {
      "coolify": {
        "apiKey": "your-token-here"
      }
    }
  }
}

"Rate limit exceeded"

Cause: Too many API requests in a short time.

Solution: The client automatically retries with exponential backoff. Wait for the retry or reduce request frequency.

"Application not found"

Cause: Invalid or non-existent UUID.

Solution:

# List all applications to find correct UUID
{baseDir}/dist/coolify-cli.cjs applications list

"connect ECONNREFUSED"

Cause: Cannot connect to Coolify API.

Solution for self-hosted:

# Set custom API URL
export COOLIFY_API_URL="https://your-coolify.example.com/api/v1"

Solution for cloud: Verify internet connection and that app.coolify.io is accessible.

"Deployment failed"

Cause: Build or deployment error.

Solution:

1. Check deployment logs:

   {baseDir}/dist/coolify-cli.cjs deployments get --uuid deploy-456
   

2. Check application logs:

   {baseDir}/dist/coolify-cli.cjs applications logs --uuid abc-123
   

3. Verify environment variables are correct:

   {baseDir}/dist/coolify-cli.cjs applications envs list --uuid abc-123
   

Node.js Not Found

Cause: Node.js not installed or not in PATH.

Solution:

# macOS (via Homebrew)
brew install node

# Verify installation
node --version

---

Output Format

All commands return structured JSON:

Success Response

{
  "success": true,
  "data": { ... },
  "count": 42
}

Error Response

{
  "success": false,
  "error": {
    "type": "APIError",
    "message": "Application not found",
    "hint": "Use 'applications list' to find valid UUIDs"
  }
}

---

Configuration

Environment Variables

Variable	Required	Default	Description
COOLIFY_TOKEN	Yes	—	API token from Coolify dashboard
COOLIFY_API_URL	No	https://app.coolify.io/api/v1	API base URL (for self-hosted)

Self-Hosted Coolify

For self-hosted instances, set the API URL:

export COOLIFY_API_URL="https://coolify.example.com/api/v1"
export COOLIFY_TOKEN="your-token-here"

---

Additional Resources

• This Skill Repository: https://github.com/visiongeist/coolifycli
• Coolify Documentation: https://coolify.io/docs/
• API Reference: See {baseDir}/references/API.md
• Coolify GitHub: https://github.com/coollabsio/coolify
• Coolify Discord: https://coollabs.io/discord

---

Edge Cases and Best Practices

UUID vs Name

Most commands require UUIDs, not names. Always use list commands first to find UUIDs:

# Bad: Using name (will fail)
{baseDir}/dist/coolify-cli.cjs applications get --uuid "my-app"

# Good: Using UUID
{baseDir}/dist/coolify-cli.cjs applications list  # Find UUID first
{baseDir}/dist/coolify-cli.cjs applications get --uuid abc-123

Force Deployments

Use --force flag carefully as it rebuilds from scratch:

# Normal deployment (uses cache)
{baseDir}/dist/coolify-cli.cjs deploy --uuid abc-123

# Force rebuild (slower, but ensures clean build)
{baseDir}/dist/coolify-cli.cjs deploy --uuid abc-123 --force

Environment Variable Updates

After updating environment variables, restart the application:

# Update env var
{baseDir}/dist/coolify-cli.cjs applications envs update \
  --uuid abc-123 \
  --env-uuid env-456 \
  --value "new-value"

# Restart to apply changes
{baseDir}/dist/coolify-cli.cjs applications restart --uuid abc-123

Backup Frequency

Use cron expressions for backup schedules:

Expression	Description
0 2 * * *	Daily at 2 AM
0 */6 * * *	Every 6 hours
0 0 * * 0	Weekly on Sunday at midnight
0 0 1 * *	Monthly on 1st at midnight

---

Summary

This skill provides complete access to Coolify's API across:

• Applications — Deployment, lifecycle, logs, environment variables
• Databases — 8 database types, backups, lifecycle management
• Services — Docker Compose orchestration
• Deployments — Trigger, monitor, cancel
• Servers — Infrastructure management and validation
• Projects — Organization and environment management
• Teams — Access control and collaboration
• Security — SSH key management
• GitHub Apps — Repository integration

All operations return structured JSON for easy agent consumption.