User Definition File for Customizing a Scratch Org User

To customize a new 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 pushed the permission sets to the scratch org with `force:source:push`.	None
`generatePassword`	Boolean. Specifies whether to generate a random password for the user. If set to `true`, `force:user:create` displays the generated password after it completes. You can also view the password using `force:user:describe`.	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 force:user:create command fails. The alias in the Alias option is different from the alias you specify with the --setalias parameter of force:user:create. You use the Alias option alias only with the Salesforce UI. The --setalias alias is local to the computer from which you run the CLI, and you can use it with other CLI commands.

You indicate the path to the user definition file with the --definitionfile parameter of the force:user:create CLI command. You can name this file whatever you like and store it anywhere the CLI can access.

1sfdx force:user:create --setalias qa-user --definitionfile config/user-def.json

You can override an option in the user definition file by specifying it as a name-value pair at the command line when you run force:user:create. This example overrides the username, list of permission sets, and whether to generate a password.

1sfdx force:user:create --setalias qa-user --definitionfile config/user-def.json permsets="Dreamy,Cloudy" Username=tester345@sfdx.org generatePassword=false

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

1sfdx force:user:create --setalias qa-user --definitionfile config/user-def.json City=Oakland

Salesforce DX Developer Guide

User Definition File for Customizing a Scratch Org User

See Also: