deploying-laravel-cloud

Laravel Cloud CLI でのデプロイ

セットアップ

composer global require laravel/cloud-cli
cloud auth -n

cloud auth を実行するとブラウザーが開きます。ブラウザーを開けない場合は、環境変数に LARAVEL_CLOUD_TOKEN を設定してください。保存済みのトークンより優先され、ディスクには何も書き込みません。代わりにトークンを保存するには、cloud auth:token --add --token=<token> -n を実行するか、次のようにパイプで渡します：echo "$TOKEN" | cloud auth:token --add -n。

コマンド

コマンドは CRUD パターンに従います：resource:list、resource:get、resource:create、resource:update、resource:delete。

利用可能なリソース：application、environment、instance、database-cluster、database、cache、bucket、domain、websocket-cluster、background-process、secret、command、deployment。

一部のリソースには追加のコマンドがあります（例：domain:verify、database:open、instance:sizes、cache:types）。cloud -h で確認してください。

コマンドのシグネチャをハードコードしないでください。実行時にオプションを確認するには、必ず cloud <command> -h を実行してください。

CLI フラグ

すべてのコマンドに必ず -n を追加してください。CLI が応答しなくなるのを防ぎます。 -q や --silent は使用しないでください。すべての出力が抑制されます。

操作ごとのフラグの組み合わせ：

• 読み取り（:list、:get）→ --json -n
• 作成（:create）→ --json -n
• 更新（:update）→ --json -n --force
• 削除（:delete）→ -n --force（--json なし）
• 環境変数 → -n --force
• デプロイ／出荷 → すべてのオプションを明示的に指定して -n（--json なし）

デプロイのワークフロー

タスクを特定し、該当する手順に従ってください。

初回デプロイですか？ → cloud ship -n（cloud ship -h でオプションを確認してください）

既存のアプリですか？ →

cloud deploy {app_name} {environment} -n --open
cloud deploy:monitor -n

環境変数ですか？ → cloud environment:variables -n --force

シークレットですか？ → echo "$VALUE" | cloud secret:create --name=NAME --json -n を実行し、続けて cloud environment-secret:attach を実行します。

インフラストラクチャをプロビジョニングしますか？ → cloud <resource>:create --json -n

モノレポ（サブディレクトリ内にアプリがある）ですか？ → cloud ship または cloud application:create に --root-directory=<subdir> を追加します。

カスタムドメインですか？ → cloud domain:create --json -n を実行し、続けて cloud domain:verify -n を実行します。

複数ステップの操作については、reference/checklists.md を参照してください。

ユーザーが何を必要としているかわからない場合は、何かを実行する前にユーザーに確認してください。

コマンドが失敗した場合

1. エラー出力を読みます
2. :list --json -n または :get --json -n でリソースの状態を確認します
3. 認証エラーですか？ → cloud auth -n
4. 問題を修正し、コマンドを再実行します
5. 一度修正した後も同じエラーが繰り返される場合は、停止してユーザーに確認してください

デプロイのたびに、必ず cloud deploy:monitor -n を実行してください。失敗した場合は、修正を試みる前に問題の内容をユーザーに示してください。

サブエージェントへの委任

メインのコンテキストウィンドウを小さく保つため、出力の多い操作はサブエージェント（Task ツールを使用）に委任してください。戻ってくるのは要約のみです。詳細な出力はサブエージェントのコンテキスト内に残ります。

以下はサブエージェントに委任してください：

• cloud deploy:monitor -n — デプロイログが非常に長くなる場合があります
• cloud deployment:get --json -n — デプロイの詳細情報全体
• cloud <resource>:list --json -n — 多数のリソースを一覧表示すると、大量の JSON が生成されます
• WebFetch を使った https://cloud.laravel.com/docs/llms.txt からのドキュメント取得

以下はメインコンテキスト内で実行してください：

• :create、:delete、:update などの短いコマンド — 出力が少量です
• cloud deploy -n — デプロイ ID がすぐに必要です
• 次のステップですぐに結果が必要なコマンド

ルール

次の手順を厳守してください：

• フラグの選択 — 上記の組み合わせを必ず使用します
• デプロイの順序 — デプロイしてから監視します。監視を省略してはいけません
• 破壊的なコマンド — 必ず事前にユーザーの確認を取り、コマンドを提示して承認を待ちます
• エラーへの対応 — 原因を特定して一度修正し、再び失敗した場合はユーザーに確認します

状況に応じて判断してください：

• インスタンスのサイズ、リージョン、クラスターの種類 — 指定がない場合はユーザーに確認します
• プロビジョニングするリソース — ユーザーの説明に基づいて判断します
• プロビジョニングの順序 — 厳密な順序はありません
• 出力の提示方法 — 状況に応じて要約、原文の提示、または項目の抽出を行います

シークレット

