platform-metadata-retrieve

어떤 스킬인가요?

ALWAYS USE THIS SKILL to retrieve metadata from an org to your local project using the sf project retrieve start command. Supports multiple retrieval modes: retrieve all remote changes, retrieve by source directory, retrieve by metadata type with wildcards, retrieve by manifest (package.xml), or retrieve by package name. Use when the user asks to retrieve, pull, sync, or download metadata, Apex classes, custom objects, or org changes. Supports source format (default) or metadata format (ZIP). DO NOT TRIGGER for deploying metadata (use platform-metadata-deploy skill), listing metadata, or generating package.xml. NEVER use MCP tools - always use this skill and the Bash tool with sf project retrieve start.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

{
  "status": 1,
  "name": "projectNotFoundError",
  "message": "This command is required to run from within an SFDX project.",
  "exitCode": 1,
  "commandName": "project retrieve start",
  "stack": "projectNotFoundError: This command is required to run from within an SFDX project.",
  "warnings": [],
  "data": {}
}

{
  "status": 0,
  "result": {
    "inboundFiles": [
      {
        "state": "Created",
        "fullName": "AccountService",
        "type": "ApexClass",
        "filePath": "force-app/main/default/classes/AccountService.cls"
      },
      {
        "state": "Created",
        "fullName": "AccountService",
        "type": "ApexClass",
        "filePath": "force-app/main/default/classes/AccountService.cls-meta.xml"
      },
      {
        "state": "Changed",
        "fullName": "Account",
        "type": "CustomObject",
        "filePath": "force-app/main/default/objects/Account/Account.object-meta.xml"
      }
    ],
    "packages": [],
    "warnings": []
  }
}

# CLI Flags Reference

Complete reference for `sf project retrieve start` command flags.

## Target Org Flag (Optional When Default Is Set)

**Note:** `--target-org` is omitted when a default org is set via `sf config set target-org`. Only include this flag when the user specifies a non-default org or no default is configured.

| Flag | Alias | Description | Example |
|------|-------|-------------|---------|
| `--target-org` | `-o` | Username or alias of target org (omit if using default) | `--target-org my-org` |

## Retrieval Mode Flags (Mutually Exclusive Groups)

| Flag | Alias | Description | Example |
|------|-------|-------------|---------|
| `--source-dir` | `-d` | File paths to retrieve from org | `--source-dir force-app` |
| `--metadata` | `-m` | Metadata component names (wildcards supported) | `--metadata ApexClass:MyClass*` |
| `--manifest` | `-x` | Path to manifest (package.xml) file | `--manifest config/package.xml` |
| `--package-name` | `-n` | Package names to retrieve (reference only) | `--package-name MyPackage` |

**Note:** Cannot combine `--manifest` with `--metadata` or `--source-dir`. Choose one retrieval mode.

## Optional Flags

| Flag | Alias | Description | Example |
|------|-------|-------------|---------|
| `--api-version` | `-a` | Target API version for retrieve | `--api-version 66.0` |
| `--ignore-conflicts` | `-c` | Ignore conflicts and overwrite local files | `--ignore-conflicts` |
| `--output-dir` | `-r` | Directory root for retrieved source files | `--output-dir retrieved` |
| `--wait` | `-w` | Minutes to wait for completion (default: 33) | `--wait 60` |

## Metadata API Format Flags

| Flag | Description | Example |
|------|-------------|---------|
| `--target-metadata-dir` | Directory for metadata format files or ZIP | `--target-metadata-dir output` |
| `--unzip` | Extract files from retrieved ZIP | `--unzip` |
| `--single-package` | ZIP points to single package directory | `--single-package` |
| `--zip-file-name` | Filename for retrieved ZIP | `--zip-file-name metadata.zip` |

## Usage Patterns

### Basic Retrieve All Changes

```bash
sf project retrieve start --json
```

### Retrieve by Source Directory

```bash
sf project retrieve start --source-dir force-app --target-org my-org --json
```

### Retrieve Multiple Directories

```bash
sf project retrieve start --source-dir force-app/main/default/classes --source-dir force-app/main/default/objects --json
```

### Retrieve by Metadata Type

```bash
sf project retrieve start --metadata ApexClass --target-org my-org --json
```

### Retrieve Specific Component

```bash
sf project retrieve start --metadata ApexClass:AccountService --target-org my-org --json
```

### Retrieve with Wildcard

```bash
sf project retrieve start --metadata 'ApexClass:Account*' --target-org my-org --json
```

### Retrieve Multiple Metadata Types

```bash
sf project retrieve start --metadata CustomObject --metadata ApexClass --target-org my-org --json
```

### Retrieve by Manifest

```bash
sf project retrieve start --manifest config/package.xml --target-org my-org --json
```

### Retrieve by Package Name

```bash
sf project retrieve start --package-name MyPackage --target-org my-org --json
```

### Retrieve Multiple Packages

```bash
sf project retrieve start --package-name Package1 --package-name "Package With Spaces" --target-org my-org --json
```

### Retrieve to Metadata Format

```bash
sf project retrieve start --source-dir force-app --target-metadata-dir output --target-org my-org --json
```

### Retrieve and Extract ZIP

```bash
sf project retrieve start --source-dir force-app --target-metadata-dir output --unzip --target-org my-org --json
```

### Ignore Conflicts

```bash
sf project retrieve start --source-dir force-app --ignore-conflicts --target-org my-org --json
```

### Custom Output Directory

```bash
sf project retrieve start --source-dir force-app --output-dir retrieved --target-org my-org --json
```

### Override Wait Time

```bash
sf project retrieve start --manifest config/package.xml --wait 60 --target-org my-org --json
```

### Override API Version

