coolify-cli

Coolify CLI

快速入门（3 分钟）

1. 安装

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/coollabsio/coolify-cli/main/scripts/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/coollabsio/coolify-cli/main/scripts/install.ps1 | iex

# Via Go
go install github.com/coollabsio/coolify-cli/coolify@latest

2. 身份验证

从 Coolify 控制面板的 /security/api-tokens 获取 API 令牌。

# Cloud-hosted Coolify
coolify context set-token cloud <YOUR_TOKEN>

# Self-hosted Coolify
coolify context add production https://coolify.example.com <YOUR_TOKEN>

# Verify connection
coolify context verify

3. 首批命令

coolify server list
coolify app list
coolify deploy name my-app

---

多实例上下文管理

每个上下文都存储名称、URL 和 API 令牌。多个 Coolify 实例（云端、预发布、生产环境）会独立管理。

# Add contexts
coolify context add production https://prod.coolify.example.com <token>
coolify context add staging https://staging.coolify.example.com <token>

# List all contexts
coolify context list

# Switch default context
coolify context use production

# Override per-command (no switching needed)
coolify app list --context staging

# Verify current context
coolify context verify

# Show Coolify instance version
coolify context version

# Delete a context
coolify context delete staging

配置文件位置：

• Linux/macOS：~/.config/coolify/config.json
• Windows：%USERPROFILE%\.config\coolify\config.json

覆盖优先级： --token 标志 > --context 标志 > 默认上下文。

---

应用生命周期

部署

coolify deploy uuid <uuid>              # Deploy by UUID
coolify deploy name my-app              # Deploy by app name
coolify deploy batch <uuid1>,<uuid2>    # Deploy multiple apps

管理

coolify app list                        # List all applications
coolify app get <uuid>                  # Get app details
coolify app start <uuid>               # Start application
coolify app stop <uuid>                # Stop application
coolify app restart <uuid>             # Restart application
coolify app delete <uuid>              # Delete application

日志

coolify app logs <uuid>                           # View recent logs
coolify app logs <uuid> --lines 100               # Last 100 lines
coolify app logs <uuid> --follow                  # Stream in real-time
coolify app deployments list <uuid>               # Deployment history
coolify app deployments logs <deployment-uuid>    # Specific deployment logs

环境变量

coolify app env list <uuid>                              # List all vars
coolify app env create <uuid> --key DB_URL --value "..." # Create variable
coolify app env update <uuid> --key DB_URL --value "..." # Update variable
coolify app env delete <uuid> --key DB_URL               # Delete variable
coolify app env sync <uuid> --file .env                  # Sync from file

重要： env sync 只会创建和更新变量。它不会删除 Coolify 中存在但 .env 文件中缺失的变量。若要完全同步，请先手动删除不需要的变量。

---

数据库管理

支持的类型：postgres、mysql、mariadb、mongodb、redis、keydb、dragonfly、clickhouse。

coolify database list                                           # List all
coolify database get <uuid>                                     # Get details
coolify database create --server-uuid <uuid> --type postgres    # Create
coolify database start <uuid>                                   # Start
coolify database stop <uuid>                                    # Stop
coolify database restart <uuid>                                 # Restart
coolify database delete <uuid>                                  # Delete

自动化备份

coolify database backup list <db-uuid>                          # List backup configs
coolify database backup create <db-uuid> --frequency "daily" --enabled  # Create schedule
coolify database backup trigger <backup-uuid>                   # Trigger now
coolify database backup executions <backup-uuid>                # Check history
coolify database backup update <backup-uuid> --frequency "weekly"       # Update schedule
coolify database backup delete <backup-uuid>                    # Remove config

---

服务管理

Coolify 支持 110 多种一键部署服务（Redis、WordPress、Plausible、Ghost 等）。

coolify service list                   # List all services
coolify service get <uuid>             # Get details
coolify service start <uuid>           # Start
coolify service stop <uuid>            # Stop
coolify service restart <uuid>         # Restart
coolify service delete <uuid>          # Delete

已知错误： coolify service env update 会返回 404（问题 #48）。可通过先删除再创建来规避。

---

服务器管理

