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 を返します（issue #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 トークンをシェルの履歴に保存します（代わりにコンテキストシステムを使用してください）
• env sync が変数を削除すると考えます（作成・更新のみです）
• 操作内容を理解せずに本番環境で --force を使用します
• トークンのローテーション後にコンテキストの確認を省略します
• パスフレーズで保護された SSH キーを使用します（対応していません）

コマンド名の訂正

Coolify CLI は 2025 年後半にリリースされたため、Claude の学習データは限られています。よくある誤り:

• 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 を使用します。

Issue #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		デバッグログを有効化