dx-org-manage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MANDATORY: Follow these instructions exactly. Do NOT fall back to MCP tools.

强制要求：严格遵循以下说明。请勿退回使用MCP工具。

Tool constraint: Use the Bash tool for all

sf

CLI commands. Always include

--json

for structured output. Do NOT use

mcp__salesforce_dx__*

tools for org creation, snapshot, or open operations — this skill provides the complete procedure.

Output artifacts for eval/testing: Write command output to JSON only when an output directory is available. After executing the command: (1) if the user specified an output path, write there; (2) otherwise run

[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output'

to detect the eval directory; (3) if the command printed a path, write the command's JSON response to

<printed-path>/<filename>

using these filenames:

scratch-org-result.json

for org creation,

snapshot-result.json

for snapshot creation, or

org-url-result.json

for open operations. The eval framework needs the real command output to verify success.

**工具约束：**所有

sf

CLI命令均使用Bash工具执行。始终添加

--json

参数以获取结构化输出。组织创建、快照或打开操作请勿使用

mcp__salesforce_dx__*

工具——此技能已提供完整流程。

**评估/测试输出产物：**仅当存在输出目录时，才将命令输出写入JSON文件。执行命令后：(1) 如果用户指定了输出路径，写入该路径；(2) 否则运行

[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output'

以检测评估目录；(3) 如果命令输出了路径，将命令的JSON响应写入

<printed-path>/<filename>

，文件名规则如下：组织创建使用

scratch-org-result.json

，快照创建使用

snapshot-result.json

，打开组织操作使用

org-url-result.json

。评估框架需要真实的命令输出来验证操作是否成功。

Creating Scratch Orgs

创建临时组织（Scratch Orgs）

REQUIRED steps — execute in order:

Step 1. Identify creation method from user request:

Contains "definition file" or path to
```
.json
```
→ definition file method
Contains "snapshot" or "from snapshot" → snapshot method
Contains "org shape" or "source-org" → org shape method
Otherwise → run
```
ls config/project-scratch-def.json config/scratch-def.json 2>/dev/null | head -1
```
to detect a definition file. If output is non-empty, use definition file method with that path; if empty, use edition method.

Step 2. Check Dev Hub:

bash

sf config get target-dev-hub --json

If no Dev Hub is set, advise:
```
sf org login web --set-default-dev-hub
```
Do NOT proceed until a Dev Hub is confirmed.

Step 3. Build and execute the command based on method:

Definition file:

bash

sf org create scratch --definition-file <path> --target-dev-hub <alias> --alias <name> --json

Edition only:

bash

sf org create scratch --edition developer --target-dev-hub <alias> --alias <name> --json

From snapshot:

bash

sf org create scratch --snapshot <snapshot-name> --target-dev-hub <alias> --alias <name> --json

From org shape:

bash

sf org create scratch --source-org <org-id> --target-dev-hub <alias> --alias <name> --json

Apply these flags when requested:

```
--duration-days <days>
```
— default 7, max 30
```
--set-default
```
— make this the default org
```
--no-track-source
```
— disable source tracking (for CI/CD)

Step 4. MANDATORY - Run org list and write output: After the org is created, you MUST run this command:

bash

sf org list --json

Then:

Parse the JSON result and find the
```
scratchOrgs
```
array
Find the entry where
```
username
```
matches the username from Step 3's creation result
Extract that complete org object (it will include: alias, username, orgId, instanceUrl, loginUrl, isDefaultUsername, connectedStatus, lastUsed, etc.)
Report to the user:
- Created scratch org.
- Alias: [alias from the org list entry]
- Username: [username]
- Org ID: [orgId]
If an output directory is available (per the output artifacts rule above), write ONLY that extracted org object (NOT the full creation result) to
```
<output-dir>/scratch-org-result.json
```

Example: If

sf org list --json

returns

{"result": {"scratchOrgs": [{"alias": "feature-dev", "username": "test@example.com", "orgId": "00D...", ...}]}}

, write just the inner org object

{"alias": "feature-dev", "username": "test@example.com", "orgId": "00D...", ...}

to the file.

Do NOT write the creation command's output. Do NOT suggest verification steps to the user.

Error handling:

"Snapshot not found" → suggest

sf org list snapshot --target-dev-hub <alias>

"No default Dev Hub" → advise
```
sf org login web --set-default-dev-hub
```

When you need more detail:

For available features, settings, and definition file structure → load
```
references/definition_file_options.md
```
For edition selection guidance and comparison → load
```
references/edition_types.md
```
For snapshot workflow and post-creation usage → load
```
references/snapshot_usage.md
```
For complete scratch org creation workflow → load
```
references/creating-scratch-org.md
```

必填步骤——按顺序执行：

步骤1. 根据用户请求确定创建方式：

包含"definition file"或
```
.json
```
文件路径 → 使用定义文件方式
包含"snapshot"或"from snapshot" → 使用快照方式
包含"org shape"或"source-org" → 使用组织形态方式
其他情况 → 运行
```
ls config/project-scratch-def.json config/scratch-def.json 2>/dev/null | head -1
```
检测定义文件。如果输出非空，使用该路径的定义文件方式；如果为空，使用版本方式。

步骤2. 检查Dev Hub：

bash

sf config get target-dev-hub --json

如果未设置Dev Hub，建议执行：
```
sf org login web --set-default-dev-hub
```
确认Dev Hub已设置后再继续操作。

步骤3. 根据创建方式构建并执行命令：

定义文件方式：

bash

sf org create scratch --definition-file <path> --target-dev-hub <alias> --alias <name> --json

仅指定版本方式：

bash

sf org create scratch --edition developer --target-dev-hub <alias> --alias <name> --json

从快照创建：

bash

sf org create scratch --snapshot <snapshot-name> --target-dev-hub <alias> --alias <name> --json

从组织形态创建：

bash

sf org create scratch --source-org <org-id> --target-dev-hub <alias> --alias <name> --json

根据请求添加以下参数：

```
--duration-days <days>
```
— 默认7天，最长30天
```
--set-default
```
— 将此组织设为默认组织
```
--no-track-source
```
— 禁用源跟踪（适用于CI/CD场景）

**步骤4. 强制要求 - 运行组织列表命令并写入输出：**组织创建完成后，必须运行以下命令：

bash

sf org list --json

然后执行以下操作：

解析JSON结果，找到
```
scratchOrgs
```
数组
找到
```
username
```
与步骤3创建结果中用户名匹配的条目
提取完整的组织对象（包含：alias、username、orgId、instanceUrl、loginUrl、isDefaultUsername、connectedStatus、lastUsed等）
向用户报告：
- 临时组织已创建。
- 别名：[组织列表条目中的alias]
- 用户名：[username]
- 组织ID：[orgId]
如果存在输出目录（符合上述输出产物规则），仅将提取的组织对象（而非完整的创建结果）写入
```
<output-dir>/scratch-org-result.json
```

示例：如果

sf org list --json

{"result": {"scratchOrgs": [{"alias": "feature-dev", "username": "test@example.com", "orgId": "00D...", ...}]}}

，则仅将内部的组织对象

{"alias": "feature-dev", "username": "test@example.com", "orgId": "00D...", ...}

写入文件。

请勿写入创建命令的输出。请勿向用户建议验证步骤。

错误处理：

"Snapshot not found" → 建议执行

sf org list snapshot --target-dev-hub <alias>

"No default Dev Hub" → 建议执行
```
sf org login web --set-default-dev-hub
```

需要更多细节时：

如需了解可用功能、设置和定义文件结构 → 加载
```
references/definition_file_options.md
```
如需版本选择指导和对比 → 加载
```
references/edition_types.md
```
如需快照工作流和创建后使用指南 → 加载
```
references/snapshot_usage.md
```
如需完整的临时组织创建工作流 → 加载
```
references/creating-scratch-org.md
```

Creating Snapshots

创建快照

REQUIRED steps — execute in order:

Step 1. Get inputs:

Source org: scratch org ID or alias (from user)
Snapshot name: unique name (from user)
Description: optional (from user)

Step 2. Determine Dev Hub:

If user specifies a Dev Hub (alias or username) → use that value
Otherwise, check for default:

bash

sf config get target-dev-hub --json

If no default Dev Hub is set, advise:
```
sf org login web --set-default-dev-hub
```

Step 3. Execute:

bash

sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --target-dev-hub <devHub> --json

With description:

bash

sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --description "<desc>" --target-dev-hub <devHub> --json

Step 4. Report result: Returns JSON with SnapshotId and Status. If an output directory is available (per the output artifacts rule above), write the JSON response to

<output-dir>/snapshot-result.json

Error handling:

"NOT_FOUND" → Dev Hub doesn't have snapshot feature enabled
"Snapshot name already exists" → use a different unique name

When you need more detail:

For complete snapshot creation workflow and flag reference → load
```
references/creating-snapshot.md
```
For CLI flag reference → load
```
references/cli_flags.md
```

必填步骤——按顺序执行：

步骤1. 获取输入信息：

源组织：临时组织ID或别名（来自用户）
快照名称：唯一名称（来自用户）
描述：可选（来自用户）

步骤2. 确定Dev Hub：

如果用户指定了Dev Hub（别名或用户名）→ 使用该值
否则，检查默认Dev Hub：

bash

sf config get target-dev-hub --json

如果未设置默认Dev Hub，建议执行：
```
sf org login web --set-default-dev-hub
```

步骤3. 执行命令：

bash

sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --target-dev-hub <devHub> --json

带描述的命令：

bash

sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --description "<desc>" --target-dev-hub <devHub> --json

**步骤4. 报告结果：**返回包含SnapshotId和Status的JSON。如果存在输出目录（符合上述输出产物规则），将JSON响应写入

<output-dir>/snapshot-result.json

。

错误处理：

"NOT_FOUND" → Dev Hub未启用快照功能
"Snapshot name already exists" → 使用其他唯一名称

需要更多细节时：

如需完整的快照创建工作流和参数参考 → 加载
```
references/creating-snapshot.md
```
如需CLI参数参考 → 加载
```
references/cli_flags.md
```

Opening Orgs

打开组织

REQUIRED steps — execute in order:

Step 1. Match user request to command:

User wants	Command
Open default org	`sf org open --json`
Open specific org	`sf org open --target-org <alias> --json`
Specific browser	`sf org open --browser chrome --json`
Incognito mode	`sf org open --private --json`
Navigate to path	`sf org open --path '<path>' --json`
URL only (don't open)	`sf org open --url-only --json`
Open metadata file	`sf org open --source-file <file-path> --json`

Step 2. Execute the matching command using the Bash tool.

Step 3. Report result: Returns URL or opens browser. If an output directory is available (per the output artifacts rule above), write the JSON response to

<output-dir>/org-url-result.json

Error handling:

"no target org" → advise
```
sf config set target-org <alias>
```
"auth error" → advise
```
sf org login web --alias <alias>
```

When you need more detail:

For complete opening org workflow and all available flags → load
```
references/opening-org.md
```

必填步骤——按顺序执行：

步骤1. 将用户请求匹配到对应命令：

用户需求	命令
打开默认组织	`sf org open --json`
打开指定组织	`sf org open --target-org <alias> --json`
指定浏览器	`sf org open --browser chrome --json`
隐身模式	`sf org open --private --json`
导航到指定路径	`sf org open --path '<path>' --json`
仅获取URL（不打开）	`sf org open --url-only --json`
打开元数据文件	`sf org open --source-file <file-path> --json`

步骤2. 使用Bash工具执行匹配的命令。

**步骤3. 报告结果：**返回URL或打开浏览器。如果存在输出目录（符合上述输出产物规则），将JSON响应写入

<output-dir>/org-url-result.json

。

错误处理：

"no target org" → 建议执行
```
sf config set target-org <alias>
```
"auth error" → 建议执行
```
sf org login web --alias <alias>
```

需要更多细节时：

如需完整的打开组织工作流和所有可用参数 → 加载
```
references/opening-org.md
```

Reference File Index

参考文件索引

Load these reference files for detailed guidance:

File	When to read
`references/definition_file_options.md`	User needs to configure org features, settings, or advanced definition file options beyond basic org creation
`references/edition_types.md`	User asks which edition to choose or needs to understand edition differences
`references/snapshot_usage.md`	User wants to use snapshots in definition files or needs post-snapshot workflow guidance
`references/creating-scratch-org.md`	Troubleshooting scratch org creation failures or need complete workflow with all options
`references/cli_flags.md`	User needs complete snapshot CLI flag reference
`references/creating-snapshot.md`	Troubleshooting snapshot creation failures or need detailed snapshot workflow
`references/opening-org.md`	User needs to navigate to specific setup paths, open metadata files, or use advanced open flags

如需详细指导，请加载以下参考文件：

文件	适用场景
`references/definition_file_options.md`	用户需要配置组织功能、设置，或超出基础组织创建的高级定义文件选项时
`references/edition_types.md`	用户询问选择哪个版本，或需要了解版本差异时
`references/snapshot_usage.md`	用户希望在定义文件中使用快照，或需要快照创建后工作流指导时
`references/creating-scratch-org.md`	排查临时组织创建失败问题，或需要包含所有选项的完整工作流时
`references/cli_flags.md`	用户需要完整的快照CLI参数参考时
`references/creating-snapshot.md`	排查快照创建失败问题，或需要详细的快照工作流时
`references/opening-org.md`	用户需要导航到特定设置路径、打开元数据文件，或使用高级打开参数时

Example Files

示例文件

Example command outputs for testing and troubleshooting:

File	Purpose
`examples/scratch-orgs/success_definition_file.json`	Successful scratch org creation using `--definition-file`
`examples/scratch-orgs/success_edition.json`	Successful scratch org creation using `--edition developer`
`examples/scratch-orgs/success_snapshot.json`	Successful scratch org creation using `--snapshot`
`examples/scratch-orgs/error_no_devhub.json`	Error when Dev Hub not authenticated
`examples/scratch-orgs/error_timeout.json`	Timeout error during org creation (exit code 69)
`examples/snapshots/success_output.json`	Successful snapshot creation
`examples/snapshots/error_output.json`	Common snapshot error scenarios

用于测试和排查问题的示例命令输出：

文件	用途
`examples/scratch-orgs/success_definition_file.json`	使用 `--definition-file` 成功创建临时组织的输出
`examples/scratch-orgs/success_edition.json`	使用 `--edition developer` 成功创建临时组织的输出
`examples/scratch-orgs/success_snapshot.json`	使用 `--snapshot` 成功创建临时组织的输出
`examples/scratch-orgs/error_no_devhub.json`	未认证Dev Hub时的错误输出
`examples/scratch-orgs/error_timeout.json`	组织创建超时错误（退出码69）
`examples/snapshots/success_output.json`	成功创建快照的输出
`examples/snapshots/error_output.json`	常见快照错误场景的输出