Platform Metadata Retrieve

作者 forcedotcom3c15867bdb9d無授權條款1K 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫昨天更新

ALWAYS USE THIS SKILL to retrieve metadata from an org to your local project with sf project retrieve start. Supports retrieval by all changes, source directory, metadata type (wildcards), manifest (package.xml), or package name, in source or metadata (ZIP) format. Use when the user asks to retrieve, pull, sync, or download metadata, Apex classes, or custom objects. DO NOT TRIGGER for deploying metadata (use platform-metadata-deploy), listing metadata, or generating a package.xml (use platform-manifest-generate). NEVER use MCP tools.

僅含說明DevOps & Cloud

AI 產生的概覽

使用 sf project retrieve start 指令將 Salesforce 組織中繼資料擷取到本機專案。

功能: 引導代理執行 sf project retrieve start，把 Salesforce 組織的中繼資料拉取到本機專案。涵蓋多種擷取模式：所有變更、來源目錄、帶萬用字元的中繼資料類型、清單檔以及套件名稱，並支援來源格式或中繼資料 ZIP 格式。也說明了旗標限制、疑難排解訊息以及預期的 JSON 輸出。
適用情境: 當使用者要求將 Salesforce 中繼資料、Apex 類別或自訂物件擷取、拉取、同步或下載到本機專案時使用。不適用於部署中繼資料、列出中繼資料或產生 package.xml。
執行需求: 需要 Salesforce CLI（sf，2.0.0 或更新版本），以及倉庫根目錄包含 sfdx-project.json 的 Salesforce 專案。需要已驗證的目標組織，並透過 Bash 工具執行指令。不附帶指令碼；包含範例 JSON 輸出與參考文件。

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.

Tool Restrictions

Use ONLY the Bash tool to execute sf project retrieve start. Do NOT use MCP tools — ignore them completely.

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)

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

Workflow

Match user request to command pattern below
Execute via Bash tool: sf project retrieve start with appropriate flags and --json flag
Return result with retrieved components count and file paths

Command Patterns

User intent	Execute 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`

Rules / Constraints

Constraint	Rationale
Always use `--json` flag	Provides structured output for reliable parsing and error handling
Must run from within Salesforce project	Command requires `sfdx-project.json` at repo root
Wildcard patterns must be quoted	Shell expansion breaks unquoted wildcards like `ApexClass:My*`
Cannot mix --manifest with --metadata or --source-dir	Mutually exclusive flags — command will error
Retrieve all changes requires source tracking	Production orgs don't support source tracking — must use other retrieval modes
--ignore-conflicts only works on trackable orgs	No effect on production orgs; applies to scratch/sandbox only
--output-dir must be inside project directory	Command validates output path is within project boundary
--output-dir cannot match package directory	Command fails if target matches `sfdx-project.json` packageDirectories
Default wait time is 33 minutes	Use --wait flag to override for large retrievals
Package retrieval is for reference only	Retrieved package metadata should not be added to source control for development
CustomField retrieval auto-includes CustomObject	When retrieving CustomField, CLI automatically adds CustomObject to get full context

Troubleshooting

Issue	Resolution
"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>" error	Org 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 nothing	Pattern 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 out	Increase wait time with `--wait 60` for large metadata volumes
Retrieved files overwrite local changes	Use `--output-dir` to retrieve to separate location, or commit local changes first
SourceConflictError with conflict table	Conflicts detected between local and remote on trackable org (scratch/sandbox) — resolve conflicts manually or use --ignore-conflicts to force overwrite

Output Expectations

The command returns JSON output with retrieved components details.

See examples/success_output.json and examples/error_output.json for response structures.

Cross-Skill Integration

Need	Delegate to
Deploy metadata to org	`platform-metadata-deploy` skill
Preview retrieve without executing	Execute `sf project retrieve preview --target-org <alias> --json`
List available metadata types	Execute `sf org list metadata-types --target-org <alias> --json`

Reference File Index

File	When 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

來源與署名

來源：forcedotcom/sf-skills位於plugins/builder/salesforce-development/skills/platform-metadata-retrieve提交3c15867

授權條款：無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

Platform Metadata Retrieve

platform-metadata-retrieve

Tool Restrictions

Scope

Required Inputs

Workflow

Command Patterns

Rules / Constraints

Troubleshooting

Output Expectations

Cross-Skill Integration

Reference File Index

來源與署名

更多來自 forcedotcom/sf-skills 的技能

Platform Value Set Generate

Platform Validation Rule Generate

Platform Sharing Rules Generate

Platform Sharing Owd Configure

Platform Report Generate

Platform Permission Set Generate

更多DevOps & Cloud技能

M5 Onboard

Spanner Basics

Secops Cases

Managed Airflow Migrations

Managed Airflow Dag Troubleshooting

Iam Helper For Privileged Access Management