forcedotcom/sf-skills / skills/dx-org-shape-manage
dx-org-shape-manage
VerifiedALWAYS USE THIS SKILL to create, list, or delete org shapes. An org shape is a captured baseline configuration (features, limits, edition, and Metadata API settings) of a source org, without its data or metadata. Use when the user asks to create/make/take an org shape, capture or replicate an org's configuration/edition/limits, list/show/view existing org shapes (including INACTIVE/superseded ones) or their IDs and status, or delete/remove org shapes for a source org. Requires a source org with Dev Hub and Org Shape for Scratch Orgs enabled. DO NOT TRIGGER for creating/checking/listing/deleting snapshots (use dx-org-snapshot-manage) or for creating scratch orgs (use dx-org-manage).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.9 KB |
| examples/create_error_output.json | config | 356 B |
| examples/create_success_output.json | config | 130 B |
| examples/delete_output.json | config | 161 B |
| examples/list_inactive_output.json | config | 891 B |
| examples/list_output.json | config | 612 B |
| references/cli_flags.md | markdown | 5.6 KB |
references/cli_flags.md
View on GitHub# CLI Flags Reference
Complete reference for the org shape commands: `sf org create shape`, `sf org list shape`, and `sf org delete shape`.
> **Global flags (all three commands):** `--json` (format output as JSON — ALWAYS use this) and `--flags-dir <value>` (import flag values from a directory).
---
## `sf org create shape`
Capture an org shape (baseline configuration) from the specified source org.
### Required Flags
| Flag | Alias | Description | Example |
|------|-------|-------------|---------|
| `--target-org` | `-o` | Username or alias of the **source org** to capture the shape from. Not required if the `target-org` configuration variable is already set. | `--target-org SourceOrg` |
> **Note:** `--target-org` here is the org being *shaped* (the source org), NOT a Dev Hub. There is no `--target-dev-hub` flag on this command.
> **API version:** This skill does not set `--api-version`. If the user needs a shape created against a specific API version, tell them to run `sf org create shape` manually via the CLI with that flag.
### Flags That Do NOT Exist (common mistakes)
Unlike `sf org create snapshot`, the shape command has **no** way to name or describe the shape:
| Not a flag | Why |
|------------|-----|
| `--name` / `-n` | A shape is identified by the source org's ID, not a custom name |
| `--description` / `-d` | Shapes have no description; use `sf org list shape` to identify them |
| `--target-dev-hub` / `-v` | The command runs against the source org, not a Dev Hub |
### Usage Patterns
```bash
# Basic shape creation (by alias)
sf org create shape --target-org SourceOrg --json
# Using the default target org
sf org create shape --json
# By username
sf org create shape --target-org test-org@example.com --json
```
**Legacy alias:** `sf force org shape create`
---
## `sf org list shape`
List all org shapes you've created. Output includes the alias, username, and ID of the source org, plus the shape's status.
### Flags
This command takes only the global flags (`--json`, `--flags-dir`). It does **not** take `--target-org` — it lists shapes across all your authenticated orgs.
### Usage Patterns
```bash
# List all org shapes you've created
sf org list shape --json
# List all org shapes and write the output to a file
sf org list shape --json > tmp/MyOrgShapeList.json
```
**Legacy alias:** `sf force org shape list`
---
## Listing Inactive Shapes (`sf data query`)
`sf org list shape` only surfaces `Active`/`InProgress` shapes and takes no `--target-org` — there is no flag to see `Inactive` shapes or to scope to one source org. To see a source org's full shape history, including shapes superseded by a later `sf org create shape` run, query `ShapeRepresentation` directly:
```bash
# All shapes (any status) for a specific source org
sf data query --target-org SourceOrg --query "SELECT Id, Name, Status, CreatedDate, LastModifiedDate FROM ShapeRepresentation" --json
# Only Inactive shapes for a specific source org
sf data query --target-org SourceOrg --query "SELECT Id, Name, Status, CreatedDate, LastModifiedDate FROM ShapeRepresentation WHERE Status = 'Inactive'" --json
```
`ShapeRepresentation` has no `SourceOrgId`, `username`, or `alias` field — the query result contains only `Id`, `Name`, `Status`, `CreatedDate`, `LastModifiedDate` (plus whatever other fields you select, e.g. `Description`, `CreatedById`, `LastModifiedById`). Requires the same `ShapeRepresentation` CRUD access as `sf org create/delete shape`.
---
## `sf org delete shape`
Delete **all** org shapes for a target (source) org.
### Required Flags
| Flag | Alias | Description | Example |
|------|-------|-------------|---------|
| `--target-org` | `-o` | Username or alias of the source org whose shapes to delete. Not required if the `target-org` configuration variable is already set. | `--target-org SourceOrg` |
### Optional Flags
| Flag | Alias | Description | Example |
|------|-------|-------------|---------|
| `--no-prompt` | `-p` | Don't prompt for confirmation (use in scripts/CI) | `--no-prompt` |
> **API version:** This skill does not set `--api-version`. If the user needs a specific API version, tell them to run `sf org delete shape` manually via the CLI with that flag.
### Usage Patterns
```bash
# Delete all org shapes for the source org (prompts for confirmation)
sf org delete shape --target-org SourceOrg --json
# Delete without prompting (scripts/CI)
sf org delete shape --target-org SourceOrg --no-prompt --json
```
**Legacy alias:** `sf force org shape delete`
### Exit Codes
| Code | Meaning |
|------|---------|
| `0` | All deletions succeeded |
| `1` | All deletions failed |
| `68` | Partial failure — some shapes deleted, others failed (see the `failures` array in the JSON) |
> Without `--no-prompt`, the command prompts "Delete shape for `<username>`?". Declining returns with no result and performs no deletion.
---
## Important Notes
- **Source org must be enabled for org shape** — enable it via **Setup → Scratch Orgs → Enable Org Shape for Scratch Orgs** in the source org. Otherwise create/delete fail with a no-access error (`ShapeRepresentationNoAccess`), or a generic `UNKNOWN_EXCEPTION` (with a support ErrorId) if the org is only partially enabled.
- **ShapeRepresentation access** — the running user must have CRUD access to the `ShapeRepresentation` object, or create fails with `NoCrudAccessCreateShape`.
- **Find the shape's org ID** — run `sf org list shape` to view created shapes, their status (`Active`, `InProgress`), and the source org IDs.
- **One active shape per source org** — creating a new shape marks any previous shape for that org inactive; `sf org delete shape` removes all shapes for the org.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |