dx-org-devhub-configure

Dev Hub を有効化し、スクラッチ組織の割り当てを確認する

Salesforce 組織で Dev Hub を有効化し、すでに有効かどうかを確認して、組織の スクラッチ組織の割り当て（有効な上限と日次上限、および残数）を確認します。デフォルト組織または名前を指定した組織が対象です。このスキルでは、Dev Hub のサブ設定（パッケージ、組織シェイプのエクスポート、スクラッチ組織のスナップショット）を構成したり、Dev Hub から作成されたアクティブなスクラッチ組織を一覧表示したりすることもできます。

Dev Hub は、スクラッチ組織や第 2 世代（2GP）／アンロックパッケージの作成と管理を可能にする組織機能です。

使用する場合

次のようなリクエストで使用します。

• 「Dev Hub を有効にして」／「Dev Hub をオンにして」／「この組織をスクラッチ組織用に設定して」
• 「自分の組織で Dev Hub は有効になっていますか？」／「Dev Hub がオンか確認して」
• 「スクラッチ組織はいくつ作成できますか？」／「スクラッチ組織の割り当て／上限はいくつですか？」／「スクラッチ組織はあといくつ作成できますか？」
• 「パッケージ／2GP／アンロックパッケージを有効にして」／「組織シェイプのエクスポートを有効にして」／「スクラッチ組織のスナップショットを有効にして」（Dev Hub のサブ設定）
• 「Dev Hub のスクラッチ組織を一覧表示して」

使用しない場合

次の場合は、このスキルを使用しないでください。

• 個別のスクラッチ組織を作成または削除する場合 — これは別のワークフローである sf org create scratch／sf org delete scratch を使用します。このスキルは Dev Hub 機能を有効にして、割り当てを報告するものであり、スクラッチ組織は作成しません。
• デフォルト／アクティブな組織を切り替える場合 — dx-org-switch を使用します。
• トライアルまたは組織の有効期限を確認する場合（「組織の有効期限はいつですか？」）— dx-org-trial-expiration-check を使用します。

Dev Hub の有効化状況の判定方法

標準オブジェクト ScratchOrgInfo は、Dev Hub が有効になっている場合にのみプロビジョニングされ、クエリ可能になります。したがって、SELECT COUNT() FROM ScratchOrgInfo が成功すれば Dev Hub はオンです。INVALID_TYPE エラーが返された場合はオフです。これが信頼できる判定方法です。

sf org list limits だけを根拠に有効化状況を判断しないでください。Dev Hub がオフの組織でも ActiveScratchOrgs／DailyScratchOrgs の行が表示されるため、制限値から分かるのは割り当てであり、有効化状況ではありません。

有効化の仕組み（重要）

• Dev Hub のマスタースイッチは、デプロイ可能な Metadata API フィールド DevHubSettings.enableScratchOrgManagementPref です。enableDevHub フィールドはなく、有効化する専用の sf コマンドもありません。この設定をデプロイすることが、Setup のトグル操作と同じです。
• 有効化は元に戻せません — 一度オンにすると、Dev Hub をオフにすることはできません。
• 必要な権限：ModifyAllData または ModifyMetadata を持つユーザーが必要です（System Administrator はこれらの権限を持っています）。権限のないユーザーには INSUFFICIENT_ACCESS が返されます。
• Sandbox、または登録済みの名前空間がある組織では有効化できません。
• Developer、Enterprise、Performance、Unlimited およびトライアルエディションで利用できます。

手順

1. 重要： Dev Hub の検出、有効化のデプロイ（安全なドライランがデフォルト）、割り当ての計算、構造化された出力を処理し、macOS と Linux で動作する同梱のヘルパースクリプトを実行してください。スキルディレクトリから絶対パスで必ず実行してください。./scripts/ は使用しないでください。これはユーザーのカレントディレクトリを基準に解決されるため、誤ったスクリプトが実行されるか、失敗します。スクリプトはこの点を自己チェックします。$0 が絶対パスでない場合、使用方法のエラーで終了するため、<skill_dir>（この SKILL.md を含むディレクトリ）へのフルパスを渡してください。

   bash "<skill_dir>/scripts/devhub.sh" <alias-or-username>            # status: on? + allocation
   bash "<skill_dir>/scripts/devhub.sh"                               # default org (target-org)
   bash "<skill_dir>/scripts/devhub.sh" <org> --allocation           # allocation only
   bash "<skill_dir>/scripts/devhub.sh" <org> --enable               # validate enabling (dry run)
   bash "<skill_dir>/scripts/devhub.sh" <org> --enable --apply       # actually enable (irreversible)
   bash "<skill_dir>/scripts/devhub.sh" <org> --list-scratch         # list active scratch orgs
   bash "<skill_dir>/scripts/devhub.sh" <alias> --instance-url <url> --enable --apply  # log in first, then enable
   bash "<skill_dir>/scripts/devhub.sh" <url>                        # bare instance URL: log in to it
   

   ユーザーからインスタンス URL（My Domain、Sandbox、またはプレリリース／スクラッチのログイン URL。例：https://my-domain.my.salesforce.com）が指定された場合は、その正確な URL を --instance-url <url> で渡してください。スクリプトは Salesforce が所有するホスト名を受け付け、sf org login web --instance-url <url> でログインした後、処理を続行します。URL だけを位置引数として渡す方法も、同じ指定の省略形として使用できます。

   <skill_dir> は、この SKILL.md を含むディレクトリの絶対パスです。

