-
Notifications
You must be signed in to change notification settings - Fork 21
Design Guidelines Flags
Flags (sometimes called options), provide specific values for a single execution of the command.
We highly discourage flags that branch the behavior of the command based on a value. For simplicity and ease of use, every command should perform one distinct task. The command's flags can modify how that task executes, but the flags shouldn't change the command's fundamental nature.
When creating a flag that accepts multiple values, we recommend you use the multiple:true
flag property. We also then encourage your users to specify the flag multiple times rather than once with a comma-separated list of the values. For example, --metadata
accepts multiple values and users run the command this way:
sf project deploy start --metadata ApexClass:MyClass --metadata ApexClass:MyOtherClass
And not this way:
sf project deploy start --metadata ApexClass:MyClass,ApexClass:MyOtherClass
- Flags can either accept a value or switch a specific behavior on or off.
- Flags are prefixed with double dashes, such as
--filename
, and optional single-letter names prefixed with one dash, such as-f
. - We recommend that all long flag names are lowercase and use kebab-case (as opposed to camelCase or PascalCase) so that your commands are consistent with the rest of the Salesforce CLI. For example, use
--no-prompt
and not--noPrompt
. - You can specify flags in any order as long as they come after the command.
- JSON output of the command shouldn't change based on the flags.
Consider these ideas when naming your flag:
- For flags that accept a value, choose a long name that briefly describes the value, such as
--job-id
. - For flags of type Boolean, which alter the behavior of a command but don’t accept a value, choose a long name that briefly describes the flag’s effect, such as
--use-most-recent
.
We recommend using short names (single character) for any required flags to reduce the amount of typing the user has to do. Generally speaking, the short name should be the first letter of the flag name or the most dominant consonant in the name, such as -i
for --id
and -c
for --ignore-conflicts
.
Use PascalCase for the permissible values of option flags. For example, these are the permissible values for the —test-level
flag of sf project deploy start
: NoTestRun
, RunSpecifiedTests
, RunLocalTests
, RunAllTestsInOrg
.
The core Salesforce CLI commands use these flag naming patterns:
- ID values
- Short name:
-i
- Long name: The type of ID, such as
--testrun-id
- Short name:
- Files
- Short name:
-f
- Long name: The type of file, such as
--csv-file
or--definition-file
- Short name:
- Directory paths
- Short name:
-d
- Long name: The type of directory, such as
--output-dir
or--source-dir
- Short name:
- Names
- Short name:
-n
- Long name: The type of name, such as
--field-name
- Short name:
Finally, these are reserved flag names:
-
--help
and-h
-
--version
and-v
--json
The core Salesforce CLI commands avoid the usage of positional arguments and varargs, and instead opt for flags. We believe flags are more specific and don't depend on the user providing them in the correct order.
© Copyright 2024 Salesforce.com, inc. All rights reserved. Various trademarks held by their respective owners.
- Quick Intro to Developing sf Plugins
- Get Started: Create Your First Plugin
- Design Guidelines
- Code Your Plugin
- Debug Your Plugin
- Write Useful Messages
- Test Your Plugin
- Maintain Your Plugin
- Integrate Your Plugin With the Doctor Command
- Migrate Plugins Built for sfdx
- Conceptual Overview of Salesforce CLI