User Definition File for Customizing a Scratch Org User

To customize a new scratch org user, rather than use the default and generated values, create a definition file.

The user definition file uses JSON format and can include any Salesforce User sObject field and these Salesforce DX-specific options.

Salesforce DX Option	Description	Default If Not Specified
`permsets`	An array of permission sets assigned to the user. Separate multiple values with commas, and enclose in square brackets. You must have previously deployed the permission sets to the scratch org with `project deploy start`.	None
`generatePassword`	Boolean. Specifies whether to generate a random password for the user. If set to `true`, `org create user` displays the generated password after it completes. You can also view the password using `org display user`.	False
`profileName`	Name of a profile to associate with the user. Similar to the ProfileId field of the User sObject except that you specify the name of the profile and not its ID. Convenient when you know only the name of the profile.	Standard User

The user definition file options are case-insensitive. However, we recommend that you use lower camel case for the Salesforce DX-specific options and upper camel case for the User sObject fields. This format is consistent with other Salesforce DX definition files.

This user definition file includes some User sObject fields and three Salesforce DX options (profileName, permsets, and generatePassword).

1{
2    "Username": "tester1@sfdx.org",
3    "LastName": "Hobbs",
4    "Email": "tester1@sfdx.org",
5    "Alias": "tester1",
6    "TimeZoneSidKey": "America/Denver",
7    "LocaleSidKey": "en_US",
8    "EmailEncodingKey": "UTF-8",
9    "LanguageLocaleKey": "en_US",
10    "profileName": "Standard Platform User",
11    "permsets": ["Dreamhouse", "Cloudhouse"],
12    "generatePassword": true
13}

In the example, the username tester1@sfdx.org must be unique across the entire Salesforce ecosystem; otherwise, the org create user command fails. We recommend that you use the --set-unique-username flag, which overrides the value in the configuration file and ensures a unique username. The alias in the Alias option is different from the alias you specify with the --set-alias flag of org create user. Use the Alias option only with the Salesforce UI. The --set-alias flag is local to the computer from which you run the CLI, and you can use it with other CLI commands.

Indicate the path to the user definition file with the --definition-file flag. You can name this file whatever you like and store it anywhere the CLI can access.

1sf org create user --set-alias qa-user --definition-file config/user-def.json --target-org my-scratch

You can override an option in the user definition file by specifying it as a name-value pair at the command line. This technique allows multiple users or continuous integration jobs to share a base definition file and then customize options when they run the command. This example overrides the username, list of permission sets, and whether to generate a password.

1sf org create user --set-alias qa-user --definition-file config/user-def.json permsets="Dreamy,Cloudy" Username=tester345@sfdx.org generatePassword=false --target-org my-scratch

You can also add options at the command line that aren’t in the user definition file. This example adds the City option.

1sf org create user --set-alias qa-user --definition-file config/user-def.json City=Oakland --target-org my-scratch

Salesforce DX Developer Guide

User Definition File for Customizing a Scratch Org User

See Also