2. 有効化する場合は、まずドライランをデフォルトにしてください。 --apply を付けずに --enable を実行してデプロイを検証し、結果を伝えてください。有効化は元に戻せないため、ユーザーが Dev Hub の実際の有効化を明確に依頼した場合に限り、--enable --apply を実行してください。適用操作には、明示的な組織エイリアスまたはユーザー名が必要です。スクリプトは、明示されていないデフォルト組織の変更を拒否します。権限不足でデプロイが拒否された場合は、スクリプトが表示する Setup UI の代替手順を伝えてください。

3. スクリプトの出力を伝えてください。組織をクエリできない場合は、ユーザーが認証できるよう、スクリプトが表示する sf org login web コマンドを伝えてください。リクエストに応じて任意のフラグを選択してください（以下を参照）。制限のみを確認する場合は --allocation、スクラッチ組織を列挙する場合は --list-scratch、サブ設定を有効にする場合は --packaging ／ --snapshots ／ --shape、自動化には --json を使用します。

完了前に

回答を返す前に、以下を確認してください。

• 重要： ヘルパーを絶対パスで実行した（bash "<skill_dir>/scripts/devhub.sh" …）。./scripts/ は使用していない（スクリプトは $0 が絶対パスでない場合に拒否します）。
• ユーザーが Dev Hub または設定を実際に有効化するよう明確に依頼していない限り、--apply を実行していない。有効化は元に戻せません。
• 手書きの回答で置き換えず、スクリプト自身の出力（ステータス／割り当て、または表示されたログイン／Setup UI の案内）を伝えた。

オプション

フラグ	目的
--allocation, -A	スクラッチ組織の割り当て（Active/Daily）のみを表示します。
--list-scratch, -l	この Dev Hub から作成されたアクティブなスクラッチ組織を一覧表示します。
--enable, -e	Dev Hub を有効にします（enableScratchOrgManagementPref=true をデプロイします）。--apply を指定しない場合はドライランです。
--configure, -c	マスタースイッチを有効にせずに、サブ設定を構成します。設定フラグと組み合わせてください。
--packaging	enablePackaging2=true（Unlocked パッケージと 2GP パッケージ）。
--snapshots	enableScratchOrgSnapshotPref=true。
--shape	enableShapeExportPref=true。
--scratch-management	enableScratchOrgManagementPref=true（Dev Hub のスイッチ）。
--pref KEY=VALUE	任意の DevHubSettings サブ設定（KEY は enable で始まり、VALUE は true/false）。複数回指定できます。
--apply	明示的に指定した組織に実際にデプロイします。--enable/--configure のデフォルトは検証のみのドライランです。
--login	先に sf org login web で組織を認証し（ブラウザーが開きます）、その後に操作を実行します。
--instance-url <url>	sf org login web --instance-url <url> で特定のインスタンス（My Domain、sandbox、またはプレリリース／スクラッチインスタンス）にログインします。--login も指定したものとして扱われます。
--json	機械可読な JSON を出力します。
--fail-if-disabled	Dev Hub が有効でない場合、3 で終了します（CI／cron のゲート）。
--help, -h	使用方法を表示します。

--enable はサブ設定フラグと組み合わせて、一度に有効化と構成を行えます （例：--enable --packaging --apply）。省略した場合、組織のデフォルトは target-org、次に target-dev-hub です。

出力例

スクリプトは実行時に正確な出力を表示します。有効と無効の状態を示す出力（割り当てテーブルや、有効化／Setup UI に関する案内を含む）の例を確認する必要がある場合は、 examples/status-output.md を読んでください。それ以外の場合は、このワークフローを簡潔に保つため、読み飛ばしてください。

自動化向けの構造化出力（--json）