coolify server list                    # List all servers
coolify server get <uuid>              # Get details
coolify server add --name web-1 --ip 192.168.1.100 --private-key-uuid <key-uuid> --user root
coolify server validate <uuid>         # Validate configuration
coolify server domains <uuid>          # List configured domains

---

输出格式与脚本编写

所有命令都支持 --format：

coolify server list                    # Table (default, human-readable)
coolify server list --format json      # JSON for automation
coolify server list --format pretty    # Pretty-printed JSON

# Pipe to jq for filtering
coolify app list --format json | jq '.[].name'

# Extract UUIDs
coolify app list --format json | jq -r '.[].uuid'

---

SSH 密钥管理

coolify private-key list                                    # List keys
coolify private-key get <uuid>                              # Get details
coolify private-key add --name deploy-key --file ~/.ssh/id_ed25519  # Add key
coolify private-key remove <uuid>                           # Remove key

注意： SSH 密钥必须无需密码（不支持密码短语）。

---

GitHub App 集成

coolify github list                                 # List GitHub Apps
coolify github get <id>                             # Get details
coolify github repos <id>                           # List repos
coolify github branches <id> --repo owner/repo      # List branches
coolify github create --name my-app --app-id 123456 --private-key-uuid <uuid> --webhook-secret "secret"
coolify github delete <id>                          # Remove integration

---

关键规则

始终执行

• 操作前验证上下文：coolify context verify
• 自动化和管道处理时使用 --format json
• 在生产环境部署前，先在预发布上下文中测试部署
• 使用 coolify deploy batch 协调多个应用的部署
• 限定 API 令牌的权限范围，并定期轮换

绝不执行

• 将 API 令牌存入 shell 历史记录（改用上下文系统）
• 假设 env sync 会删除变量（它只会创建或更新变量）
• 未了解操作内容就在生产环境中使用 --force
• 轮换令牌后跳过上下文验证
• 使用受密码短语保护的 SSH 密钥（不支持）

命令名称更正

Claude 对 Coolify CLI 的训练数据有限（该 CLI 于 2025 年末发布）。常见幻觉如下：

• 使用 coolify app list，而不是 coolify apps list 或 coolify application list
• 使用 coolify deploy uuid <uuid>，而不是 coolify app deploy <uuid> — deploy 是顶层命令
• 使用 coolify deploy name <name>，而不是 coolify deploy --app <name>
• 必须指定子命令：使用 coolify deploy uuid <uuid>，而不是 coolify deploy <uuid>
• --format json 才是正确写法（不是像 cf CLI 那样使用 --output json）

---

避免已知问题

此技能可避免 5 个已记录的问题：

问题 #1："app env sync" 因 "cannot unmarshal array" 失败

错误：cannot unmarshal array into Go value 来源：https://github.com/coollabsio/coolify-cli/issues/49 避免方法：确保 .env 文件使用简单的 KEY=VALUE 格式。不要使用 JSON 数组。如果批量同步失败，请逐个同步变量。

问题 #2："service env update" 返回 404

错误：HTTP 404 Not Found 来源：https://github.com/coollabsio/coolify-cli/issues/48 避免方法：删除并重新创建变量，不要更新变量：

coolify service env delete <uuid> --key MY_KEY
coolify service env create <uuid> --key MY_KEY --value "new_value"

问题 #3：令牌轮换后上下文身份验证失败

错误：轮换 API 令牌后返回 401 Unauthorized 避免方法：更新令牌并验证：coolify context set-token <name> <new-token> && coolify context verify

问题 #4：宽输出时表格渲染异常

错误：列未对齐或被截断 来源：https://github.com/coollabsio/coolify-cli/issues/54 避免方法：使用 --format json 或 --format pretty，确保输出可靠。

问题 #5：Windows 上找不到配置文件

错误：在 Windows 上找不到配置文件 预防措施：确保目录存在：%USERPROFILE%\.config\coolify\。CLI 将配置存储在 %USERPROFILE%\.config\coolify\config.json。

---

全局标志参考

标志	短标志	用途
--context		使用特定上下文
--host		覆盖主机名
--token		覆盖身份验证令牌
--format		输出格式：table/json/pretty
--show-sensitive	-s	在输出中显示机密信息
--force	-f	跳过确认
--debug		启用调试日志记录