Command Flags

Add flags to your commands so users can provide input to modify the behavior of the command.

To get started with your new flag, run this interactive command in your plugin directory:

All commands automatically have the --help and -h flags for displaying long and short command help, respectively.

If your command extends the base SfCommand class, it also has these flags by default:

  • --json : Format output as JSON.
  • --flags-dir : Import flag values from a file.

If you pick one of these flag types when you run dev generate flag, you're not required to write any code at all to make it work!

  • optionalHub (corresponds to the standard --target-dev-hub flag)
  • requiredlHub (corresponds to the standard --target-dev-hub flag)
  • optionalOrg (corresponds to the standard --target-org flag)
  • requiredOrg (corresponds to the standard --target-org flag)
  • orgApiVersion (corresponds to the standard --api-version flag)

Instead, you can simply use the existing Salesforce CLI code to make the flag work the same way as it does in other CLI commands and even use the standard definition (flag long and short name, description, default value). The dev generate flag command prompts you for all the information.

Here are the most common properties for defining a new flag. See the oclif docs for the full list and @salesforce/sf-plugins-core for specialty flags.

  • summary - Brief overview of the flag's purpose. Displayed with the --help | -h flags.
  • description - More in-depth explanation of the flag. Displayed only with the --help flag.
  • char - Short character that the user can use instead of the full flag name, such as -p instead of --package-name.
  • multiple - Set to true if the user can provide the flag multiple times in the same command execution, for example sf do awesome things -i 1 -i 2 -i 3
  • parse - A function to modify or validate input. The value returned from this function is the new flag value.
  • dependsOn - Flags that must be passed to use this flag.
  • exclusive - This flag can't be specified alongside these other flags.
  • exactlyOne - Exactly one of these flags must be provided.
  • required - Set to true if the user is required to provide this flag on every command execution.
  • default - Provide the default value for a flag if it's not provided by the user.
  • hidden - Set to true if you want to hide the flag from the user.

Select a flag type based on the behavior you want that flag to cause. Using a specific flag type helps you validate the format of the flag value that your user supplies.

This section lists the types you can select for your new flag. Each section includes a code snippet that shows an example of declaring the flag in your command Typescript file. See the summary for a description of the type.

As an example, see the DeployMetadata class for the flags defined for the sf project deploy start core Salesforce CLI command.

The flag doesn't accept an actual value; simply specifying it at the command line sets it to true. Sample user input:

--my-boolean-flag

Sample user input:

--my-dir-flag /Users/romeo/sfdx-projects

This flag takes the input value and converts it to a Duration.

Sample user input:

--my-duration-flag 33

Sample user input:

--my-enum-flag B

Sample user input:

--my-file-flag /Users/romeo/sfdx-projects/list.json

Sample user input:

--my-integer-flag 42

Sample user input:

--my-string-flag "awesome string value"

Sample user input:

--my-apiversion-flag 56.0

Sample user input:

--my-devhub-flag devhub@example.com

Sample user input:

--my-username-flag test-wvkpnfm5z113@example.com

Sample user input:

--my-optional-username-flag test-wvkpnfm5z113@example.com

Sample user input:

--my-sfid-flag 04t001122334455ABC

This flag takes the input value and converts it to a URL

Sample user input:

--my-url-flag https://developer.salesforce.com/docs