Imported from visiongeist/coolifycli (AGENTS.md). Install upstream with npx skills add visiongeist/coolifycli. Copyright stays with the author.

Agent Instructions for Coolify CLI

This document provides guidance for AI agents (like GitHub Copilot, Claude, or other AI assistants) when working with the Coolify CLI project.

Project Overview

coolifycli is a command-line interface and OpenClaw skill for managing Coolify deployments, applications, databases, and infrastructure via the Coolify API. It's designed to be used both as a standalone CLI tool and as an AI agent skill.

Repository Structure

/Users/damien.antipa/Code/coolifycli/
├── LICENSE                          # MIT License
├── README.md                        # Main documentation
├── SKILL.md                         # Root skill definition
├── AGENTS.md                        # This file
└── skills/coolify/
    ├── SKILL.md                     # Detailed skill documentation
    ├── references/
    │   └── API.md                   # Coolify API reference
    └── scripts/
        └── coolify                  # Main CLI script (bash)

Core Technologies

• Bash - Primary scripting language for the CLI
• curl - HTTP client for API requests
• jq - JSON processing
• Coolify API - REST API for Coolify platform management

Key Concepts

1. OpenClaw Skill Format

This project follows the OpenClaw skill format, which means:

• Skills are defined in SKILL.md files with YAML frontmatter
• Commands are designed to be agent-invocable
• All output is structured JSON for programmatic consumption
• Environment variables are used for configuration

2. Coolify API Integration

• API endpoint: https://app.coolify.io/api/v1 (default) or self-hosted
• Authentication: Bearer token via COOLIFY_TOKEN environment variable
• All API responses are JSON
• Rate limiting is handled automatically

3. Command Structure

Commands follow this pattern:

./scripts/coolify <domain> <action> [options]

Examples:

• ./scripts/coolify applications list
• ./scripts/coolify deploy --uuid abc-123
• ./scripts/coolify databases create-postgresql --project-uuid proj-123 --server-uuid server-456

Common Tasks

When a User Wants to Deploy an Application

1. First, list available resources:

   ./scripts/coolify servers list
   ./scripts/coolify projects list

2. Create or identify the application:

   ./scripts/coolify applications list
   # or create new:
   ./scripts/coolify applications create-public --project-uuid X --server-uuid Y --git-repository "https://github.com/user/repo" --git-branch main

3. Configure if needed:

   ./scripts/coolify applications envs create --uuid APP_UUID --key KEY --value VALUE

4. Deploy:

   ./scripts/coolify deploy --uuid APP_UUID

When a User Needs Database Management

1. List existing databases:

   ./scripts/coolify databases list

2. Create a new database:

   ./scripts/coolify databases create-postgresql --project-uuid X --server-uuid Y --name "mydb"

3. Configure backups:

   ./scripts/coolify databases backups create --uuid DB_UUID --frequency "0 2 * * *" --enabled true

When a User Wants to Troubleshoot

1. Check application status:

   ./scripts/coolify applications get --uuid APP_UUID

2. View logs:

   ./scripts/coolify applications logs --uuid APP_UUID

3. Check recent deployments:

   ./scripts/coolify deployments list-for-app --uuid APP_UUID

Important Conventions

1. Always Use UUIDs

• Most commands require UUIDs, not names
• Always list resources first to get the correct UUID
• Example: ./scripts/coolify applications list before operating on an app

2. Environment Variables Required

• COOLIFY_TOKEN - Required for all API operations
• COOLIFY_API_URL - Optional, defaults to https://app.coolify.io/api/v1
• Check if these are set before running commands

3. JSON Output Format

All commands return structured JSON:

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

Or on error:

{
  "success": false,
  "error": {
    "type": "APIError",
    "message": "...",
    "hint": "..."
  }
}

4. Command Naming Patterns

• Domain commands: <domain> <action> (e.g., applications list)
• Nested resources: <domain> <resource> <action> (e.g., applications envs list)
• Creation commands: Often include type in name (e.g., create-postgresql, create-public)

Agent Workflow Guidelines

When Asked to "Deploy Something"

1. Gather information - What needs to be deployed? From where?
2. Check prerequisites - Is COOLIFY_TOKEN set? Are servers available?
3. List resources - Show available projects, servers, existing apps
4. Propose a plan - Outline the steps before executing
5. Execute incrementally - Run commands step by step, checking results
6. Verify success - Check deployment status and logs

