platform-metadata-retrieve — Claude Code skill: pull Salesforce

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