Skip to main content

dfx identity

Reference

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.

CommandDescription
deploy-walletInstalls the wallet Wasm to the provided canister id.
get-principalShows the textual representation of the principal associated with the current identity.
get-walletShows the canister identifier for the wallet associated with your current identity principal.
helpDisplays this usage message or the help of the given subcommand(s).
exportExports the PEM definition for an identity.
importCreates a new identity by importing a PEM file that contains the key information or security certificate for a principal.
listLists existing identities.
newCreates a new identity.
removeRemoves an existing identity.
renameRenames an existing identity.
set-walletSets the wallet canister identifier to use for your current identity principal.
useSpecifies the identity to use.
whoamiDisplays 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.

ArgumentDescription
<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.

ArgumentDescription
--storage-modeBy 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.
--forceIf 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.

ArgumentDescription
<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.

ArgumentDescription
--storage-modeBy 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.
--forceIf 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.

FlagDescription
--drop-walletsRequired 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.

ArgumentDescription
<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.

ArgumentDescription
<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.

FlagDescription
--forceSkips 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.

ArgumentDescription
<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