機械可読な出力（説明文なし）には、どのモードでも --json を使用します。ステータスでは devHubEnabled、status、allocation オブジェクトが返されます。有効化では success、applied、devHubVerifiedState が返されます。決定論的に動作し、LLM は不要です。

bash "<skill_dir>/scripts/devhub.sh" my-devhub --json
# {"org":"my-devhub","devHubEnabled":true,"status":"enabled", ... }

Dev Hub が有効でない場合、--fail-if-disabled は 3 で終了し（stderr に ALERT: 行を出力）、スケジュールされたジョブで状態を判定できます。

終了コード

• 0 成功
• 1 組織を照会できなかった場合、またはデプロイに失敗した場合（認証／接続／デプロイ）
• 2 使用方法が誤っているか、依存関係（sf または jq）が不足している場合
• 3 Dev Hub が有効でない場合（--fail-if-disabled が設定されている場合のみ）

認証

組織がまだ認証されていない場合、--login（または --instance-url <url>）を使ってスキルからログインし、同じ実行内で要求された操作を続けて実行できます。ユーザーがインスタンス URL を指定した場合は、この方法を推奨します。

<url> をユーザーの実際のインスタンス URL に置き換えてください（ここでは汎用的な https://my-domain.my.salesforce.com のプレースホルダーを示しています）。

# Log in to a specific instance (My Domain / pre-release / sandbox), then enable:
bash "<skill_dir>/scripts/devhub.sh" my-alias \
  --instance-url https://my-domain.my.salesforce.com --enable --apply

# Bare instance URL as shorthand — logs in to it, then reports status:
bash "<skill_dir>/scripts/devhub.sh" https://my-domain.my.salesforce.com

# Just authenticate an org (no other action):
bash "<skill_dir>/scripts/devhub.sh" my-alias --login

sf org login web は OAuth フロー用のブラウザーを開きます。セッションはタイムアウトするため、速やかに完了してください。位置引数（my-alias）を指定すると、それが CLI エイリアスになります。URL のように見える位置引数（:// を含むもの）は、ログイン先の --instance-url として扱われます。このオプションで指定できるのは、HTTPS を使用する Salesforce 所有のホスト名のみです。通常の本番／DE／トライアルログイン（login.salesforce.com）の場合は、--instance-url を省略してください。ブラウザーフローが何度もタイムアウトする場合、スクリプトはコードベースのログインに使う sf org login device の代替手順を表示します。

組織が認証されておらず、ログインフラグも指定されていない場合、スクリプトは代わりに、ログインして再実行するための正確なコマンドを表示します。インスタンス URL が指定されている場合は、その URL が使用されます。

  my-org                         could not query org (...)

  To authenticate against https://my-domain.my.salesforce.com, run:
    sf org login web --instance-url "https://my-domain.my.salesforce.com" --alias "my-org"
  Or let this script log you in and continue in one step:
    devhub.sh "my-org" --instance-url "https://my-domain.my.salesforce.com" --login
  Then re-run. List existing logins with:  sf org list

手動での代替手順（スクリプトを利用できない場合）

# Detect Dev Hub (INVALID_TYPE error means OFF; a count means ON):
sf data query --query "SELECT COUNT() FROM ScratchOrgInfo" --target-org <org> --json

# Enable Dev Hub via the Tooling API (what the Setup toggle does; irreversible):
sf api request rest "/services/data/v47.0/tooling/sobjects/DevHubSettings/DevHub" \
  --method PATCH \
  --body '{"FullName":"DevHub","Metadata":{"enableScratchOrgManagementPref":true}}' \
  --target-org <org>

# Or enable in the UI: Setup > Quick Find > "Dev Hub" > turn Enable Dev Hub On.

# View scratch org allocation:
sf org list limits --target-org <org> --json | jq '.result[] | select(.name|test("ScratchOrg"))'

メモ

• PATH 上に Salesforce CLI (sf) と jq が必要です。また、認証済みの組織が少なくとも 1 つ必要です（sf org login web）。
• 有効化した後、組織をデフォルトの Dev Hub に設定します： sf config set target-dev-hub <org>。
• パッケージング（enablePackaging2）を有効にするには、先に Dev Hub を有効にする必要があります。--enable --packaging を使うと、1 回のデプロイで順序を処理できます。
• 管理者以外のユーザーがスクラッチ組織を作成・表示するには、引き続きオブジェクトへのアクセス権（ScratchOrgInfo と ActiveScratchOrg の Read/Create）が必要です。また、2GP／アンロックパッケージをビルドするには、「Create and Update Second-Generation Packages」権限が必要です。
• デフォルトの組織を切り替えるには dx-org-switch を使います。有効期限を確認するには dx-org-trial-expiration-check を使います。