Allow command execution outside project directory without sfdx-project.json

[Amit-Tripathi]

Let me run commands that are environment-agnostic outside of a project directory. I should be able to list packages or package versions anywhere in my terminal. The .sf auth files are in my root dir and it shouldn’t need to be in a SF project to run it.

If I try to run commands such as sf package version list or sf package list, they will error out unless I have a file named sfdx-project.json. There doesn't need to be anything in the file so I created a blank sfdx-project.json in my home directory as a workaround.
Some commands do run without it like sf org list but not all commands.

[VivekMChawla]

@Amit-Tripathi - I've felt similar frustration and would like to improve this.

Currently under consideration via W-16189175

[cristiand391]

hey, we've updated 3 packaging commands to allow them to run outside a project:
salesforcecli/plugin-packaging#733

the rest mentioned there can also be updated for the same but will require some refactoring in the libs so we'll cover those in a separate WI: W-16286213

please let me know if there's a specific command that you don't see listed there.

[Cerelius]

Hello, thanks for addressing this suggestion!

Amit reached out to me for input on this through our external Slack connection channel. I'm including my thoughts from our thread.

This is my view on priority order for the commands that have yet to be migrated based on my experience.

1. package version promote
2. package version report
3. package version displayancestry
4. package version delete
5. package update
6. package delete

Also I didn't know that the --package flag would reference the aliases in the sfdx-project.json. I would encourage an update to the way it's described here to help make that connection for consumers.

-p | --package PACKAGE
Required
ID (starts with 04t) or alias of the package version to promote.
Type: option

I appreciate the updates and I'll enjoy my newfound freedom for running commands. Soon I'll be able to remove my fake sfdx-project.json file. It's encouraging to hear that you had similar frustrations about the commands.

[mshanemc]

how would you update this line to make the alias part clearer?

ID (starts with 04t) or alias of the package version to promote

[cristiand391]

The last part of this was delivered in sf v2.56.7, see release notes:
https://github.com/forcedotcom/cli/tree/main/releasenotes/#2567-august-28-2024

Please let us know if there are other commands you think shouldn't require a project (some do on purpose because they need to read/write to sfdx-project.json)

[kkoellner]

With the ant tool being deprecated, it sure would be nice to work with simple directories of metadata files without having to deal with the SFDX project structure. I'd like to scripts to do simple retreives and deploys with the overhead of being in a project. The command below throws a "This directory does not contain a valid Salesforce DX project." error.

sf project retrieve start --manifest ./package.xml --target-org orgName.

[alan-morey]

@kkoellner This is already possible, with the --target-metadata-dir flag

sf project retrieve start --manifest package.xml --target-metadata-dir . --target-org myorg

This will retrieve the metadata components to a zip file called unpackaged.zip within the current directory, the zip file contains a directory unpackaged which contains the components.

You might also be interested in using other flags such as --single-package, --zip-file-name and --unzip as well.

sf project retrieve start --single-package --manifest package.xml --target-metadata-dir . --zip-file-name mymetadata.zip --unzip --target-org myorg

This retrieves components, from the target org as per manifest, as a single package which means no unpackaged directory in the zip file, the zip file is named mymetadata.zip instead of unpackaged.zip, and that zip file is unzipped to produce a directory mymetadata that contains the components specified as well as the package.xml used to retrieve.

Refer to help for more details:

sf project retrieve start --help