[Metadata Decompose] sf project retrieve start --metadata unable to retrieve individual CustomLabel

[RayHWLau]

Summary

sf project retrieve command failed to retrieve individual Custom Label after opt-in to decomposeCustomLabelsBeta

Steps To Reproduce

1. Install latest salesforce cli (currently 2.37.4)
2. Opt-in to decomposeCustomLabelsBeta in sfdx-project.json
3. Open Sandbox, create a new Custom Label with developer name TestCustomLabel
4. open salesforce cli in vscode / command prompt. Authorize the sandbox
5. Execute following command in VSCode / Command Prompt:

sf project retrieve start --metadata CustomLabel:TestCustomLabel
sf project retrieve start --metadata CustomLabels:TestCustomLabel
sf project retrieve start --metadata CustomLabels:CustomLabels/TestCustomLabel
(VSCode only) create the label metadata manually in local directory, then right click retrieve source from org from dropdown

Expected result

Either of following should be able to retrieve the custom label correctly
C1. sf project retrieve start --metadata CustomLabel:TestCustomLabel
C2. sf project retrieve start --metadata CustomLabels:TestCustomLabel should be able to retrieve corresponding
C3. sf project retrieve start --metadata CustomLabels:CustomLabels/TestCustomLabel
C4. (VSCode only) create the label metadata manually in local directory, then right click retrieve source from org from dropdown

Actual result

C1. Cannot use this type, instead use CustomLabels
C2. Entity of type 'CustomLabels' named 'TestCustomLabel' cannot be found
C3. Entity of type 'CustomLabels' named 'CustomLabels/TestCustomLabel' cannot be found
C4. Could not infer a metadata type

System Information

Environment:
MacOS
@salesforce/cli/2.37.4 darwin-arm64 node-v20.12.0

Windows
@salesforce/cli/2.37.4 win32-x64 node-v20.11.1

Connected Sandbox:
Developer, cloned from Unlimited Edition Production Org

Software:
Windows:
cmd.exe
powershell embedded in VSCode

MacOS:
zsh

{
  "architecture": "darwin-arm64",
  "cliVersion": "@salesforce/cli/2.37.4",
  "nodeVersion": "node-v20.12.0",
  "osVersion": "Darwin 23.4.0",
  "rootPath": "/usr/local/lib/sf",
  "shell": "zsh",
  "pluginVersions": [
    "@oclif/plugin-autocomplete 3.0.13 (core)",
    "@oclif/plugin-commands 3.2.2 (core)",
    "@oclif/plugin-help 6.0.20 (core)",
    "@oclif/plugin-not-found 3.1.2 (core)",
    "@oclif/plugin-plugins 5.0.7 (core)",
    "@oclif/plugin-search 1.0.20 (core)",
    "@oclif/plugin-update 4.2.4 (core)",
    "@oclif/plugin-version 2.0.16 (core)",
    "@oclif/plugin-warn-if-update-available 3.0.15 (core)",
    "@oclif/plugin-which 3.1.7 (core)",
    "@salesforce/cli 2.37.4 (core)",
    "apex 3.1.4 (core)",
    "auth 3.5.5 (core)",
    "data 3.2.5 (core)",
    "deploy-retrieve 3.5.6 (core)",
    "info 3.1.3 (core)",
    "limits 3.2.1 (core)",
    "marketplace 1.1.1 (core)",
    "org 4.0.4 (core)",
    "packaging 2.3.0 (core)",
    "schema 3.2.1 (core)",
    "settings 2.1.2 (core)",
    "sobject 1.2.2 (core)",
    "source 3.2.3 (core)",
    "telemetry 3.1.18 (core)",
    "templates 56.1.1 (core)",
    "trust 3.5.4 (core)",
    "user 3.4.3 (core)",
    "sfdx-git-delta 5.39.1 (user)"
  ]
}

[github-actions]

Thank you for filing this issue. We appreciate your feedback and will review the issue as soon as possible. Remember, however, that GitHub isn't a mechanism for receiving support under any agreement or SLA. If you require immediate assistance, contact Salesforce Customer Support.

