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, design the flag so that users specify it 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

Guidelines

• 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
• File paths
  • Short name: -f
  • Long name: The type of file, such as --csv-file or --definition-file
• Directory paths
  • Short name: -d
  • Long name: The type of directory, such as --output-dir or --source-dir
• Names
  • Short name: -n
  • Long name: The type of name, such as --field-name

Finally, these are reserved flag names:

• --help and -h
• --version and -v
• --json

Arguments

The core Salesforce CLI commands avoid the usage of positional arguments / varargs and instead opt for flags. We beleive flags are more specific and don't depend on the user providing them in the correct order.