組織内で共有され、環境に紐付けられる暗号化された値です。CLI は値をローカルで暗号化するため、平文が API に送信されることはありません。

cloud secret:list --json -n
echo "$VALUE" | cloud secret:create --name=STRIPE_KEY --json -n
cloud environment-secret:attach {environment} {secretId} -n
cloud environment-secret:list {environment} --json -n

値はパイプで渡してください。--value= も使えますが、平文がシェル履歴とプロセス一覧に残ります。

secret:update、secret:delete、environment-secret:attach が受け取るのはシークレット ID であり、名前ではありません。名前は一意ではありません。ID は cloud secret:list --json -n で確認してください。

secret:get はなく、単一の環境からシークレットをデタッチする方法もありません。secret:delete はシークレットを削除し、すべての環境からデタッチします。

シークレットには PHP 拡張機能の sodium が必要です。ほかのコマンドでは必要ありません。

リモートアクセス

Tinker（>= v0.2.0）

Cloud 環境で PHP コードを直接実行します。

cloud tinker {environment} --code='Your PHP code here' --timeout=60 -n

• --code — 実行する PHP コード（非対話モードでは必須）
• --timeout — 出力を待つ最大秒数（デフォルト：60）

コードは echo、dump などを使って明示的に結果を出力する必要があります。式だけでは何も出力されません。

対話型プロンプトを避けるため、必ず --code と -n を指定してください。

リモートコマンド

Cloud 環境でシェルコマンドを実行します。

cloud command:run {environment} --cmd='your command here' -n

• --cmd — 実行するコマンド（非対話モードでは必須）
• --no-monitor — リアルタイムの出力ストリーミングをスキップします
• --copy-output — 出力をクリップボードにコピーします

過去のコマンドを確認します。

• cloud command:list {environment} --json -n — コマンド履歴を一覧表示します
• cloud command:get {commandId} --json -n — 特定のコマンドの詳細と出力を取得します

出力が長くなる可能性がある場合は、command:run をサブエージェントに委任してください。

請求と使用状況

現在の組織の請求と使用状況を確認します。

cloud usage --json -n

• --period=current|previous|1|2|3 — 請求期間（デフォルトは current。1／2／3 は過去 N 期間を示し、最大 3 です）。それ以外を指定するとエラーになります。
• --environment=<id> — 使用状況を単一の環境に絞り込みます
• --detailed — アプリケーション、リソース、アドオンごとの内訳を含めます
• --json — 機械可読形式で出力します（必ず -n と併用してください）

よく使うクエリ：

• 現在の支出：cloud usage --json -n | jq '.currentSpendCents'
• 先月の請求額：cloud usage --period=previous --json -n
• 1 つの環境の全内訳：cloud usage --environment=<id> --detailed --json -n

すべての金額はセント単位です。すべての階層でキーは camelCase です（例：currentSpendCents、bandwidth.allowanceBytes、databases[].totalCents、applications[].totalCostCents）。

--detailed --json はサブエージェントに委任してください。ペイロードにはすべてのデータベース、キャッシュ、バケット、WebSocket、アプリケーションが含まれるため、大きくなる可能性があります。

設定

1. 環境変数：LARAVEL_CLOUD_TOKEN — API トークン。保存済みのトークンより優先されます（空の場合は未設定として扱われます）
2. グローバル：~/.config/cloud/config.json — 認証トークンと設定
3. リポジトリローカル：.cloud/config.json — アプリケーションと環境のデフォルト設定（cloud repo:config {application} -n で設定）
4. CLI 引数は両方の設定ファイルより優先されます

repo:config にはアプリケーションを渡してください。渡さない場合、コマンドはアプリケーションを尋ねる必要があり、-n を指定していて組織に複数のアプリケーションがあると失敗します。デプロイコマンドではこれらのデフォルト設定は不要です。アプリケーションと環境を直接指定してください。

組織が複数ある場合、API トークンも複数保存されます。各コマンドは .cloud/config.json から organization_id を読み取り、使用するトークンを選択します。設定されていない場合、コマンドは失敗します。cloud repo:config {application} --organization=<id|name|slug> -n で設定してください。

LARAVEL_CLOUD_TOKEN に保持できるトークンは 1 つだけなので、組織は自動的に選択されます。--organization で別の組織を指定すると、トークンの組織にフォールバックせず失敗します。

ドキュメント

Laravel Cloud ドキュメント：https://cloud.laravel.com/docs/llms.txt

ユーザーから仕組みについて質問された場合、または Laravel Cloud の機能について説明を求められた場合は、上記 URL から WebFetch を使ってドキュメントを取得し、正確な回答に活用してください。

困ったときは

• 公式ドキュメントを取得するには、https://cloud.laravel.com/docs/llms.txt を参照してください
• コマンドのオプションを確認するには、cloud <command> -h を実行してください
• コマンドを確認するには、cloud -h を実行してください