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.