Skip to content

docs: fix identity metadata storage paths #284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
raymondk merged 5 commits into from
Jan 20, 2026
Merged

docs: fix identity metadata storage paths #284

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ae26113
docs: fix macOS metadata location to be copiable
marc0olo Jan 20, 2026
2edc728
docs: fix identity storage paths in dfx migration guide
marc0olo Jan 20, 2026
a576565
docs: fix note about keyring service
marc0olo Jan 20, 2026
a4eea6e
docs: fix shell quoting in identity migration script
marc0olo Jan 20, 2026
f9dadc8
Apply suggestion from @adamspofford-dfinity
raymondk Jan 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions docs/migration/from-dfx.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -290,12 +290,14 @@ Both dfx and icp-cli support three storage modes:

### Identity Storage Locations

| Tool | Metadata Location | Private Key Storage |
|------|-------------------|---------------------|
| **dfx** | `~/.config/dfx/identity/<name>/` | System keyring (default), or encrypted/plaintext in `identity.pem` |
| **icp-cli** | **macOS:** `~/Library/Application Support/org.dfinity.icp-cli/identity/`<br>**Linux:** `~/.local/share/icp-cli/identity/`<br>**Windows:** `%APPDATA%\icp-cli\data\identity\` | System keyring (default), or encrypted/plaintext file |
| Tool | Identity Directory | Structure |
|------|-------------------|-----------|
| **dfx** | `~/.config/dfx/identity/` | Per-identity subdirectories:<br>`<name>/identity.json` (metadata)<br>`<name>/identity.pem` (key, if not in keyring) |
| **icp-cli** | **macOS:** `~/Library/Application Support/org.dfinity.icp-cli/identity/`<br>**Linux:** `~/.local/share/icp-cli/identity/`<br>**Windows:** `%APPDATA%\icp-cli\data\identity\` | Centralized files:<br>`identity_list.json` (all identities)<br>`identity_defaults.json` (default selection)<br>`keys/<name>.pem` (keys, if not in keyring) |

**Note:** Both tools use the same keyring service (`internet_computer_identities`), so keyring-stored identities coexist without conflicts.
**Private key storage (both tools):** System keyring (default), or encrypted/plaintext PEM files

**Note:** dfx and icp-cli use different service names in the system keyring (`internet_computer_identities` vs `icp-cli`), so identities must be explicitly migrated using the import/export process described below.

### Checking Your dfx Identity Storage Mode

Expand Down Expand Up @@ -378,25 +380,25 @@ for id in $(dfx identity list | grep -v "^anonymous"); do
echo "Migrating $id..."

# Export from dfx (handles all storage types)
dfx identity export $id > /tmp/${id}.pem
dfx identity export "$id" > "/tmp/${id}.pem"

# Import to icp-cli (uses keyring by default)
icp identity import $id --from-pem /tmp/${id}.pem
icp identity import "$id" --from-pem "/tmp/${id}.pem"

# Clean up
rm /tmp/${id}.pem
rm "/tmp/${id}.pem"

# Verify principals match
echo " dfx principal: $(dfx identity get-principal --identity $id)"
echo " icp-cli principal: $(icp identity principal --identity $id)"
echo " dfx principal: $(dfx identity get-principal --identity "$id")"
echo " icp-cli principal: $(icp identity principal --identity "$id")"
echo ""
done

# List all imported identities
icp identity list
```

**Note:** This script will prompt for passwords if any dfx identities are password-protected or stored in keyring.
**Note:** This script copies identities to icp-cli without removing them from dfx. Your original dfx identities remain intact and both tools can be used side-by-side. The script will prompt for passwords if any dfx identities are password-protected or stored in keyring.

### Setting the Default Identity

Expand Down