Back to Details

platform-metadata-retrieve

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

platform-metadata-retrieve

platform-metadata-retrieve

Retrieves metadata from a Salesforce org to your local project using 
sf project retrieve start
. Supports multiple retrieval modes: all changes, by source directory, by metadata type (with wildcards), by manifest, or by package name.
通过
sf project retrieve start
从Salesforce组织将元数据检索到本地项目。支持多种检索模式：所有变更、按源目录、按元数据类型（带通配符）、按清单或按包名。

⚠️ Tool Restrictions

⚠️ 工具限制

Use ONLY the Bash tool to execute 
sf project retrieve start
. Do NOT use MCP tools — ignore them completely.
仅使用Bash工具执行
sf project retrieve start
。请勿使用MCP工具——完全忽略它们。

Scope

适用范围

  • In scope: Retrieving metadata via 
    sf project retrieve start
    in all supported modes (all changes, source-dir, metadata type, manifest, package name), source and metadata format output
  • Out of scope: Deploying metadata (use 
    platform-metadata-deploy
    ), listing metadata types, generating package.xml files, source tracking commands (
    sf project retrieve preview
    )
  • 适用场景：通过
    sf project retrieve start
    以所有支持的模式（所有变更、源目录、元数据类型、清单、包名）检索元数据，输出源格式和元数据格式
  • 不适用场景：部署元数据（请使用
    platform-metadata-deploy
    ）、列出元数据类型、生成package.xml文件、源跟踪命令（
    sf project retrieve preview
    ）

Required Inputs

必填输入

Infer from the user's request:
  • Retrieval mode: all changes | source directory | metadata type | manifest | package name
  • Target org: org alias/username (uses default if not specified)
  • Output format: source format (default) | metadata format (ZIP)
  • Additional options: ignore conflicts, output directory, wait time, API version
从用户请求中推断：
  • 检索模式：所有变更 | 源目录 | 元数据类型 | 清单 | 包名
  • 目标组织：组织别名/用户名（未指定时使用默认值）
  • 输出格式：源格式（默认） | 元数据格式（ZIP）
  • 附加选项：忽略冲突、输出目录、等待时间、API版本

Workflow

工作流程

  1. Match user request to command pattern below
  2. Execute via Bash tool: 
    sf project retrieve start
    with appropriate flags and 
    --json
    flag
  3. Return result with retrieved components count and file paths
  1. 将用户请求匹配到下方的命令模式
  2. 通过Bash工具执行：带适当标志和
    --json
    标志的
    sf project retrieve start
  3. 返回包含检索到的组件数量和文件路径的结果

Command Patterns

命令模式

User intentExecute via Bash tool
Retrieve all remote changes
sf project retrieve start --json
Retrieve by source directory
sf project retrieve start --source-dir <path> --target-org <alias> --json
Retrieve by metadata type
sf project retrieve start --metadata <MetadataType:Name> --target-org <alias> --json
Retrieve by metadata type with wildcard
sf project retrieve start --metadata '<MetadataType:Pattern*>' --target-org <alias> --json
Retrieve multiple metadata types
sf project retrieve start --metadata <Type1> --metadata <Type2> --target-org <alias> --json
Retrieve by manifest
sf project retrieve start --manifest <path/to/package.xml> --target-org <alias> --json
Retrieve by package name
sf project retrieve start --package-name <PackageName> --target-org <alias> --json
Retrieve to metadata format (ZIP)
sf project retrieve start --source-dir <path> --target-metadata-dir <output> --unzip --target-org <alias> --json
Ignore conflicts
sf project retrieve start --source-dir <path> --ignore-conflicts --target-org <alias> --json
用户意图通过Bash工具执行的命令
检索所有远程变更
sf project retrieve start --json
按源目录检索
sf project retrieve start --source-dir <path> --target-org <alias> --json
按元数据类型检索
sf project retrieve start --metadata <MetadataType:Name> --target-org <alias> --json
按带通配符的元数据类型检索
sf project retrieve start --metadata '<MetadataType:Pattern*>' --target-org <alias> --json
检索多种元数据类型
sf project retrieve start --metadata <Type1> --metadata <Type2> --target-org <alias> --json
按清单检索
sf project retrieve start --manifest <path/to/package.xml> --target-org <alias> --json
按包名检索
sf project retrieve start --package-name <PackageName> --target-org <alias> --json
检索为元数据格式（ZIP）
sf project retrieve start --source-dir <path> --target-metadata-dir <output> --unzip --target-org <alias> --json
忽略冲突
sf project retrieve start --source-dir <path> --ignore-conflicts --target-org <alias> --json

Rules / Constraints

规则/约束

