Platform Metadata Retrieve
OfficialFreeEasily pull Salesforce metadata to your local project.
Free · Opens the source repo
What Platform Metadata Retrieve does
The Platform Metadata Retrieve skill is designed for developers working with Salesforce projects who need a reliable way to retrieve metadata from their Salesforce org. By utilizing the sf project retrieve start command, this skill supports various retrieval modes, allowing users to pull all remote changes, specify a source directory, select metadata types using wildcards, or retrieve by manifest and package name. This flexibility makes it suitable for different project needs, whether you are syncing changes or downloading specific components.
This skill is particularly useful when you want to keep your local project up-to-date with the latest changes from your Salesforce org. It streamlines the process of retrieving Apex classes, custom objects, and other metadata, ensuring that developers can focus on building rather than manual syncing. The command's output can be formatted as either source or metadata (ZIP), catering to different project requirements.
When using this skill, it is essential to follow the guidelines for execution. The skill mandates the use of the Bash tool to run the sf project retrieve start command, and it provides structured JSON output that includes details about the retrieved components. This structured approach aids in error handling and ensures that developers have clear visibility into what has been retrieved.
However, it is important to note that this skill is not intended for deploying metadata or generating package.xml files. It is specifically focused on retrieval tasks, making it a valuable addition to any Salesforce developer's toolkit when managing metadata efficiently.
When to use it
Use this skill when you need to pull metadata from a Salesforce org to your local project, particularly when syncing changes or downloading specific components.
When not to use it
Avoid using this skill for deploying metadata, listing metadata types, or generating package.xml files, as it is not designed for those tasks.
What you can build with it
Syncing Changes from Org
Use this skill to pull all remote changes from your Salesforce org to ensure your local project is up-to-date.
Retrieving Specific Metadata Types
Specify metadata types or use wildcards to retrieve only the components you need for your project.
Downloading Metadata via Manifest
Utilize a manifest file to retrieve a curated set of metadata, streamlining your development workflow.
How to install Platform Metadata Retrieve
View source1. Install with the skills CLI
npx skills add forcedotcom/sf-skills/platform-metadata-retrieve --agent claude-code2. Or install it manually
Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.
Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs
Inside SKILL.md
Written by forcedotcomplatform-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 startin 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 startwith appropriate flags and--jsonflag - 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 |
Frequently asked questions about Platform Metadata Retrieve
Similar skills
WinMD API Search
Easily find and explore Windows desktop APIs.
WebMCPify
Transform any web app into an agent-ready platform.
Phoenix Tracing
Instrument LLM applications with OpenInference tracing.
Foundry Hosted Agent CopilotKit
Guidance for developing agentic web apps on Azure.
Power Automate Foundation
Connect AI agents to Power Automate seamlessly.
Power Automate Flow Builder
Efficiently build and deploy Power Automate flows programmatically.