Migrate from dfx to icp CLI

[deucalioncodes]

Migration: dfx → icp CLI

Context

dfx is now considered legacy. The new officially supported CLI is icp (@icp-sdk/icp-cli).

Benefits of icp over dfx

Feature	icp	dfx
Networks	Project-local — each project has isolated local network	Shared global network
Canister IDs	Stored in .icp/data/ (committed to version control)	Scattered in .dfx/ (gitignored)
Env vars	ic_env cookie — no .env files needed	Required .env files with CANISTER_ID_*
Identity	icp identity default (one default)	dfx identity use (switching confusion)
Build	Official version-pinned recipes (e.g., @dfinity/rust@v3.2.0)	Manual build steps, easy to misconfigure
Deploy	icp deploy -e ic (cleaner)	dfx deploy --network ic (legacy)
Local dev	icp network start -d in project dir	dfx start (global shared state)

How to Leverage icp Improvements

1. Project-Local Networks

• Run icp network start -d in each project directory
• No more collisions between projects using the same canister IDs
• Clean isolation for parallel development

2. Version-Pinned Recipes

Instead of manual build steps in dfx.json:

# icp.yaml
build:
  recipe: @dfinity/rust@v3.2.0

This ensures reproducible builds across all environments.

3. Git-Friendly Canister IDs

Move from .dfx/ (gitignored) to .icp/data/ (should be committed):

# After first deploy, commit the generated IDs
.gitignore
- .dfx/
+ .icp/data/

Team members now share the same canister IDs automatically.

4. No More .env Files

Remove all CANISTER_ID_* from .env. The ic_env cookie handles this:

# Old (dfx)
source .env && dfx deploy

# New (icp)
icp deploy -e ic  # cookie handles canister IDs

5. Simpler Identity Management

# Set once, use everywhere
icp identity default my_identity

# No more "which identity am I using?" confusion

Migration Steps

1. Install icp CLI: npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm
2. Convert dfx.json → icp.yaml (see docs)
3. Update deploy scripts to use icp commands
4. Move canister IDs from .dfx/ to .icp/data/ and commit
5. Update CI/CD workflows
6. Update documentation

Resources

• icp-cli docs: https://cli.icp.build
• Migration guide: https://skills.internetcomputer.org (fetch icp-cli skill)

Acceptance Criteria

• All dfx commands replaced with icp equivalents
• icp.yaml configured correctly
• Local development works with icp network start -d
• Staging/mainnet deploy works with icp deploy -e <env>
• CI/CD updated
• Team onboarded to new workflow