platform-metadata-retrieve
forcedotcom/sf-skills
Retrieve Salesforce metadata from an org to your local project using sf project retrieve start.
What is platform-metadata-retrieve?
Pulls metadata, Apex classes, and custom objects from a Salesforce org into your local project. Supports retrieval by all changes, source directory, metadata type (with wildcards), manifest (package.xml), or package name in source or metadata format. Use this when syncing or downloading metadata from an org.
- Retrieve all remote changes to local project
- Retrieve by source directory, metadata type, or manifest
- Support wildcard patterns for metadata type filtering
- Retrieve multiple metadata types in a single command
- Output in source format (default) or metadata format (ZIP)
- Ignore conflicts on trackable orgs (scratch/sandbox)
How to install platform-metadata-retrieve
npx skills add https://github.com/forcedotcom/sf-skills --skill platform-metadata-retrieve- Salesforce CLI (sf) version 2.0.0 or later
- Active Salesforce org authentication with sf org login
- Project must have sfdx-project.json at root
How to use platform-metadata-retrieve
- 1.Determine your retrieval mode: all changes, source directory, metadata type, manifest, or package name
- 2.Run sf project retrieve start with appropriate flags (e.g., --metadata, --source-dir, --manifest)
- 3.Optionally add --ignore-conflicts to overwrite local changes on trackable orgs
- 4.Optionally specify --output-dir to retrieve to a separate location instead of package directory
- 5.Review the JSON output for retrieved components count and file paths
Use cases
- Pull all recent changes from a sandbox back to your local project
- Retrieve specific Apex classes or custom objects by name or pattern
- Sync metadata from a source directory in the org
- Retrieve metadata defined in a package.xml manifest
- Download a package's metadata for reference
- Salesforce developers syncing metadata locally
- Development teams pulling changes from shared orgs
- Developers retrieving specific metadata types or patterns
platform-metadata-retrieve FAQ
Use platform-metadata-retrieve to pull metadata FROM an org TO your local project. Use platform-metadata-deploy to push metadata FROM your local project TO an org.
Yes, but only using --source-dir, --metadata, or --manifest modes. Production orgs don't support source tracking, so you cannot use 'retrieve all changes' mode.
On trackable orgs (scratch/sandbox), conflicts are reported. Use --ignore-conflicts to force overwrite local changes, or resolve conflicts manually first.
Yes. Wrap patterns like 'ApexClass:My*' in single quotes to prevent shell expansion and ensure the CLI receives the literal pattern.
Yes, use --output-dir to retrieve to a location inside your project. The path must be within the project boundary and cannot match your package directory.
Full instructions (SKILL.md)
Source of truth, from forcedotcom/sf-skills.
name: platform-metadata-retrieve description: "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." metadata: version: "1.0" domains: ["Platform", "Developer Experience"] relatedSkills: - "platform-metadata-deploy" cliTools: - tool: ["sf"] semver: ">=2.0.0"
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 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 |
Related skills
More from forcedotcom/sf-skills and the wider catalog.
platform-models-api-configure
Configure Claude Code or Claude Agent SDK to use Salesforce Models API with OrgJWT authentication.
platform-permission-set-generate
Generate correct, deployable Salesforce permission set metadata with object, field, and user permissions.
platform-policy-rule-generate
Author Salesforce Data Cloud PolicyRuleDefinition and PolicyRuleDefinitionSet metadata XML for governance policies.
platform-quick-deploy
Deploy validated Salesforce metadata to Production without re-running tests.
platform-report-generate
Generate and validate Salesforce Lightning Report metadata (.report-meta.xml) for tabular, summary, matrix, and joined reports.
platform-sandbox-configure
Manage Salesforce sandbox lifecycle—create, refresh, activate, and delete sandboxes via Connect REST API.