/dx-org-devhub-configure

name: dx-org-devhub-configure
description: "Enable Dev Hub on a Salesforce org and view its scratch org allocation, using the Salesforce CLI (sf). Use when someone wants to turn on or enable Dev Hub, set up an org to create scratch orgs or second-generation (2GP) and unlocked packages, check whether Dev Hub is already enabled, see how many scratch orgs they can create (Active and Daily scratch org limits, remaining allocation), configure Dev Hub preferences such as packaging, org shape export, or scratch org snapshots, or list the active scratch orgs created from a Dev Hub. Enabling deploys the enableScratchOrgManagementPref setting, is irreversible, needs a System Administrator (ModifyAllData or ModifyMetadata), and does not work in sandboxes. DO NOT TRIGGER for creating or deleting individual scratch orgs, for switching the default org (use dx-org-switch), or for trial or org expiration dates (use dx-org-trial-expiration-check)."
allowed-tools: Read, Bash(bash), Bash(sf api request rest), Bash(sf data query), Bash(sf org list), Bash(sf org login web), Bash(sf org login device), Bash(sf project deploy), Bash(sf config get), Bash(sf org display), Bash(sf org open), Bash(jq)
metadata:
  version: "1.0"
  domains: ["Developer Experience"]
  # DevHubSettings metadata + the Tooling API DevHubSettings endpoint require
  # API 47.0 or later (see scripts/devhub.sh SETTINGS_API_VERSION).
  minApiVersion: "47.0"
  relatedSkills:
    - "dx-org-switch"
    - "dx-org-trial-expiration-check"
  # Enabling needs ModifyAllData OR ModifyMetadata (either suffices). accessCheck
  # is a flat array with no OR operator, so declaring both would read as AND and
  # could falsely gate an admin holding only one. Declare the canonical
  # System-Administrator perm; the OR alternative stays documented in the
  # description and body.
  accessCheck:
    - type: "userPerm"
      value: "ModifyAllData"
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6.0"
    - tool: ["sf"]
      semver: ">=2.0.0"

Enable Dev Hub & View Scratch Org Allocation

Enable **Dev Hub** on a Salesforce org, verify whether it is already on, and see the org's **scratch org allocation** (Active and Daily limits and how many remain) — for the default org or a named org. The skill can also configure Dev Hub sub-preferences (packaging, org shape export, scratch org snapshots) and list the active scratch orgs created from a Dev Hub.

Dev Hub is the org feature that lets you **create and manage scratch orgs** and **second-generation (2GP) / unlocked packages**.

When to use

Trigger on requests like:

• "Enable Dev Hub" / "Turn on Dev Hub" / "Set up this org for scratch orgs."
• "Is Dev Hub enabled on my org?" / "Check if Dev Hub is on."
• "How many scratch orgs can I create?" / "What's my scratch org allocation /

limit?" / "How many scratch orgs do I have left?"

• "Turn on packaging / 2GP / unlocked packages" / "Enable org shape export" /

"Enable scratch org snapshots" (Dev Hub sub-preferences).

• "List the scratch orgs on my Dev Hub."

When NOT to use

Do **not** trigger this skill for:

• **Creating or deleting an individual scratch org** — that is

`sf org create scratch` / `sf org delete scratch`, a different workflow. This skill enables the *Dev Hub feature* and reports *allocation*; it does not create scratch orgs.

• **Switching the default/active org** — use `dx-org-switch`.
• **Trial or org expiration dates** ("when does my org expire") — use

`dx-org-trial-expiration-check`.

How Dev Hub enablement is determined

The standard object **`ScratchOrgInfo`** is provisioned and becomes queryable **only when Dev Hub is enabled**. So a successful `SELECT COUNT() FROM ScratchOrgInfo` means Dev Hub is **ON**; an `INVALID_TYPE` error means it is **OFF**. This is the reliable signal.

> Do **not** infer enablement from `sf org list limits` alone: it reports > `ActiveScratchOrgs` / `DailyScratchOrgs` rows even on orgs where Dev Hub is > **off**, so limits show allocation but not enablement.

How enabling works (important)

• The Dev Hub master switch is the **deployable** Metadata API field

**`DevHubSettings.enableScratchOrgManagementPref`**. There is **no** `enableDevHub` field and **no** dedicated `sf` command to turn it on — deploying this setting is exactly what the Setup toggle does.

• **Enabling is irreversible** — once on, Dev Hub cannot be turned off.
• **Requires** a user with **ModifyAllData** or **ModifyMetadata** (a **System

Administrator** has these). A user without them gets `INSUFFICIENT_ACCESS`.

• **Cannot** be enabled in a **sandbox**, or in an org that has a **registered

namespace**.

• Available in **Developer, Enterprise, Performance, Unlimited**, and **trial**

editions.

Steps

1. **CRITICAL:** Run the bundled helper script, which handles Dev Hub detection, the enablement deploy (with a safe dry-run default), allocation math, and structured output, and works on macOS and Linux. Always invoke it by **absolute path** from the skill directory — never `./scripts/`, which resolves against the user's current directory and will either run the wrong script or fail. The script self-checks this: if `$0` is not absolute it exits with a usage error, so pass the full path to `<skill_dir>` (the directory containing this 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> -