---
schema_version: "1"
id: 9f6640e14043e6f043330b935c0fbdc8090640a9bb24fccd6125a7ed9f8068f3
title: Command Flags
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/salesforcedx/sfcliplugin/guides/code/command-flags.md
canonical_url: https://developer.salesforce.com/docs/platform/salesforce-cli-plugin/guide/command-flags.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 2aee91eb2c1befd4c2a24fdfae7b64818ea77f989ed6b1c0e58d7629acdc49cd
products:
  - Salesforce CLI Plugin Developer Guide
  - salesforcedx
---
# 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:

```bash
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](https://oclif.io/docs/flags) for the full list and [@salesforce/sf-plugins-core](https://salesforcecli.github.io/sf-plugins-core/#flags) 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](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/main/src/commands/project/deploy/start.ts#L40) for the flags defined for the `sf project deploy start` core Salesforce CLI command.

### `boolean`

```typescript
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`

```typescript
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](https://forcedotcom.github.io/kit/classes/duration.html).

```typescript
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`

```typescript
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`

```typescript
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`

```typescript
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`

```typescript
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`

```typescript
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`

```typescript
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`

```typescript
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`

```typescript
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`

```typescript
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](https://nodejs.org/api/url.html)

```typescript
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`