このスキルを**常に使用**して、組織のメタデータ（データ構造や設定情報）をローカルプロジェクトに取得します。sf project retrieve start コマンドを使用します。 **対応する取得方法:** - リモート側の全ての変更を取得 - ソースディレクトリを指定して取得 - メタデータの種類を指定して取得（ワイルドカード対応） - マニフェスト（package.xml ファイル）を使って取得 - パッケージ名を指定して取得 **次のような場合に使用:** ユーザーがメタデータ、Apex クラス（プログラムコード）、カスタムオブジェクト（独自定義の情報形式）、または組織内の変更内容を取得・同期・ダウンロードするよう求めた場合。 **対応形式:** - ソース形式（デフォルト） - メタデータ形式（ZIP ファイル） **注意事項:** - メタデータのアップロード（platform-metadata-deploy スキルを使用）には使用しない - メタデータの一覧表示には使用しない - package.xml の生成には使用しない - MCP ツール（外部接続機能）は使用しない。このスキルと Bash ツール内で sf project retrieve start を使用する
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.
Salesforceの組織（クラウド上の開発環境）からメタデータ（設定情報やプログラムコード）をローカルプロジェクトに取得します。sf project retrieve start コマンドを使用し、すべての変更、ソースディレクトリ指定、メタデータ型指定（ワイルドカード対応）、マニフェスト指定、パッケージ名指定など複数の取得方法に対応しています。
Bashツールのみを使用 して sf project retrieve start を実行してください。MCP ツールは使用しないでください。
sf project retrieve start による全取得方法（すべての変更、ソースディレクトリ、メタデータ型、マニフェスト、パッケージ名）の実行、およびソース形式・メタデータ形式での出力platform-metadata-deploy を使用）、メタデータ型の一覧表示、package.xml ファイルの生成、ソース追跡コマンド（sf project retrieve preview）ユーザーの要望から以下を推測します：
sf project retrieve start を実行（--json フラグ付き）| ユーザーの意図 | Bash ツールで実行 |
|---|---|
| リモートのすべての変更を取得 | sf project retrieve start --json |
| ソースディレクトリ指定で取得 | sf project retrieve start --source-dir <path> --target-org <alias> --json |
| メタデータ型指定で取得 | sf project retrieve start --metadata <MetadataType:Name> --target-org <alias> --json |
| メタデータ型をワイルドカード指定で取得 | sf project retrieve start --metadata '<MetadataType:Pattern*>' --target-org <alias> --json |
| 複数のメタデータ型を取得 | sf project retrieve start --metadata <Type1> --metadata <Type2> --target-org <alias> --json |
| マニフェスト指定で取得 | sf project retrieve start --manifest <path/to/package.xml> --target-org <alias> --json |
| パッケージ名指定で取得 | sf project retrieve start --package-name <PackageName> --target-org <alias> --json |
| メタデータ形式（ZIP）で取得 | sf project retrieve start --source-dir <path> --target-metadata-dir <output> --unzip --target-org <alias> --json |
| 競合を無視して取得 | sf project retrieve start --source-dir <path> --ignore-conflicts --target-org <alias> --json |
| 制約 | 理由 |
|---|---|
常に --json フラグを使用 |
構造化された出力で確実なパースとエラー処理が可能 |
| Salesforce プロジェクトディレクトリ内で実行必須 | sfdx-project.json がリポジトリルートに必要 |
| ワイルドカードパターンはクォート必須 | クォートなしではシェルが展開してコマンドが失敗 |
| --manifest と --metadata または --source-dir は併用不可 | 相互排他的なフラグ — コマンドがエラー |
| すべての変更取得にはソース追跡が必須 | 本番環境はソース追跡未対応 — 他の取得方法を使用 |
| --ignore-conflicts は追跡可能な組織のみ対応 | 本番環境には無効；スクラッチ組織・サンドボックスのみ |
| --output-dir はプロジェクトディレクトリ内必須 | プロジェクト境界内のパスであることが必須 |
| --output-dir は package directory と重複不可 | sfdx-project.json の packageDirectories と一致すると失敗 |
| デフォルト待機時間は 33 分 | 大規模取得時は --wait フラグで変更可能 |
| パッケージ取得は参考用途のみ | 取得したパッケージメタデータは開発時にソース管理に追加しないこと |
| CustomField 取得は CustomObject を自動包含 | CustomField 取得時、完全なコンテキスト取得のため CustomObject も自動で追加 |
| 問題 | 解決方法 |
|---|---|
| 「This command is required to run from within an SFDX project」エラー | Salesforce プロジェクトディレクトリにいない — sfdx-project.json があるプロジェクトルートに cd |
| 「No org found for <alias>」エラー | 組織別名が存在しないか認証されていない — sf org list で確認 |
| 「This org does not support source tracking」メッセージ | 本番環境はすべての変更取得に非対応 — --source-dir、--metadata、--manifest を使用 |
| 「ERROR running project retrieve start: Cannot mix --manifest with --metadata or --source-dir」エラー | 競合するフラグを削除 — 1つの取得方法のみを使用 |
| ワイルドカードパターンが何も取得されない | パターンがクォートされていない — シングルクォートで囲む：'ApexClass:My*' |
| 「The package directory path in sfdx-project.json does not exist」エラー | 出力ディレクトリがパッケージディレクトリと競合 — 別のパスを使用 |
| 「Output directory must be inside the project」エラー | --output-dir がプロジェクト境界外 — プロジェクト内の相対パスを使用 |
| 取得がタイムアウト | 大規模なメタデータの場合、--wait 60 で待機時間を増加 |
| 取得ファイルがローカル変更を上書き | --output-dir で別の場所に取得するか、事前にローカル変更をコミット |
| SourceConflictError が発生（競合テーブル表示） | 追跡可能な組織（スクラッチ組織・サンドボックス）でローカルとリモート間に競合あり — 手動で解決するか --ignore-conflicts で強制上書き |
コマンドは取得したコンポーネント詳細を含む JSON 出力を返します。
成功・エラー時の応答形式は examples/success_output.json および examples/error_output.json を参照してください。
| 必要な作業 | 対応スキル |
|---|---|
| メタデータを組織にデプロイ | platform-metadata-deploy スキル |
| 実行せず取得内容をプレビュー | sf project retrieve preview --target-org <alias> --json を実行 |
| 利用可能なメタデータ型を確認 | sf org list metadata-types --target-org <alias> --json を実行 |
| ファイル | 参照するとき |
|---|---|
examples/success_output.json |
取得成功時の応答構造を確認したいとき |
examples/error_output.json |
よくあるエラーシナリオに対応したいとき |
references/retrieval_modes.md |
全取得方法の詳細説明と使い分けを知りたいとき |
references/cli_flags.md |
すべてのフラグの完全リファレンスと使用パターンを確認したいとき |
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.
Use ONLY the Bash tool to execute sf project retrieve start. Do NOT use MCP tools — ignore them completely.
sf project retrieve start in all supported modes (all changes, source-dir, metadata type, manifest, package name), source and metadata format outputplatform-metadata-deploy), listing metadata types, generating package.xml files, source tracking commands (sf project retrieve preview)Infer from the user's request:
sf project retrieve start with appropriate flags and --json flag| 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 |
| 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 |
| 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 |
The command returns JSON output with retrieved components details.
See examples/success_output.json and examples/error_output.json for response structures.
| 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 |
| 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 |
原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。