feat: add --root-with-dependencies flag to sf project retrieve start @W-23818734@ by WillieRuemmele · Pull Request #1626 · salesforcecli/plugin-deploy-retrieve

WillieRuemmele · 2026-08-11T21:16:18Z

Summary

Adds --root-with-dependencies flag to sf project retrieve start that exposes the Metadata API rootTypesWithDependencies request parameter
Flag accepts Bot and AiAgentDefinitionVersion as valid values (multiple allowed)
When explicitly provided, it takes precedence over the existing auto-detected ['Bot'] behavior for Agent pseudo-types

Work Item

@W-23818734@: Add a new flag for rootTypesWithDependencies MDAPI Option

Test plan

Unit tests pass (22 passing)
TypeScript compiles cleanly
CI passes
Manual test: sf project retrieve start --metadata ApexClass:Foo --include-dependents Bot --root-with-dependencies AiAgentDefinitionVersion

for full support: should merge and bump forcedotcom/source-deploy-retrieve#1819

…3818734@

…-23818734@

…W-23818734@

WillieRuemmele · 2026-08-12T17:50:45Z

QA

✅ :

 pd project retrieve start -m AiAgentDefinitionVersion -o orgfarm --root-with-dependencies AiAgentDefinitionVersion

 ────────────── Retrieving Metadata ──────────────

 Retrieving v68.0 metadata from epic.in.35369562fe09@orgfarm.salesforce.com using the v68.0 SOAP API

 ✔ Preparing retrieve request 3ms
 ✔ Sending request to org 579ms
 ✔ Waiting for the org to respond 33.14s
 ✔ Done 0ms

 Status: Succeeded
 Elapsed Time: 33.72s


Retrieved Source
┌─────────┬──────────────────────┬──────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ State   │ Name                 │ Type                     │ Path                                                                                                                                           │
├─────────┼──────────────────────┼──────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Created │ Devloop_Live_Agent   │ AiAgentDefinition        │ force-app/main/default/aiAgents/Devloop_Live_Agent.aiAgentDefinition-meta.xml                                                                  │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/Devloop_Live_Agent#1.aiAgentDefinitionVersion-meta.xml                   │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/agentGraph/Devloop_Live_Agent_v1_graph.json                              │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/agentScript/Devloop_Live_Agent_v1_definition.agent                       │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/localActions/AccountManagement/AnswerQuestionsWithKnowledge/input/schema │
│         │                      │                          │ .json                                                                                                                                          │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/localActions/AccountManagement/AnswerQuestionsWithKnowledge/output/schem │
│         │                      │                          │ a.json                                                                                                                                         │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/localActions/AccountManagement/ResetSecurePassword/input/schema.json     │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/localActions/AccountManagement/ResetSecurePassword/output/schema.json    │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/localActions/AccountManagement/UpdateVerifiedContact/input/schema.json   │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/localActions/AccountManagement/UpdateVerifiedContact/output/schema.json  │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/localActions/CaseManagement/AddCaseComment/input/schema.json             │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/localActions/CaseManagement/AddCaseComment/output/schema.json            │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/localActions/CaseManagement/AnswerQuestionsWithKnowledge/input/schema.js │
│         │                      │                          │ on                                                                                                                                             │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/localActions/CaseManagement/AnswerQuestionsWithKnowledge/output/schema.j │
│         │                      │                          │ son                                                                                                                                            │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/localActions/CaseManagement/CreateCaseEnhancedData/input/schema.json     │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/localActions/CaseManagement/CreateCaseEnhancedData/output/schema.json    │
│ Changed │ Devloop_Live_Agent#1 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#1/localActions/CaseManagement/GetCaseByVerifiedCaseNumber/input/schema.jso

vs

│ Created │ ASA1                 │ AiAgentDefinition        │ force-app/main/default/aiAgents/ASA1.aiAgentDefinition-meta.xml                                                                                │
│ Created │ Devloop_Live_Agent   │ AiAgentDefinition        │ force-app/main/default/aiAgents/Devloop_Live_Agent.aiAgentDefinition-meta.xml                                                                  │
│ Created │ ASA1#1               │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/ASA1#1/ASA1#1.aiAgentDefinitionVersion-meta.xml                                               │
│ Created │ ASA1#1               │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/ASA1#1/agentGraph/ASA1_v1_graph.json                                                          │
│ Created │ ASA1#1               │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/ASA1#1/agentScript/ASA1_v1_definition.agent                                                   │
.
.
.                                                                                                                              
│ Created │ Devloop_Live_Agent#2 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#2/localActions/ReservationManagement/FinalizeReservation/input/schema.json │
│ Created │ Devloop_Live_Agent#2 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#2/localActions/ReservationManagement/FinalizeReservation/output/schema.jso │
│         │                      │                          │ n                                                                                                                                              │
│ Created │ Devloop_Live_Agent#2 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#2/localActions/ReservationManagement/GetReservationTimeSlots/input/schema. │
│         │                      │                          │ json                                                                                                                                           │
│ Created │ Devloop_Live_Agent#2 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#2/localActions/ReservationManagement/GetReservationTimeSlots/output/schema │
│         │                      │                          │ .json                                                                                                                                          │
│ Created │ Devloop_Live_Agent#2 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#2/localActions/ReservationManagement/IdentifyCustomerByEmail/input/schema. │
│         │                      │                          │ json                                                                                                                                           │
│ Created │ Devloop_Live_Agent#2 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#2/localActions/ReservationManagement/IdentifyCustomerByEmail/output/schema │
│         │                      │                          │ .json                                                                                                                                          │
│ Created │ Devloop_Live_Agent#2 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#2/localActions/ServiceCustomerVerification/SendEmailVerificationCode/input │
│         │                      │                          │ /schema.json                                                                                                                                   │
│ Created │ Devloop_Live_Agent#2 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#2/localActions/ServiceCustomerVerification/SendEmailVerificationCode/outpu │
│         │                      │                          │ t/schema.json                                                                                                                                  │
│ Created │ Devloop_Live_Agent#2 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#2/localActions/ServiceCustomerVerification/VerifyCustomer/input/schema.jso │
│         │                      │                          │ n                                                                                                                                              │
│ Created │ Devloop_Live_Agent#2 │ AiAgentDefinitionVersion │ force-app/main/default/aiAgentDefinitionVersions/Devloop_Live_Agent#2/localActions/ServiceCustomerVerification/VerifyCustomer/output/schema.js │
│         │                      │                          │ on                                                                                                                                             │
│ Created │ SayHello             │ ApexClass                │ force-app/main/default/classes/SayHello.cls                                                                                                    │
│ Created │ SayHello             │ ApexClass                │ force-app/main/default/classes/SayHello.cls-meta.xml