When Asked to "Create a Database"

1. Determine database type - PostgreSQL, MySQL, MongoDB, Redis, etc.
2. List servers - Where should it be created?
3. Create database - Use appropriate create-* command
4. Configure if needed - Set up backups, credentials
5. Provide connection info - Show the database UUID and connection details

When Asked to "Debug an Issue"

1. Gather context - What's the symptom? Which resource is affected?
2. Get resource details - Use get command to see current state
3. Check logs - View application or deployment logs
4. Check deployments - List recent deployments for the app
5. Propose solutions - Based on the error type, suggest fixes

When Working with Environment Variables

1. List existing - Always check what's already configured
2. Create or update - Use appropriate command
3. Remember to restart - Environment changes require app restart
4. Validate - Confirm the changes took effect

Error Handling

Common Errors and Solutions

Always Provide Context

When an error occurs:

1. Explain what went wrong in user-friendly terms
2. Show the relevant error message
3. Provide the specific command to fix or investigate further
4. If needed, explain the underlying Coolify/API concept

Development Guidelines

When Adding New Features

1. Check API.md - See if the endpoint exists in Coolify API
2. Follow existing patterns - Match the structure of similar commands
3. Update SKILL.md - Document the new command with examples
4. Test manually - Run the command with real API credentials
5. Update README.md - Add to relevant section

When Fixing Bugs

1. Reproduce first - Understand the exact failure case
2. Check API response - Is it an API issue or CLI parsing issue?
3. Test fix - Verify it works with the actual Coolify API
4. Consider edge cases - What if UUID is invalid? What if response is empty?

Code Style

• Use bash best practices (quote variables, check exit codes)
• Use jq for JSON parsing, not string manipulation
• Provide clear error messages with actionable hints
• Always output valid JSON on success or failure

Reference Documentation

• README.md - Overview, installation, quick start
• SKILL.md - Root skill definition
• skills/coolify/SKILL.md - Complete command reference
• skills/coolify/references/API.md - Coolify API documentation

Common Agent Mistakes to Avoid

❌ DON'T assume application names can be used as identifiers (always use UUIDs)
❌ DON'T run commands without checking if COOLIFY_TOKEN is set
❌ DON'T forget to list resources before operating on them
❌ DON'T ignore error messages - they contain helpful hints
❌ DON'T forget that environment variable changes require app restart

✅ DO list resources first to get UUIDs
✅ DO check prerequisites before running commands
✅ DO provide context and explain what each command does
✅ DO handle errors gracefully with helpful suggestions
✅ DO verify operations completed successfully

Testing Commands

Before suggesting commands to users:

1. Validate syntax - Check that all required options are provided
2. Check dependencies - Does the command require UUIDs from other commands?
3. Consider state - Will this work given the current state? (e.g., can't restart a stopped app without starting it first)
4. Explain side effects - Will this trigger a deployment? Will it restart services?

Quick Command Reference

Most Common Operations

# List everything
./scripts/coolify applications list
./scripts/coolify databases list
./scripts/coolify servers list
./scripts/coolify projects list

# Get details
./scripts/coolify applications get --uuid UUID
./scripts/coolify databases get --uuid UUID

# Lifecycle management
./scripts/coolify applications start|stop|restart --uuid UUID
./scripts/coolify databases start|stop|restart --uuid UUID

# Deployments
./scripts/coolify deploy --uuid UUID
./scripts/coolify deployments list
./scripts/coolify applications logs --uuid UUID

# Environment variables
./scripts/coolify applications envs list --uuid UUID
./scripts/coolify applications envs create --uuid UUID --key KEY --value VALUE

Working Directory

The CLI script is located at:

/Users/damien.antipa/Code/coolifycli/skills/coolify/scripts/coolify

Always use absolute paths or run from the repository root.

Final Notes

• This is a real project that interacts with production Coolify instances
• Always be cautious with destructive operations (delete, stop, etc.)
• When in doubt, list resources first to understand the current state
• Explain commands before running them so users understand what will happen
• Provide complete examples that users can run directly

For questions or issues, refer to the main documentation files or the Coolify documentation at https://coolify.io/docs/