sf project deploy start has inconsistent documentation

[chivalry]

Summary

sf project deploy start --help includes the following in the documentation:

-o, --target-org=<value>   (required) Login username or alias for the target org.

This is incorrect, as the flag is not required, although if default-org isn't configured, it is required. Numerous examples in the documentation omit the --target-org flag.

I'd suggest changing the wording to:

-o, --target-org=<value>   (required if `target-org` is unset) Login username or alias for the target org.

Steps To Reproduce

1. In a project where target-org is set to a valid org, execute sf project deploy start and confirm no error occurs.
2. Execute sf config unset target-org, attempt to execute sf project deploy start and confirm that an error occurs.

Expected result

The documentation shouldn't state that --target-org is required when it isn't always required.

Actual result

The documentation specifies that --target-org is required when that isn't always the case.

System Information

• macOS 13.5.2, VS Code 1.83.0 terminal, zsh 5.9

{
  "architecture": "darwin-arm64",
  "cliVersion": "@salesforce/cli/2.14.6",
  "nodeVersion": "node-v18.15.0",
  "osVersion": "Darwin 22.6.0",
  "rootPath": "/Users/chuck/.local/share/sf/client/2.14.6-1f2724e",
  "shell": "zsh",
  "pluginVersions": [
    "@oclif/plugin-autocomplete 2.3.10 (core)",
    "@oclif/plugin-commands 3.0.3 (core)",
    "@oclif/plugin-help 6.0.3 (core)",
    "@oclif/plugin-not-found 3.0.2 (core)",
    "@oclif/plugin-plugins 3.9.2 (core)",
    "@oclif/plugin-search 1.0.3 (core)",
    "@oclif/plugin-update 4.1.2 (core)",
    "@oclif/plugin-version 2.0.3 (core)",
    "@oclif/plugin-warn-if-update-available 3.0.1 (core)",
    "@oclif/plugin-which 3.0.5 (core)",
    "@salesforce/cli 2.14.6 (core)",
    "apex 2.3.20 (core)",
    "auth 2.8.22 (core)",
    "data 2.5.19 (core)",
    "deploy-retrieve 1.19.2 (core)",
    "info 2.6.49 (core)",
    "limits 2.3.39 (core)",
    "login 1.2.37 (core)",
    "marketplace 0.3.0 (core)",
    "org 2.11.4 (core)",
    "packaging 1.26.4 (user)",
    "schema 2.3.30 (core)",
    "settings 1.4.35 (core)",
    "sobject 0.2.13 (core)",
    "source 2.10.43 (core)",
    "telemetry 2.3.6 (core)",
    "templates 55.5.14 (core)",
    "trust 2.6.20 (core)",
    "user 2.3.37 (core)"
  ]
}

Additional information

I did a cursory look for where the documentation is sourced from but wasn't able to easily find it. If given directions to the file where the documentation exists I'd be happy to edit the file and submit a PR.

[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.

[chivalry]

BTW, this seems to be a wider documentation issue. At least one other command sf org open also says that --target-org is required when, strictly speaking, it's not.

Open your default scratch org, or another specified org, in a browser.

USAGE
  $ sf org open -o <value> [--json] [--api-version <value>] [-b chrome|edge|firefox | -r] [-p <value> | -f <value>]

FLAGS
  -b, --browser=<option>     Browser where the org opens.
                             <options: chrome|edge|firefox>
  -f, --source-file=<value>  Path to an ApexPage or FlexiPage to open in Lightning App Builder.
  -o, --target-org=<value>   (required) Username or alias of the target org.
  -p, --path=<value>         Navigation URL path to open a specific page.
  -r, --url-only             Display navigation URL, but don’t launch browser.
  --api-version=<value>      Override the api version used for api requests made by this command

...

EXAMPLES
  Open your default org in your default browser:

    $ sf org open

[cristiand391]

Hey @chivalry, sorry for the late reply.

This is due to how oclif (CLI framework we use) handles default flag values, see this: oclif/core#854

let's keep this open, maybe we can get a way to improve the help text while still keeping this pattern in our flags

[chivalry]

Thanks, @cristiand391. I just found it momentarily confusing while I was moving our sfdx calls over to sf in our scripts.

[git2gus]

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

[mshanemc]

I think there's a potential oclif-level fix for this, but we can fix in sf everywhere the flag is used pretty easily by modifying the text description to caveat required