```bash
sf project retrieve start --source-dir force-app --api-version 66.0 --target-org my-org --json
```

# Retrieval Modes

Complete guide to the five retrieval modes supported by `sf project retrieve start`.

## Mode 1: Retrieve All Remote Changes

**When to use:** Sync all org changes to local project (most common workflow)

```bash
sf project retrieve start --json
```

- Retrieves all metadata that changed in the org since last sync
- Only works with orgs that allow source tracking (scratch/sandbox)
- Does not work with production orgs
- Most common command for daily development workflow

## Mode 2: Retrieve by Source Directory

**When to use:** Pull specific directory/file from org

```bash
sf project retrieve start --source-dir force-app --target-org my-org --json
sf project retrieve start --source-dir force-app/main/default/classes --target-org my-org --json
sf project retrieve start --source-dir force-app/main/default/classes/AccountService.cls --target-org my-org --json
```

- Can target entire directory or single file
- Retrieves directory contents recursively
- Multiple `--source-dir` flags supported
- Works with all org types (scratch, sandbox, production)

**Multiple directories:**

```bash
sf project retrieve start --source-dir force-app/main/default/classes --source-dir force-app/main/default/objects --json
```

## Mode 3: Retrieve by Metadata Type

**When to use:** Pull specific metadata types or components

```bash
sf project retrieve start --metadata ApexClass --json
sf project retrieve start --metadata ApexClass:AccountService --json
sf project retrieve start --metadata 'ApexClass:Account*' --json
```

- Retrieve all components of a type: `--metadata ApexClass`
- Retrieve specific component: `--metadata ApexClass:AccountService`
- Retrieve with wildcard pattern: `--metadata 'ApexClass:Account*'` (requires quotes)
- Multiple `--metadata` flags supported
- Works with all org types

**Wildcards:**

```bash
sf project retrieve start --metadata 'CustomObject:SBQQ__*' --json
sf project retrieve start --metadata 'ListView:Case*' --json
```

**Multiple types:**

```bash
sf project retrieve start --metadata CustomObject --metadata ApexClass --json
```

## Mode 4: Retrieve by Manifest (package.xml)

**When to use:** Pull metadata listed in package.xml

```bash
sf project retrieve start --manifest path/to/package.xml --json
```

- Retrieves all components specified in the manifest file
- Cannot be combined with `--metadata` or `--source-dir`
- Works with all org types
- Useful for CI/CD pipelines and release management

## Mode 5: Retrieve by Package Name

**When to use:** Extract package metadata for reference only

```bash
sf project retrieve start --package-name MyPackageName --json
sf project retrieve start --package-name "Package With Spaces" --json
```

- Retrieves metadata into child directory matching package name
    - Cannot be used with the `--output-dir` flag 
- Retrieved metadata is **for reference only** — not for development/deployment
- Do not add to source control
- For package development, use manifest or source-dir modes instead
- Works with all org types

**Multiple packages:**

```bash
sf project retrieve start --package-name Package1 --package-name "Package With Spaces" --package-name Package3 --json
```

## Output Format Options

### Source Format (Default)

```bash
sf project retrieve start --source-dir force-app --json
```

- Retrieves in Salesforce DX source format
- Files written to package directories defined in `sfdx-project.json`
- Default behavior

### Metadata Format (ZIP)

```bash
sf project retrieve start --source-dir force-app --target-metadata-dir output --json
```

- Retrieves as ZIP file in metadata format
- Use `--unzip` to automatically extract contents
- Use `--zip-file-name` to specify ZIP filename
- Use `--single-package` for single package directory structure

**Extract automatically:**

```bash
sf project retrieve start --source-dir force-app --target-metadata-dir output --unzip --json
```

## Conflict Handling

### Ignore Conflicts (Scratch/Sandbox Only)

**⚠️ Warning:** Do not use `--ignore-conflicts` flag without confirming with the user first. This flag overwrites local changes and may result in lost work.

```bash
sf project retrieve start --source-dir force-app --ignore-conflicts --json
```

- Overwrites local files even if they have uncommitted changes
- Only works on orgs that allow source tracking (scratch/sandbox)
- No effect on production orgs

### Retrieve to Separate Directory

```bash
sf project retrieve start --source-dir force-app --output-dir retrieved-backup --json
```

- Retrieves to custom directory instead of default package directory
- Cannot use directory that matches `sfdx-project.json` packageDirectories
- Useful for comparing org state with local state
- Running multiple times adds/overwrites files in target directory

## Common Patterns

### Retrieve Specific Apex Class

```bash
sf project retrieve start --metadata ApexClass:MyApexClass --ignore-conflicts --json
```

### Retrieve All Custom Objects with Namespace

```bash
sf project retrieve start --metadata 'CustomObject:SBQQ__*' --json
```

### Retrieve All List Views for Standard Object

```bash
sf project retrieve start --metadata 'ListView:Case*' --json
```

### Retrieve to Metadata Format and Extract

```bash
sf project retrieve start --source-dir force-app --target-metadata-dir output --unzip --json
```

---
name: platform-metadata-retrieve
description: "ALWAYS USE THIS SKILL to retrieve metadata from an org to your local project using the sf project retrieve start command. Supports multiple retrieval modes: retrieve all remote changes, retrieve by source directory, retrieve by metadata type with wildcards, retrieve by manifest (package.xml), or retrieve by package name. Use when the user asks to retrieve, pull, sync, or download metadata, Apex classes, custom objects, or org changes. Supports source format (default) or metadata format (ZIP). DO NOT TRIGGER for deploying metadata (use platform-metadata-deploy skill), listing metadata, or generating package.xml. NEVER use MCP tools - always use this skill and the Bash tool with sf project retrieve start."
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 |