while only the one extra component was retrieved, it's spidering for it

soridalac · 2026-08-12T20:59:31Z

+
+# flags.root-type-with-dependencies.description
+
+Sets the rootTypesWithDependencies Metadata API value. Will retrieve additional metadata types that depend on the type passed, currently only supports 'Bots' and 'AiAgentDefinitionVersion'


Suggested change

Sets the rootTypesWithDependencies Metadata API value. Will retrieve additional metadata types that depend on the type passed, currently only supports 'Bots' and 'AiAgentDefinitionVersion'

Sets the rootTypesWithDependencies Metadata API value. Will retrieve additional metadata types that depend on the type passed, currently only supports 'Bot' and 'AiAgentDefinitionVersion'

jshackell-sfdc

See my suggestions and additions!

Co-authored-by: Juliet Shackell <63259011+jshackell-sfdc@users.noreply.github.com>

…n-deploy-retrieve into wr/includeDependents

Fixed formatting issues in metadata retrieval commands.

feat: add --include-dependents flag to sf project retrieve start @W-2…

265a8c5

…3818734@

WillieRuemmele requested a review from a team as a code owner August 11, 2026 21:16

WillieRuemmele added 5 commits August 11, 2026 15:26

docs: my own spin

2741eff

fix: merge --include-dependents with auto-detected Bot pseudo-type @W…

01bb47e

…-23818734@

chore: fix return type

ac2117e

fix: loosen manifest NUT assertion to tolerate platform-added Flows @…

2c9892e

…W-23818734@

chore: update flag name

3f4c289

WillieRuemmele changed the title ~~feat: add --include-dependents flag to sf project retrieve start @W-23818734@~~ feat: add --root-with-dependencies flag to sf project retrieve start @W-23818734@ Aug 12, 2026

chore: change to root-type-with-dependencies

bef02a0

soridalac reviewed Aug 12, 2026

View reviewed changes

soridalac approved these changes Aug 12, 2026

View reviewed changes

jshackell-sfdc reviewed Aug 12, 2026

View reviewed changes

Comment thread messages/retrieve.start.md Outdated

Comment thread messages/retrieve.start.md Outdated

Comment thread messages/retrieve.start.md

WillieRuemmele and others added 6 commits August 12, 2026 15:45

Update messages/retrieve.start.md

3f60083

Co-authored-by: Juliet Shackell <63259011+jshackell-sfdc@users.noreply.github.com>

docs: updates

73f68b7

Merge branch 'wr/includeDependents' of github.com:salesforcecli/plugi…

e2cc6e0

…n-deploy-retrieve into wr/includeDependents

fix: fix formatting of examples in the help

ef7344d

Correct metadata syntax for SBQQ custom objects

103d756

Fixed formatting issues in metadata retrieval commands.

Update retrieve.start.md

bfca22b

jshackell-sfdc approved these changes Aug 12, 2026

View reviewed changes

WillieRuemmele merged commit 7a9acfa into main Aug 12, 2026
40 checks passed

WillieRuemmele deleted the wr/includeDependents branch August 12, 2026 22:11

Navigation Menu

Uh oh!

feat: add --root-with-dependencies flag to sf project retrieve start @W-23818734@ - #1626

feat: add --root-with-dependencies flag to sf project retrieve start @W-23818734@#1626
WillieRuemmele merged 13 commits into
mainfrom
wr/includeDependents

WillieRuemmele commented Aug 11, 2026 •

edited

Loading

Uh oh!

WillieRuemmele commented Aug 12, 2026 •

edited

Loading

Uh oh!

soridalac Aug 12, 2026

Uh oh!

jshackell-sfdc left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		# flags.root-type-with-dependencies.description

		Sets the rootTypesWithDependencies Metadata API value. Will retrieve additional metadata types that depend on the type passed, currently only supports 'Bots' and 'AiAgentDefinitionVersion'

Uh oh!

Conversation

WillieRuemmele commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Work Item

Test plan

Uh oh!

WillieRuemmele commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

QA

Uh oh!

soridalac Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

jshackell-sfdc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

WillieRuemmele commented Aug 11, 2026 •

edited

Loading

WillieRuemmele commented Aug 12, 2026 •

edited

Loading