Salesforce Docs Portal

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:

sf dev generate flag

Global Flags

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.

Built-In Flags

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.

Flag Properties

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.

Flag Types

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.

boolean

import { Flags, SfCommand } from "@salesforce/sf-plugins-core";

class MyCommand extends SfCommand {
  public static flags = {
    "my-boolean-flag": Flags.boolean({
      summary: "a flag that expects a true/false value",
    }),
  };
}

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

directory

import { Flags, SfCommand } from "@salesforce/sf-plugins-core";

class MyCommand extends SfCommand {
  public static flags = {
    "my-dir-flag": Flags.directory({
      summary: "a flag that expects a string that points to a directory",
      exists: true, // optionally require the directory to exist
    }),
  };
}

Sample user input:

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

duration

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

import { Flags, SfCommand } from "@salesforce/sf-plugins-core";

class MyCommand extends SfCommand {
  public static flags = {
    "my-duration-flag": Flags.duration({
      summary: "a flag that expects a string that can be converted to a Duration",
      unit: "minutes",
    }),
  };
}

Sample user input:

--my-duration-flag 33

enum

import { Flags, SfCommand } from "@salesforce/sf-plugins-core";

enum MyEnum {
  "A" = "A",
  "B" = "B",
  "C" = "C",
}

class MyCommand extends SfCommand {
  public static flags = {
    "my-enum-flag": Flags.enum<MyEnum>({
      summary: "a flag that expects a specific value defined by an enum",
      options: Object.values(MyEnum),
    }),
  };
}

Sample user input:

--my-enum-flag B

file

import { Flags, SfCommand } from "@salesforce/sf-plugins-core";

class MyCommand extends SfCommand {
  public static flags = {
    "my-file-flag": Flags.file({
      summary: "a flag that expects a string that points to a file",
      exists: true, // optionally require the file to exist
    }),
  };
}

Sample user input:

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

integer

import { Flags, SfCommand } from "@salesforce/sf-plugins-core";

class MyCommand extends SfCommand {
  public static flags = {
    "my-integer-flag": Flags.integer({
      summary: "a flag that expects a number",
      min: 0, // optionally set the minimum acceptable number
      max: 100, // optionally set the maximum acceptable number
    }),
  };
}

Sample user input:

--my-integer-flag 42

string

import { Flags, SfCommand } from "@salesforce/sf-plugins-core";

class MyCommand extends SfCommand {
  public static flags = {
    "my-string-flag": Flags.string({
      summary: "a flag that expects a string value",
    }),
  };
}

Sample user input:

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

orgApiVersion

import { Flags, SfCommand } from "@salesforce/sf-plugins-core";

class MyCommand extends SfCommand {
  public static flags = {
    "my-apiversion-flag": Flags.orgApiVersion({
      summary: "a flag that expects a valid Salesforce API version",
    }),
  };
}

Sample user input:

--my-apiversion-flag 56.0

requiredHub

import { Flags, SfCommand } from "@salesforce/sf-plugins-core";

class MyCommand extends SfCommand {
  public static flags = {
    "my-devhub-flag": Flags.requiredOrg({
      summary: "a flag that expects a username of a devhub org that you have authorized",
    }),
  };
}

Sample user input:

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

requiredOrg

import { Flags, SfCommand } from "@salesforce/sf-plugins-core";

class MyCommand extends SfCommand {
  public static flags = {
    "my-username-flag": Flags.requiredOrg({
      summary: "a flag that expects a username of an org that you have authorized",
    }),
  };
}

Sample user input:

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

optionalOrg

import { Flags, SfCommand } from "@salesforce/sf-plugins-core";

class MyCommand extends SfCommand {
  public static flags = {
    "my-optional-username-flag": Flags.requiredOrg({
      summary: "a flag that expects a username of an org that you may or may not have authorized",
    }),
  };
}

Sample user input:

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

salesforceId

import { Flags, SfCommand } from "@salesforce/sf-plugins-core";

class MyCommand extends SfCommand {
  public static flags = {
    "my-sfid-flag": Flags.salesforceId({
      summary: "a flag that expects a Salesforce ID",
      length: 18, // optionally set the length of the id
      startsWith: "00D", // optionally set the string that the id must start with
    }),
  };
}

Sample user input:

--my-sfid-flag 04t001122334455ABC

url

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

import { Flags, SfCommand } from '@salesforce/sf-plugins-core';

class MyCommand extends SfCommand {
  public static flags = {
    'my-url-flag': Flags.url({
      summary: 'a flag that expects a url that can be parsed by node's URL class',
    }),
  }
}

Sample user input:

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