dfx identity
Use the dfx identity command with subcommands and flags to manage the identities used to execute commands and communicate with the IC or the local canister execution environment. Creating multiple user identities enables you to test user-based access controls.
The basic syntax for running dfx identity commands is:
dfx identity [subcommand] [flag]
Depending on the dfx identity subcommand you specify, additional arguments, options, and flags might apply or be required. To view usage information for a specific dfx identity subcommand, specify the subcommand and the --help flag. For example, to see usage information for dfx identity new, you can run the following command:
dfx identity new --help
For reference information and examples that illustrate using dfx identity commands, select an appropriate command.
| Command | Description |
|---|---|
deploy-wallet | Installs the wallet Wasm to the provided canister id. |
get-principal | Shows the textual representation of the principal associated with the current identity. |
get-wallet | Shows the canister identifier for the wallet associated with your current identity principal. |
help | Displays this usage message or the help of the given subcommand(s). |
export | Exports the PEM definition for an identity. |
import | Creates a new identity by importing a PEM file that contains the key information or security certificate for a principal. |
list | Lists existing identities. |
new | Creates a new identity. |
remove | Removes an existing identity. |
rename | Renames an existing identity. |
set-wallet | Sets the wallet canister identifier to use for your current identity principal. |
use | Specifies the identity to use. |
whoami | Displays the name of the current identity user context. |
Creating a default identity
The first time you run the dfx canister create command to register an identifier, your public/private key pair credentials are used to create a default user identity. The credentials for the default user are migrated from $HOME/.dfinity/identity/creds.pem to $HOME/.config/dfx/identity/default/identity.pem.
You can then use dfx identity new to create new user identities and store credentials for those identities in $HOME/.config/dfx/identity/<identity_name>/identity.pem files. For example, you can create an identity named ic_admin by running the following command:
dfx identity new ic_admin
This command adds a private key for the ic_admin user identity in the ~/.config/dfx/identity/ic_admin/identity.pem file.
dfx identity deploy-wallet
Use the dfx identity deploy-wallet command to turn a canister into a wallet canister by installing the wallet Wasm to it.
Note that you must be connected to the IC or the local canister execution environment to run this command. In addition, you must be a controller of the canister you want to deploy the wallet to.
Basic usage
dfx identity deploy-wallet [flag] <canister id>
Arguments
You must specify the following argument for the dfx identity deploy-wallet command.
| Argument | Description |
|---|---|
<canister id> | The ID of the canister where the wallet Wasm will be deployed. |
dfx identity get-principal
Use the dfx identity get-principal command to display the textual representation of a principal associated with the current user identity context.
If you haven’t created any user identities, you can use this command to display the principal for the default user. The textual representation of a principal can be useful for establishing and testing role-based authorization scenarios.
Basic usage
dfx identity get-principal [flag]
Example
If you want to display the textual representation of a principal associated with a specific user identity context, you can run commands similar to the following:
dfx identity use ic_admin
dfx identity get-principal
In this example, the first command sets the user context to use the ic_admin identity. The second command then returns the principal associated with the ic_admin identity.
dfx identity get-wallet
Use the dfx identity get-wallet command to display the canister identifier for the wallet associated with your current identity principal.
Note that you must be connected to the IC or the local canister execution environment to run this command. In addition, you must be in a project directory to run the command. For example, if your project name is hello_world, your current working directory must be the hello_world top-level project directory or one of its subdirectories to run the dfx identity get-wallet command.
Basic usage
dfx identity get-wallet [flag]
Example
If you want to display the canister identifier for the wallet canister associated with your identity, you can run the following command:
dfx identity get-wallet
To display the canister identifier for the wallet canister associated with your identity on a specific testnet, you might run a command similar to the following:
dfx identity get-wallet --network=https://192.168.74.4
dfx identity export
Use the dfx identity export command to export the PEM definition of an existing identity. You can import this definition elsewhere using dfx identity import.
Basic usage
dfx identity export identity-name
Examples
The following will export a PEM file for an existing identity. If you transferred this file to another computer, the
example below for dfx identity import would import it.
dfx identity export alice >generated-id.pem
dfx identity import
Use the dfx identity import command to create a user identity by importing the user’s key information or security certificate from a PEM file.
Password policy: If an identity is imported using --storage-mode password-protected, the following requirements apply to the password:
- The password needs to be longer than 8 characters.
Basic usage
dfx identity import [options] identity-name pem_file-name
Options
You can specify the following options for the dfx identity import command.
| Argument | Description |
|---|---|
--storage-mode | By default, PEM files are stored in the OS-provided keyring. If that is not available, they are encrypted with a password when writing them to disk. Plaintext PEM files are still available (e.g. for use in non-interactive situations like CI), but not recommended for use since they put the keys at risk. To force the use of one specific storage mode, use the --storage-mode flag with either --storage-mode password-protected or --storage-mode plaintext. |
--force | If the identity already exists, remove and re-import it. |
Examples
You can use the dfx identity import command to import a PEM file that contains the security certificate to use for an identity. For example, you can run the following command to import the generated-id.pem file to create the user identity alice:
dfx identity import alice generated-id.pem
The command adds the generated-id.pem file to the ~/.config/dfx/identity/alice directory.
dfx identity list
Use the dfx identity list command to display the list of user identities available. When you run this command, the list displays an asterisk (*) to indicate the currently active user context. You should note that identities are global. They are not confined to a specific project context. Therefore, you can use any identity listed by the dfx identity list command in any project.
Basic usage
dfx identity list [flag]
Examples
You can use the dfx identity list command to list all of the identities you have currently available and to determine which identity is being used as the currently-active user context for running dfx commands. For example, you can run the following command to list the identities available:
dfx identity list
This command displays the list of identities found similar to the following:
alice_auth
anonymous
bob_standard *
default
ic_admin
In this example, the bob_standard identity is the currently-active user context. After you run this command to determine the active user, you know that any additional dfx commands you run are executed using the principal associated with the bob_standard identity.
dfx identity new
Use the dfx identity new command to add new user identities. You should note that the identities you add are global. They are not confined to a specific project context. Therefore, you can use any identity you add using the dfx identity new command in any project.
Only the characters ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz.-_@0123456789 are valid in identity names.
Password policy: If an identity is created using --storage-mode password-protected, the following requirements apply to the password:
- The password needs to be longer than 8 characters.
Basic usage
dfx identity new [options] _identity-name_
Arguments
You must specify the following argument for the dfx identity new command.
| Argument | Description |
|---|---|
<identity_name> | Specifies the name of the identity to create. This argument is required. Valid characters are letters, numbers, and these symbols: .-_@ |
Options
You can specify the following options for the +dfx identity new+ command.
| Argument | Description |
|---|---|
--storage-mode | By default, PEM files are stored in the OS-provided keyring. If that is not available, they are encrypted with a password when writing them to disk. Plaintext PEM files are still available (e.g. for use in non-interactive situations like CI), but not recommended for use since they put the keys at risk. To force the use of one specific storage mode, use the --storage-mode flag with either --storage-mode password-protected or --storage-mode plaintext. |
--force | If the identity already exists, remove and re-import it. |
--hsm-key-id <hsm key id> | A sequence of pairs of hex digits. |
--hsm-pkcs11-lib-path <hsm pkcs11 lib path> | The file path to the opensc-pkcs11 library e.g. "/usr/local/lib/opensc-pkcs11.so" |
Examples
You can then use dfx identity new to create new user identities and store credentials for those identities in $HOME/.config/dfx/identity/<identity_name>/identity.pem files. For example, you can create an identity named ic_admin by running the following command:
dfx identity new ic_admin
This command adds a private key for the ic_admin user identity in the ~/.config/dfx/identity/ic_admin/identity.pem file.
After adding the private key for the new identity, the command displays confirmation that the identity has been created:
Creating identity: "ic_admin".
Created identity: "ic_admin".
dfx identity remove
Use the dfx identity remove command to remove an existing user identity. You should note that the identities you add are global. They are not confined to a specific project context. Therefore, any identity you remove using the dfx identity remove command will no longer be available in any project.
Basic usage
dfx identity remove [flag] _identity-name_
Flags
You can use the following optional flags with the dfx identity remove command.
| Flag | Description |
|---|---|
--drop-wallets | Required if the identity has wallets configured so that users do not accidentally lose access to wallets. |
Arguments
You must specify the following argument for the dfx identity remove command.
| Argument | Description |
|---|---|
<identity_name> | Specifies the name of the identity to remove. This argument is required. |
Examples
You can use the dfx identity remove command to remove any previously-created identity, including the default user identity. For example, if you have added named user identities and want to remove the default user identity, you can run the following command:
dfx identity remove default
The command displays confirmation that the identity has been removed:
Removing identity "default".
Removed identity "default".
Although you can delete the default identity if you have created other identities to replace it, you must always have at least one identity available. If you attempt to remove the last remaining user context, the dfx identity remove command displays an error similar to the following:
Identity error:
Cannot delete the default identity
If you have an identity with one or more wallets configured, it will only be deleted if you call it with --drop-wallets. This is made so that users don't accidentally lose access to their cycles wallets. If you try to delete an identity with at least one wallet configured, it will display the attached wallets like this:
This identity is connected to the following wallets:
identity 'mainnet' on network 'ic' has wallet rwlgt-iiaaa-aaaaa-aaaaa-cai
dfx identity rename
Use the dfx identity rename command to rename an existing user identity. You should note that the identities you add are global. They are not confined to a specific project context. Therefore, any identity you rename using the dfx identity rename command is available using the new name in any project.
Basic usage
dfx identity rename [flag] _from_identity-name_ _to_identity-name_
Arguments
You must specify the following arguments for the dfx identity rename command.
| Argument | Description |
|---|---|
<from_identity_name> | Specifies the current name of the identity you want to rename. This argument is required. |
<to_identity_name> | Specifies the new name of the identity you want to rename. This argument is required. |
Example
You can rename the default user or any identity you have previously created using the dfx identity rename command. For example, if you want to rename a test_admin identity that you previously created, you would specify the current identity name you want to change from and the new name you want to change to by running a command similar to the following:
dfx identity rename test_admin devops
dfx identity set-wallet
Use the dfx identity set-wallet command to specify the wallet canister identifier to use for your identity.
Basic usage
dfx identity set-wallet [flag] [--canister-name canister-name]
Flags
You can use the following optional flags with the dfx identity set-wallet command.
| Flag | Description |
|---|---|
--force | Skips verification that the canister you specify is a valid wallet canister. This option is only useful if you are connecting to the IC running locally. |
Example
If you use more than one principal for your identity, you might have access to more than one wallet canister identifier. You can use the dfx identity set-wallet command to specify the wallet canister identifier to use for a given identity.
For example, you might store the wallet canister identifier in an environment variable, then invoke the dfx identity set-wallet command to use that wallet canister for additional operations by running the following:
export WALLET_CANISTER_ID=$(dfx identity get-wallet)
dfx identity set-wallet --canister-name ${WALLET_CANISTER_ID} --network=https://192.168.74.4
dfx identity use
Use the dfx identity use command to specify the user identity you want to active. You should note that the identities you have available to use are global. They are not confined to a specific project context. Therefore, you can use any identity you have previously created in any project.
The identity used by a command is:
- the identity specified in the command with
--identity <NAME>, if defined - else the identity specified by the environment variable
export DFX_IDENTITY=<NAME>, if defined - the identity specified by
dfx identity use <NAME>.
Basic usage
dfx identity use [flag] _identity-name_
Arguments
You must specify the following argument for the dfx identity use command.
| Argument | Description |
|---|---|
<identity_name> | Specifies the name of the identity you want to make active for subsequent commands. This argument is required. |
Examples
If you want to run multiple commands with the same user identity context, you can run a command similar to the following:
dfx identity use ops
After running this command, subsequent commands use the credentials and access controls associated with the ops user.
dfx identity whoami
Use the dfx identity whoami command to display the name of the currently-active user identity context.
Basic usage
dfx identity whoami [flag]
Example
If you want to display the name of the currently-active user identity, you can run the following command:
dfx identity whoami
The command displays the name of the user identity. For example, you had previously run the command dfx identity use bob_standard, the command would display:
bob_standard