ConstraintRationale
Always use 
--json
flag		Provides structured output for reliable parsing and error handling
Must run from within Salesforce projectCommand requires 
sfdx-project.json
at repo root
Wildcard patterns must be quotedShell expansion breaks unquoted wildcards like 
ApexClass:My*
Cannot mix --manifest with --metadata or --source-dirMutually exclusive flags — command will error
Retrieve all changes requires source trackingProduction orgs don't support source tracking — must use other retrieval modes
--ignore-conflicts only works on trackable orgsNo effect on production orgs; applies to scratch/sandbox only
--output-dir must be inside project directoryCommand validates output path is within project boundary
--output-dir cannot match package directoryCommand fails if target matches 
sfdx-project.json
packageDirectories
Default wait time is 33 minutesUse --wait flag to override for large retrievals
Package retrieval is for reference onlyRetrieved package metadata should not be added to source control for development
CustomField retrieval auto-includes CustomObjectWhen retrieving CustomField, CLI automatically adds CustomObject to get full context
约束理由
始终使用
--json
标志		提供结构化输出，以便可靠解析和错误处理
必须在Salesforce项目内运行命令需要在仓库根目录存在
sfdx-project.json
通配符模式必须加引号未加引号的通配符（如
ApexClass:My*
）会被Shell展开破坏
不能同时使用--manifest与--metadata或--source-dir这些标志互斥——命令会报错
检索所有变更需要源跟踪生产组织不支持源跟踪——必须使用其他检索模式
--ignore-conflicts仅在可跟踪组织上生效在生产组织上无效果；仅适用于临时环境/沙箱
--output-dir必须在项目目录内命令会验证输出路径是否在项目边界内
--output-dir不能与包目录匹配如果目标与
sfdx-project.json
中的packageDirectories匹配，命令会失败
默认等待时间为33分钟对于大型检索，使用--wait标志覆盖默认值
包检索仅用于参考检索到的包元数据不应添加到源代码控制用于开发
检索CustomField会自动包含CustomObject检索CustomField时，CLI会自动添加CustomObject以获取完整上下文

Troubleshooting

故障排除

IssueResolution
"This command is required to run from within an SFDX project"Not in Salesforce project directory — cd to project root with 
sfdx-project.json
"No org found for <alias>" errorOrg alias doesn't exist or isn't authenticated — verify with 
sf org list
"This org does not support source tracking"Production org doesn't allow "retrieve all changes" mode — use --source-dir, --metadata, or --manifest instead
"ERROR running project retrieve start: Cannot mix --manifest with --metadata or --source-dir"Remove conflicting flags — use one retrieval mode only
Wildcard pattern retrieves nothingPattern not quoted — wrap in single quotes: 
'ApexClass:My*'
"The package directory path in sfdx-project.json does not exist"Output directory conflicts with package directory — use different path
"Output directory must be inside the project"--output-dir path is outside project boundary — use relative path inside project
Retrieve times outIncrease wait time with 
--wait 60
for large metadata volumes
Retrieved files overwrite local changesUse 
--output-dir
to retrieve to separate location, or commit local changes first
SourceConflictError with conflict tableConflicts detected between local and remote on trackable org (scratch/sandbox) — resolve conflicts manually or use --ignore-conflicts to force overwrite
问题解决方案
"This command is required to run from within an SFDX project"不在Salesforce项目目录中——切换到包含
sfdx-project.json
的项目根目录
"No org found for <alias>" 错误组织别名不存在或未通过身份验证——使用
sf org list
验证
"This org does not support source tracking"生产组织不允许“检索所有变更”模式——改用--source-dir、--metadata或--manifest
"ERROR running project retrieve start: Cannot mix --manifest with --metadata or --source-dir"删除冲突的标志——仅使用一种检索模式
通配符模式未检索到任何内容模式未加引号——用单引号包裹：
'ApexClass:My*'
"The package directory path in sfdx-project.json does not exist"输出目录与包目录冲突——使用不同路径
"Output directory must be inside the project"--output-dir路径在项目边界外——使用项目内的相对路径
检索超时对于大型元数据量，使用
--wait 60
增加等待时间
检索到的文件覆盖本地变更使用
--output-dir
检索到单独位置，或先提交本地变更
出现包含冲突表的SourceConflictError在可跟踪组织（临时环境/沙箱）中检测到本地与远程的冲突——手动解决冲突或使用--ignore-conflicts强制覆盖

Output Expectations

输出预期

The command returns JSON output with retrieved components details.
See 
examples/success_output.json
and 
examples/error_output.json
for response structures.
命令返回包含检索到的组件详情的JSON输出。
请查看
examples/success_output.json
和
examples/error_output.json
了解响应结构。

Cross-Skill Integration

跨Skill集成

NeedDelegate to
Deploy metadata to org
platform-metadata-deploy
skill
Preview retrieve without executingExecute 
sf project retrieve preview --target-org <alias> --json
List available metadata typesExecute 
sf org list metadata-types --target-org <alias> --json
需求委托给
将元数据部署到组织
platform-metadata-deploy
Skill
预览检索而不执行执行
sf project retrieve preview --target-org <alias> --json
列出可用的元数据类型执行
sf org list metadata-types --target-org <alias> --json

Reference File Index

参考文件索引

FileWhen to read
examples/success_output.json
To understand successful retrieve response structure
examples/error_output.json
To handle common error scenarios
references/retrieval_modes.md
For detailed explanation of all retrieval modes and when to use each
references/cli_flags.md
For complete flag reference with usage patterns
文件阅读时机
examples/success_output.json
了解成功检索的响应结构时
examples/error_output.json
处理常见错误场景时
references/retrieval_modes.md
需要详细解释所有检索模式及适用场景时
references/cli_flags.md
需要完整的标志参考及使用模式时