Back to Details

dx-org-snapshot-manage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

dx-org-snapshot-manage

dx-org-snapshot-manage

Coordinates the full lifecycle of Salesforce scratch org snapshots — create, get (status), list, and delete — via 
sf org create snapshot
, 
sf org get snapshot
, 
sf org list snapshot
, and 
sf org delete snapshot
. A snapshot is a point-in-time copy of a scratch org (its metadata and data) that you reference by name in a scratch org definition file to spin up new orgs from saved state.
协调 Salesforce scratch org snapshot 的完整生命周期——创建、获取（状态）、列出和删除——通过 
sf org create snapshot
、
sf org get snapshot
、
sf org list snapshot
和 
sf org delete snapshot
实现。Snapshot 是 scratch org 在某一时间点的副本（包含其 metadata 和 data），可以在 scratch org definition 文件中按名称引用，以从保存的状态启动新的 org。

Tool Restrictions

工具限制

Use ONLY the Bash tool to execute the 
sf org ... snapshot
commands. Do NOT use MCP tools — ignore them completely.
Output artifacts for eval/testing: ALWAYS write the command's complete JSON response to a file when an output directory is available. Do NOT ask the user what file to write — this skill defines the filenames. After executing each command: (1) if the user specified an output path, write there immediately; (2) otherwise run 
[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output'
to detect the eval directory; (3) write the command's full, unmodified JSON response to 
<output-dir>/<filename>
using these filenames: 
create-snapshot-result.json
, 
get-snapshot-result.json
, 
list-snapshots-result.json
, or 
delete-snapshot-result.json
. This is the generated output — write it without asking. (4) If no output directory can be found by either check, include the command's complete, unmodified JSON response verbatim (e.g. in a fenced code block) in your final reply instead of skipping the artifact.
仅使用 Bash 工具执行 
sf org ... snapshot
命令。不要使用 MCP 工具——完全忽略它们。
用于 eval/testing 的输出产物： 有可用输出目录时，始终将命令的完整 JSON 响应写入文件。不要询问用户应写入哪个文件——此 skill 已定义文件名。执行每条命令后：(1) 如果用户指定了输出路径，立即写入该路径；(2) 否则运行 
[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output'
检测 eval 目录；(3) 使用以下文件名，将命令未经修改的完整 JSON 响应写入 
<output-dir>/
：
create-snapshot-result.json
、
get-snapshot-result.json
、
list-snapshots-result.json
或 
delete-snapshot-result.json
。这是生成的输出——直接写入，无需询问。(4) 如果通过上述任一检查均未找到输出目录，则在最终回复中逐字包含命令未经修改的完整 JSON 响应（例如放在 fenced code block 中），不得省略该产物。

Relationship to Other Skills

与其他 Skill 的关系

This skill owns the full snapshot lifecycle — create, get status, list, and delete. It does not create scratch orgs.
  • Any snapshot operation (create, status, list, delete, expiry check) → this skill.
  • Create a scratch org, including from an existing snapshot (
    --snapshot <name>
    ) → 
    dx-org-manage
    .
  • Org shapes (baseline config without data, 
    sf org create/list/delete shape
    ) → 
    dx-org-shape-manage
    . Shapes and snapshots are different artifacts with different commands — see the comparison below.
Snapshot (this skill)Org Shape (
dx-org-shape-manage
)
CapturesFull point-in-time copy: metadata and dataBaseline config only: features, limits, edition, Metadata API settings
Commands
sf org create/get/list/delete snapshot
sf org create/list/delete shape
Referenced via
snapshot
(name) in the scratch def file
sourceOrg
(org ID) in the scratch def file
PrerequisiteDev Hub has Scratch Org Snapshots enabledSource org has Org Shape for Scratch Orgs enabled
Operates againstA Dev Hub (
--target-dev-hub
)		The source org (
--target-org
)
此 skill 负责 snapshot 的完整生命周期——创建、获取状态、列出和删除。它不创建 scratch org。
  • 任何 snapshot 操作（创建、状态、列出、删除、过期检查）→ 此 skill。
  • 创建 scratch org，包括从现有 snapshot 创建（
    --snapshot <name>
    ）→ 
    dx-org-manage
    skill。
  • Org shape（不含数据的 baseline config，
    sf org create/list/delete shape
    ）→ 
    dx-org-shape-manage
    skill。Shape 和 snapshot 是不同产物，使用不同命令——请参阅下方对比。
Snapshot（此 skill）Org Shape（
dx-org-shape-manage
）
捕获内容完整的时间点副本：metadata 和 data仅限 baseline config：features、limits、edition、Metadata API settings
命令
sf org create/get/list/delete snapshot
sf org create/list/delete shape
引用方式scratch def file 中的 
snapshot
（名称）		scratch def file 中的 
sourceOrg
（org ID）
前提条件Dev Hub 已启用 Scratch Org SnapshotsSource org 已启用 Org Shape for Scratch Orgs
操作目标Dev Hub（
--target-dev-hub
）		source org（
--target-org
）

Scope

范围

  • In scope: Creating (
    sf org create snapshot
    ), getting status (
    sf org get snapshot
    ), listing (
    sf org list snapshot
    ), and deleting (
    sf org delete snapshot
    ) scratch org snapshots
  • Out of scope: Creating org shapes (
    dx-org-shape-manage
    ), creating scratch orgs — including from a snapshot (
    dx-org-manage
    )
  • 范围内：创建（
    sf org create snapshot
    ）、获取状态（
    sf org get snapshot
    ）、列出（
    sf org list snapshot
    ）和删除（
    sf org delete snapshot
    ）scratch org snapshot
  • 范围外：创建 org shape（
    dx-org-shape-manage
    ）、创建 scratch org——包括从 snapshot 创建（
    dx-org-manage
    ）

Required Inputs

必需输入

Infer from the user's request:
  • Operation: create, get, list, or delete (see Workflow step 1)
  • Dev Hub: Username or alias of the Dev Hub that owns the snapshots. Passed via 
    --target-dev-hub
    (
    -v
    ); optional if the 
    target-dev-hub
    config variable is set. All four commands operate against a Dev Hub, never 
    --target-org
    .
  • Source org (create only): Scratch org ID (starts with 
    00D
    ), username, or alias to snapshot. Passed via 
    --source-org
    (
    -o
    ).
  • Snapshot name (create only): A unique name for the snapshot, max 15 characters. Passed via 
    --name
    (
    -n
    ).
  • Snapshot name or ID (get & delete only): Name, or ID (starts with 
    0Oo
    ), of the snapshot. Passed via 
    --snapshot
    (
    -s
    ).
  • Description (create, optional): Documents snapshot contents.
  • Expiry threshold in days (expiring-soon listing only): There is no CLI flag for this — it's a client-side filter on 
    ExpirationDate
    (see Command Patterns).
从用户请求中推断：
  • 操作：create、get、list 或 delete（见工作流步骤 1）
  • Dev Hub：拥有这些 snapshot 的 Dev Hub 的用户名或别名。通过 
    --target-dev-hub
    （
    -v
    ）传入；如果已设置 
    target-dev-hub
    配置变量，则可省略。所有四条命令都针对 Dev Hub 操作，绝不能使用 
    --target-org
    。
  • Source org（仅 create）：要创建 snapshot 的 scratch org ID（以 
    00D
    开头）、用户名或别名。通过 
    --source-org
    （
    -o
    ）传入。
  • Snapshot name（仅 create）：snapshot 的唯一名称，最多 15 个字符。通过 
    --name
    （
    -n
    ）传入。
  • Snapshot name or ID（仅 get 和 delete）：snapshot 的名称或 ID（以 
    0Oo
    开头）。通过 
    --snapshot
    （
    -s
    ）传入。
  • Description（create 时可选）：记录 snapshot 的内容。
  • Expiry threshold in days（仅用于列出即将过期的 snapshot）：CLI 没有对应的 flag——这是客户端对 
    ExpirationDate
    的筛选（见命令模式）。

Workflow

工作流

  1. Identify the operation and match it to the command pattern below.
  2. Resolve the Dev Hub — if 
    --target-dev-hub
    isn't provided, check the default with 
    sf config get target-dev-hub
    . Never fabricate a placeholder Dev Hub name (e.g. 
    my-dev-hub
    ) — an unresolved hub is a hard stop; advise 
    sf org login web --set-default-dev-hub
    instead.
  3. For create, confirm the source org and snapshot name — the source must be a scratch org; the name must be unique in the Dev Hub and ≤15 characters.
  4. Execute via Bash tool with the 
    --json
    flag.
  5. Report the result (see Output Expectations and the example files).
  1. 识别操作，并将其与下方对应的命令模式匹配。
  2. 解析 Dev Hub——如果未提供 
    --target-dev-hub
    ，使用 
    sf config get target-dev-hub
    检查默认值。绝不能虚构占位 Dev Hub 名称（例如 
    my-dev-hub
    ）——无法解析 Dev Hub 时必须停止操作；建议改用 
    sf org login web --set-default-dev-hub
    。
  3. 对于 create，确认 source org 和 snapshot name——source 必须是 scratch org；名称在 Dev Hub 中必须唯一，且长度不超过 15 个字符。
  4. 通过 Bash 工具执行，并带上 
    --json
    flag。
  5. 报告结果（见输出预期和示例文件）。

Command Patterns

命令模式

OperationUser intentExecute via Bash tool
CreateCreate snapshot with name only
sf org create snapshot --source-org <orgId|alias> --name <SnapshotName> --json
CreateCreate snapshot with description
sf org create snapshot --source-org <orgId|alias> --name <SnapshotName> --description "<desc>" --json
CreateSpecify Dev Hub explicitly
sf org create snapshot --source-org <orgId|alias> --name <SnapshotName> --target-dev-hub <devHub> --json
GetCheck a snapshot's status/details
sf org get snapshot --snapshot <name|0Oo...> --json
ListList all snapshots in the Dev Hub
sf org list snapshot --json
ListList snapshots expiring within N days
sf org list snapshot --json
→ filter on 
ExpirationDate
with 
jq
(see 
references/cli_flags.md
)
DeleteDelete a snapshot (with confirm prompt)
sf org delete snapshot --snapshot <name|0Oo...> --json
DeleteDelete without prompting (scripts/CI)
sf org delete snapshot --snapshot <name|0Oo...> --no-prompt --json
DeleteDelete multiple/all snapshotsFirst 
sf org list snapshot --json
, confirm the target names with the user, then run 
sf org delete snapshot --snapshot <name>
once per snapshot — there is no bulk-delete command
Snapshot creation is asynchronous. 
create
returns a record whose 
Status
is typically 
InProgress
initially, with 
ExpirationDate
still 
null
. Poll with 
sf org get snapshot
until 
Status
is 
Active
(verified live against a real Dev Hub — see 
examples/create_success_output.json
vs 
examples/get_output.json
) before using the snapshot to create scratch orgs.
操作用户意图通过 Bash 工具执行
Create仅使用名称创建 snapshot
sf org create snapshot --source-org <orgId|alias> --name <SnapshotName> --json
Create创建带 description 的 snapshot
sf org create snapshot --source-org <orgId|alias> --name <SnapshotName> --description "<desc>" --json
Create显式指定 Dev Hub
sf org create snapshot --source-org <orgId|alias> --name <SnapshotName> --target-dev-hub <devHub> --json
Get检查 snapshot 的状态/详情
sf org get snapshot --snapshot <name|0Oo...> --json
List列出 Dev Hub 中的所有 snapshot
sf org list snapshot --json
List列出将在 N 天内过期的 snapshot
sf org list snapshot --json
→ 使用 
jq
筛选 
ExpirationDate
（见 
references/cli_flags.md
）
Delete删除 snapshot（带确认提示）
sf org delete snapshot --snapshot <name|0Oo...> --json
Delete删除但不提示（脚本/CI）
sf org delete snapshot --snapshot <name|0Oo...> --no-prompt --json
Delete删除多个/全部 snapshot首先执行 
sf org list snapshot --json
，向用户确认目标名称，然后对每个 snapshot 分别执行一次 
sf org delete snapshot --snapshot <name>
——没有批量删除命令
Snapshot 创建是异步操作。 
create
返回的记录最初通常具有 
Status
= 
InProgress
，同时 
ExpirationDate
仍为 
null
。使用 
sf org get snapshot
轮询，直到 
Status
变为 
Active
（已在真实 Dev Hub 上验证——见 
examples/create_success_output.json
与 
examples/get_output.json
），然后再使用该 snapshot 创建 scratch org。

Rules / Constraints

规则/限制

ConstraintRationale
Always use 
--json
flag		Provides structured output for reliable parsing and error handling
All commands operate against a Dev Hub
--target-dev-hub
(not 
--target-org
) — optional only if the 
target-dev-hub
config is set
Dev Hub must have Scratch Org Snapshots enabledOtherwise commands fail — contact Salesforce to enable it
Source org (create) must be a scratch orgSnapshots only work with scratch orgs
Snapshot names must be unique in the Dev Hub, ≤15 charactersLonger names fail with 
STRING_TOO_LONG
(verified live)
Creation is asynchronous
create
may return before the snapshot is 
Active
— poll with 
sf org get snapshot
There is no update/rename/extend-expiration command.Verified — the CLI (and the underlying platform object) exposes only create/get/list/delete. To change a snapshot's name, description, or expiration, delete it and create a new one.
There is no bulk-delete command.Each 
sf org delete snapshot
call removes exactly one snapshot
sf org list snapshot
has no server-side filters		Returns every visible snapshot; filter status/expiry client-side (e.g. with 
jq
)
delete
prompts for confirmation by default		Use 
--no-prompt
(
-p
) for non-interactive/CI use
Bulk/
--no-prompt
deletes require an explicit confirmation step		Before deleting multiple or all snapshots — or any delete with 
--no-prompt
— first run 
sf org list snapshot --json
, echo the resolved target names back to the user, and get explicit confirmation. Deletion is irreversible.
Permissions affect visibility/deletionUsers see/delete only their own snapshots unless a Dev Hub admin grants View All / Modify All
限制原因
始终使用 
--json
flag		提供结构化输出，以便可靠地解析和处理错误
所有命令都针对 Dev Hub 操作使用 
--target-dev-hub
（而不是 
--target-org
）——仅当已设置 
target-dev-hub
配置时才能省略
Dev Hub 必须启用 Scratch Org Snapshots否则命令将失败——请联系 Salesforce 启用该功能
Source org（create）必须是 scratch orgSnapshot 仅适用于 scratch org
Snapshot 名称在 Dev Hub 中必须唯一，且不超过 15 个字符更长的名称会触发 
STRING_TOO_LONG
（已实时验证）
创建过程是异步的
create
可能在 snapshot 变为 
Active
之前返回——使用 
sf org get snapshot
轮询
没有更新/重命名/延长过期时间的命令。已验证——CLI（以及底层 platform object）仅公开 create/get/list/delete。若要更改 snapshot 的名称、description 或 expiration，请删除后重新创建。
没有批量删除命令。每次 
sf org delete snapshot
调用仅删除一个 snapshot
sf org list snapshot
没有服务端筛选功能		返回所有可见 snapshot；在客户端筛选状态/过期时间（例如使用 
jq
）
delete
默认会提示确认		在非交互式/CI 场景中使用 
--no-prompt
（
-p
）
批量删除或使用 
--no-prompt
删除需要明确的确认步骤		在删除多个或全部 snapshot 之前，或对任何使用 
--no-prompt
的删除操作之前，先执行 
sf org list snapshot --json
，将解析出的目标名称回显给用户，并获得明确确认。删除操作不可撤销。
权限会影响可见性和删除权限除非 Dev Hub 管理员授予 View All / Modify All 权限，否则用户只能查看/删除自己的 snapshot

Troubleshooting

故障排除

IssueResolution
@salesforce/plugin-signups does not exist in the registry
Snapshot commands live in the 
signups
plugin, bundled with a normal 
sf
install. This means the CLI environment is incomplete (slim/offline image) — do NOT attempt 
sf plugins install
in an offline environment, it will fail and loop. Advise repairing the environment (
sf update
, or a fresh install) from a connected machine.
Scratch Org Snapshots isn't enabled for your Dev Hub.
The Dev Hub lacks the snapshot feature — contact Salesforce to enable it
No snapshot found with the given name or id: <value>
(
SingleRecordQuery_NoRecords
)		Verified live on 
get
/
delete
— the name/ID doesn't exist in this Dev Hub. Run 
sf org list snapshot --json
to see available snapshots
STRING_TOO_LONG
— "Org Snapshot Name: data value too large... (max length=15)"		Verified live — the 
--name
value exceeds 15 characters. Shorten it and retry
Snapshot name already exists (
DuplicateValue
)		Names must be unique per Dev Hub — choose a different name
Status
is 
InProgress
for a while		Creation is asynchronous — keep polling 
sf org get snapshot
until 
Status
becomes 
Active
Status
is 
Error
(see the 
Error
field)		Read the 
Error
field, delete the failed snapshot, and recreate
NotADevHubError
The targeted org isn't a Dev Hub — point 
--target-dev-hub
at an actual Dev Hub
No default Dev Hub org foundProvide 
--target-dev-hub <alias>
or set a default with 
sf config set target-dev-hub=<alias>
问题解决方案
@salesforce/plugin-signups does not exist in the registry
Snapshot 命令位于 
signups
plugin 中，标准 
sf
安装会捆绑该插件。这意味着 CLI 环境不完整（slim/offline image）——不要在离线环境中尝试 
sf plugins install
，否则会失败并陷入循环。建议在联网机器上修复环境（
sf update
，或全新安装）。
Scratch Org Snapshots isn't enabled for your Dev Hub.
Dev Hub 缺少 snapshot 功能——请联系 Salesforce 启用该功能
No snapshot found with the given name or id: <value>
（
SingleRecordQuery_NoRecords
）		已在 
get
/
delete
上实时验证——该名称/ID 在此 Dev Hub 中不存在。运行 
sf org list snapshot --json
查看可用 snapshot
STRING_TOO_LONG
——“Org Snapshot Name: data value too large... (max length=15)”		已实时验证——
--name
值超过 15 个字符。请缩短后重试
Snapshot 名称已存在（
DuplicateValue
）		名称在每个 Dev Hub 中必须唯一——请选择其他名称
Status
在一段时间内保持 
InProgress
创建过程是异步的——持续使用 
sf org get snapshot
轮询，直到 
Status
变为 
Active
Status
为 
Error
（见 
Error
字段）		读取 
Error
字段，删除失败的 snapshot，然后重新创建
NotADevHubError
目标 org 不是 Dev Hub——请将 
--target-dev-hub
指向实际的 Dev Hub
未找到默认 Dev Hub org提供 
--target-dev-hub <alias>
，或使用 
sf config set target-dev-hub=<alias>
设置默认值

Output Expectations

输出预期

All commands return JSON when 
--json
is used. 
get
/
list
return the raw 
OrgSnapshot
sobject record(s) — verified live, these include the sobject 
attributes
wrapper plus 
Id
, 
SnapshotName
, 
Description
, 
Status
(
New
, 
InProgress
, 
Active
, 
Error
, 
Expired
, or 
Deleted
), 
SourceOrg
, 
CreatedDate
, 
LastModifiedDate
, 
ExpirationDate
(
null
until 
Active
), and 
Error
.
  • Create → a single snapshot record (
    Status
    is 
    InProgress
    immediately after creation; 
    ExpirationDate
    is 
    null
    ).
  • Get → a single snapshot record — use it to poll 
    Status
    .
  • List → an array of snapshot records, ordered by 
    CreatedDate
    . Empty array if none exist.
  • Delete → 
    { "id": "0Oo...", "success": true, "errors": [] }
    . No result if the user declines the confirmation prompt.
See the example files below for exact response structures (captured live against a real Dev Hub, not assumed).
使用 
--json
时，所有命令都会返回 JSON。
get
/
list
返回原始 
OrgSnapshot
sobject 记录——已实时验证，这些记录包含 sobject 
attributes
wrapper，以及 
Id
、
SnapshotName
、
Description
、
Status
（
New
、
InProgress
、
Active
、
Error
、
Expired
或 
Deleted
）、
SourceOrg
、
CreatedDate
、
LastModifiedDate
、
ExpirationDate
（在 
Active
之前为 
null
）和 
Error
。
  • Create → 单个 snapshot 记录（创建后 
    Status
    立即为 
    InProgress
    ；
    ExpirationDate
    为 
    null
    ）。
  • Get → 单个 snapshot 记录——使用它轮询 
    Status
    。
  • List → snapshot 记录数组，按 
    CreatedDate
    排序。如果不存在，则返回空数组。
  • Delete → 
    { "id": "0Oo...", "success": true, "errors": [] }
    。如果用户拒绝确认提示，则不会返回结果。
请参阅下方示例文件了解精确的响应结构（这些结构均来自真实 Dev Hub 的实时捕获，并非假设）。

Cross-Skill Integration

跨 Skill 集成

NeedDelegate to
Create a scratch org from a snapshot
dx-org-manage
skill (set 
snapshot
to the snapshot name in the definition file, or 
--snapshot <name>
)
Create/list/delete an org shape instead of a snapshot
dx-org-shape-manage
skill
需求委托给
从 snapshot 创建 scratch org
dx-org-manage
skill（在 definition 文件中将 
snapshot
设置为 snapshot 名称，或使用 
--snapshot <name>
）
创建/列出/删除 org shape 而非 snapshot
dx-org-shape-manage
skill

Reference File Index

参考文件索引

FileWhen to read
references/cli_flags.md
Detailed flag reference across create/get/list/delete, including the 
jq
pipeline for filtering snapshots expiring soon
references/snapshot_usage.md
Using a snapshot name in a scratch org definition file, once it's 
Active
文件阅读时机
references/cli_flags.md
create/get/list/delete 的详细 flag 参考，包括筛选即将过期 snapshot 的 
jq
pipeline
references/snapshot_usage.md
snapshot 变为 
Active
后，在 scratch org definition 文件中使用 snapshot 名称

Example Files

示例文件

FilePurpose
examples/create_success_output.json
Successful snapshot creation (
Status: InProgress
)
examples/create_error_output.json
STRING_TOO_LONG
— name over 15 characters
examples/get_output.json
Get response for an 
Active
snapshot (
ExpirationDate
populated)
examples/list_output.json
List response — array of snapshot records
examples/delete_output.json
Successful delete response
文件用途
examples/create_success_output.json
成功创建 snapshot（
Status: InProgress
）
examples/create_error_output.json
STRING_TOO_LONG
——名称超过 15 个字符
examples/get_output.json
Active
snapshot 的 Get 响应（
ExpirationDate
已填充）
examples/list_output.json
List 响应——snapshot 记录数组
examples/delete_output.json
成功删除的响应