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.

---

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

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

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 |