coolify

# Coolify API Skill **Repository:** [github.com/visiongeist/coolifycli](https://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 ```bash # 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 ```bash {baseDir}/dist/coolify-cli.cjs applications list ``` **Output:** ```json { "success": true, "data": [ { "uuid": "abc-123", "name": "my-app", "status": "running", "fqdn": "https://app.example.com" } ], "count": 1 } ``` ### Get Application Details ```bash {baseDir}/dist/coolify-cli.cjs applications get --uuid abc-123 ``` ### Application Lifecycle ```bash # 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 ```bash {baseDir}/dist/coolify-cli.cjs applications logs --uuid abc-123 ``` ### Environment Variables ```bash # 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 ```bash # 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 ```bash {baseDir}/dist/coolify-cli.cjs databases list ``` ### Get Database Details ```bash {baseDir}/dist/coolify-cli.cjs databases get --uuid db-123 ``` ### Database Lifecycle ```bash # 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 ```bash # 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 ```bash # 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 ```bash {baseDir}/dist/coolify-cli.cjs services list ``` ### Get Service Details ```bash {baseDir}/dist/coolify-cli.cjs services get --uuid service-123 ``` ### Service Lifecycle ```bash # 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 ```bash {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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash {baseDir}/dist/coolify-cli.cjs deployments get --uuid deploy-456 ``` ### Cancel Deployment ```bash {baseDir}/dist/coolify-cli.cjs deployments cancel --uuid deploy-456 ``` --- ## Servers ### List Servers ```bash {baseDir}/dist/coolify-cli.cjs servers list ``` ### Get Server Details ```bash {baseDir}/dist/coolify-cli.cjs servers get --uuid server-123 ``` ### Create Server ```bash {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 ```bash {baseDir}/dist/coolify-cli.cjs servers update \ --uuid server-123 \ --name "Updated Name" \ --description "Production environment" ``` ### Validate Server ```bash {baseDir}/dist/coolify-cli.cjs servers validate --uuid server-123 ``` ### Get Server Resources ```bash # 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 ```bash {baseDir}/dist/coolify-cli.cjs servers delete --uuid server-123 ``` --- ## Projects ### List Projects ```bash {baseDir}/dist/coolify-cli.cjs projects list ``` ### Get Project Details ```bash {baseDir}/dist/coolify-cli.cjs projects get --uuid proj-123 ``` ### Create Project ```bash {baseDir}/dist/coolify-cli.cjs projects create \ --name "My Project" \ --description "Production project" ``` ### Update Project ```bash {baseDir}/dist/coolify-cli.cjs projects update \ --uuid proj-123 \ --name "Updated Name" ``` ### Delete Project ```bash {baseDir}/dist/coolify-cli.cjs projects delete --uuid proj-123 ``` ### Environments ```bash # 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 ```bash {baseDir}/dist/coolify-cli.cjs teams list ``` ### Get Current Team ```bash {baseDir}/dist/coolify-cli.cjs teams current ``` ### Get Team Members ```bash {baseDir}/dist/coolify-cli.cjs teams members ``` ### Get Team by ID ```bash {baseDir}/dist/coolify-cli.cjs teams get --id 1 ``` --- ## Security (Private Keys) ### List Private Keys ```bash {baseDir}/dist/coolify-cli.cjs security keys list ``` ### Get Private Key ```bash {baseDir}/dist/coolify-cli.cjs security keys get --uuid key-123 ``` ### Create Private Key ```bash {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 ```bash {baseDir}/dist/coolify-cli.cjs security keys update \ --uuid key-123 \ --name "Updated Key Name" ``` ### Delete Private Key ```bash {baseDir}/dist/coolify-cli.cjs security keys delete --uuid key-123 ``` --- ## GitHub Apps ### List GitHub Apps ```bash {baseDir}/dist/coolify-cli.cjs github-apps list ``` ### Get GitHub App ```bash {baseDir}/dist/coolify-cli.cjs github-apps get --uuid gh-123 ``` ### Create GitHub App ```bash {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 ```bash {baseDir}/dist/coolify-cli.cjs github-apps update \ --uuid gh-123 \ --name "Updated App Name" ``` ### Delete GitHub App ```bash {baseDir}/dist/coolify-cli.cjs github-apps delete --uuid gh-123 ``` ### List Repositories ```bash {baseDir}/dist/coolify-cli.cjs github-apps repos --uuid gh-123 ``` ### List Branches ```bash {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:** ```bash {baseDir}/dist/coolify-cli.cjs servers list ``` 2. **Create application:** ```bash {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:** ```bash {baseDir}/dist/coolify-cli.cjs applications envs create \ --uuid <new-app-uuid> \ --key DATABASE_URL \ --value "postgres://..." \ --is-runtime true ``` 4. **Deploy:** ```bash {baseDir}/dist/coolify-cli.cjs deploy --uuid <new-app-uuid> ``` ### Set Up Database with Backups 1. **Create database:** ```bash {baseDir}/dist/coolify-cli.cjs databases create-postgresql \ --project-uuid proj-123 \ --server-uuid server-456 \ --name "production-db" ``` 2. **Configure daily backups:** ```bash {baseDir}/dist/coolify-cli.cjs databases backups create \ --uuid <db-uuid> \ --frequency "0 2 * * *" \ --enabled true ``` 3. **Trigger manual backup:** ```bash {baseDir}/dist/coolify-cli.cjs databases backups trigger \ --uuid <db-uuid> \ --backup-uuid <backup-uuid> ``` ### Monitor Application Health 1. **Check application status:** ```bash {baseDir}/dist/coolify-cli.cjs applications get --uuid abc-123 ``` 2. **View recent logs:** ```bash {baseDir}/dist/coolify-cli.cjs applications logs --uuid abc-123 ``` 3. **List recent deployments:** ```bash {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:** ```bash export COOLIFY_TOKEN="your-token-here" ``` Or configure in Clawdbot config at `~/.clawdbot/clawdbot.json`: ```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:** ```bash # 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:** ```bash # 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: ```bash {baseDir}/dist/coolify-cli.cjs deployments get --uuid deploy-456 ``` 2. Check application logs: ```bash {baseDir}/dist/coolify-cli.cjs applications logs --uuid abc-123 ``` 3. Verify environment variables are correct: ```bash {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:** ```bash # macOS (via Homebrew) brew install node # Verify installation node --version ``` --- ## Output Format All commands return structured JSON: ### Success Response ```json { "success": true, "data": { ... }, "count": 42 } ``` ### Error Response ```json { "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: ```bash 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: ```bash # 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: ```bash # 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: ```bash # 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.