[amtrack]

I'm also facing this issue. I'd still like to retrieve individual CustomLabel components and this fails.

$ sf project retrieve start -m CustomLabel:Dummy
Preparing retrieve request... Error
Error (1): Cannot use this type, instead use CustomLabels

I followed the instructions:

• delete the metadata locally
• change sfdx-project.json
• retrieve (all labels) from an org

Retrieving all labels via sf project retrieve start -m CustomLabels works but I'm surprised about the file structure:

$ tree force-app/main/default/labels
force-app/main/default/labels
└── CustomLabels
    ├── CustomLabels.labels-meta.xml
    ├── One.label-meta.xml
    └── Two.label-meta.xml

2 directories, 3 files

Is this correct?

[RayHWLau]

Hi @amtrack,

The retrieve command works properly on retrieving all CustomLabels, however the deploy commands failed to identify the labels which are in the decomposed directory.

for your information, I have also tried to diff the changes with salesforce git delta (sgd) and come up with correct package.xml. But current version salesforce cli simply bypass the custom label metadata listed in package.xml

[git2gus]

This issue has been linked to a new work item: W-15643464

[shabu74]

Hi @RayHWLau,

I have found the reason for that. It happened for custom labels and sharing rules too. Both these components have two type of metadata entities. One for bulk retrieval eg: SharingRules, CustomLabels and other for single retrieval eg: SharingCriteriaRule, SharingOwnerRule, CustomLabel etc. Bulk retrieval using SharingRules is working fine. So for CustomLabels. But if we will try to retrieve a specific sharing criteria rule, sharing owner rule or custom label, retrieval command is successful, but we will get Nothing retrieved message.

[shabu74]

Any update @mshanemc ?

[mshanemc]

@shabu74 there's a lot going on, but I'm working through the trade-offs around this.

It greatly simplifies things if you always deploy/retrieve the parent. So much so that we intentionally disabled that in the beta. Very interested in this feedback.

FWIW, I've chatted with the mdapi team about limits (they count files, not "components" so retrieve/deploying all your CustomLabels vs. specifying some individual CustomLabels doesn't affect the limit.

So I guess the question becomes, "how bad would it be, and in what ways, if we just said, don't use the children directly".

[obviously, we'd want to handle the vscode org-browser right-click scenario better and say, "oh, you wanted to retrieve a CustomLabel....I'll retrieve CustomLabels for you"]

[the metadata deploy/retrieve ends up deploying/retrieving the file named CustomLabels anyway...it just makes a different file than what you have in source, including only that label]

I'm not saying what you're asking for can't be done, I'm wanting to understand more of why that's valuable to you

[amtrack]

@mshanemc Hmm, I'd hope that all operations (retrieve, deploy and delete as well) will work for the individual CustomLabel metadata type.
To me it would feel like a strange restriction not being able to work with an addressable metadata type like CustomLabel.

Speaking of restrictions and custom labels :-) here's a use case of retrieving an individual CustomLabel:

Assuming you have two package directories force-app and sfdx-source/lib.
I'd love to be able to retrieve a new CustomLabel to the sfdx-source/lib package directory instead of the default package directory.

$ sf project retrieve start -m CustomLabel:MyNewLabel --output-dir sfdx-source/lib
Error (1): The retrieve target directory [sfdx-source/lib] overlaps one of your package directories. Specify a different retrieve target directory and try again.

I feel like there are a lot of things to consider with custom labels and package directories with and even without decomposition.

[mshanemc]

@amtrack the "where do things end up" should really be controlled by your default:true packageDirectory.

we added output-dir to help wth, "retrieve it in source format but not into my project." It gets really messy when retrieves can duplicate code into new parts of the project (even if you really mean to in this situation).

Hopefully you can soon just retrieve it and then decide where it goes because of the new #2682 stuff

[amtrack]

@mshanemc Hmm, OK.