chore: replace dfx with icp-cli across the repository (dfinity#3801)

## Summary

DFX has been superseded by ICP-CLI
([`dfinity/icp-cli`](https://github.com/dfinity/icp-cli), binary `icp`,
config `icp.yaml`, v0.2.0 as of March 2026). This PR migrates the entire
repository off DFX so that it builds, tests, deploys, and runs locally
via `icp` only.

Migration guide:
https://cli.internetcomputer.org/0.2/migration/from-dfx.md

## Changes

**Configuration**
- `dfx.json` → `icp.yaml` (YAML manifest format required by icp-cli)
- `demos/using-dev-build/dfx.json` → `demos/using-dev-build/icp.yaml`
- Version tracking: `.icp-cli-version` file (replaces `"dfx"` field in
`dfx.json`)
- `dfx.example.json` files → `icp.yaml.example`
- `.dfx/` cache directory → `.icp/` in all ignore files

**CI Workflows**
- Replace `dfinity/setup-dfx` action with `npm install -g
@icp-sdk/icp-cli@$(cat .icp-cli-version)`
- `canister-tests.yml`: all `dfx` commands → `icp` equivalents
- `deploy-rc.yml`: all `dfx` commands → `icp` equivalents
- Rename `update-dfx.yml` → `update-icp-cli.yml`, re-point at
`dfinity/icp-cli` releases
- `DFX_DEPLOY_KEY` local env var → `ICP_DEPLOY_KEY` (still reads
`secrets.DFX_DEPLOY_KEY`)

**Scripts**
- `scripts/build`: metadata key `dfx` → `icp-cli`
- `scripts/deploy-archive`: `dfx canister` → `icp canister`
- `scripts/deploy-common.bash`: `dfx canister` → `icp canister`,
`--network` → `-e`
- `scripts/deploy-local-to-beta`, `scripts/deploy-pr-to-beta`: updated
references
- `scripts/make-upgrade-proposal`: all `dfx` commands → `icp`
equivalents
- `demos/vc_issuer/provision`: `dfx` → `icp`, `--dfx-network` →
`--icp-network`

**Source Code**
- `src/vite-plugins/src/utils.ts`: `dfx info/canister` → `icp
info/canister`
- `src/frontend/src/hooks.server.ts`: `dfx canister id` → `icp canister
status --id-only`
- `demos/using-dev-build/test.ts`: same command updates
- `demos/using-dev-build/vite.plugins.ts`: `DFX_NETWORK` →
`ICP_NETWORK`, `.dfx/` → `.icp/`
- `src/try-ii/src/try-ii-frontend/package.json`: `dfx` → `icp` in npm
scripts

**Documentation**
- `HACKING.md`: all dfx commands → icp-cli equivalents, updated
prerequisites
- `README.md`: updated config example with array-based canisters format
- All demo and stable-memory READMEs updated

## Key command mapping

| dfx | icp-cli |
|-----|---------|
| `dfx start --background` | `icp network start -d` |
| `dfx stop` | `icp network stop` |
| `dfx deploy` | `icp deploy` |
| `dfx build` | `icp build` |
| `dfx canister call` | `icp canister call` |
| `dfx canister id <name>` | `icp canister status <name> --id-only` |
| `dfx canister create --all` | individual `icp canister create <name>`
per canister |
| `--network ic` | `-e ic` |
| `--argument` | `--args` |
| `--argument-type` | `--args-format` |
| `--argument-file` | `--args-file` |
| `--wallet <id>` | `--proxy <id>` |

## Test plan

- [ ] CI passes (canister tests, e2e tests, deploy job)
- [ ] Local development works: `icp network start -d && icp deploy`
- [ ] No remaining active `dfx` references (only historical code
comments preserved)

---------

Co-authored-by: Tim Aterton <timothyaterton@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: timothyaterton

.dockerignore

@@ -15,7 +15,7 @@ Dockerfile
 *.swp
 
 # filter out all "hidden" files and directories
-# (.git, .dfx, .*ignore, etc)
+# (.git, .icp, .*ignore, etc)
 .*
 
 # except for the ones we really want

.github/workflows/canister-tests.yml

@@ -492,13 +492,14 @@ jobs:
       - name: Install Playwright Browsers
         run: npx playwright install chromium
 
-      - uses: dfinity/setup-dfx@e50c04f104ee4285ec010f10609483cf41e4d365
+      - name: Install icp-cli
+        run: npm install -g @icp-sdk/icp-cli@$(cat .icp-cli-version | tr -d '[:space:]')
 
       # Helps with debugging
       - name: Show versions
         run: |
-          echo dfx --version
-          dfx --version
+          echo icp --version
+          icp --version
           echo node --version
           node --version
 
@@ -511,8 +512,8 @@ jobs:
             npm start --prefix ./src/test_openid_provider -- "$port" | tee -a "test-openid-provider-${port}-logs.txt" &
           done
 
-      - name: "Run dfx"
-        run: dfx start --background --artificial-delay 0
+      - name: "Run icp-cli"
+        run: icp network start -d
 
       - name: "Download II backend wasm"
         uses: actions/download-artifact@v4
@@ -533,7 +534,10 @@ jobs:
           path: demos/test-app
 
       - name: Create Canisters
-        run: dfx canister create --all
+        run: |
+          icp canister create internet_identity
+          icp canister create internet_identity_frontend
+          icp canister create test_app
 
       - name: Generate OpenID configs
         id: openid-configs
@@ -548,11 +552,11 @@ jobs:
 
       - name: Deploy canisters
         run: |
-          # NOTE: dfx install will run the postinstall scripts from dfx.json
-          dfx canister install internet_identity --wasm internet_identity_backend.wasm.gz --argument "(opt record { captcha_config = opt record { max_unsolved_captchas= 50:nat64; captcha_trigger = variant {Static = variant { CaptchaDisabled }}}; related_origins = opt vec { \"https://id.ai\"; \"https://identity.ic0.app\"; \"https://identity.internetcomputer.org\" }; new_flow_origins = opt vec { \"https://id.ai\" }; openid_configs = opt vec { ${{ steps.openid-configs.outputs.OPENID_CONFIGS }} } })"
-          II_CANISTER_ID=$(dfx canister id internet_identity)
-          dfx canister install internet_identity_frontend --wasm internet_identity_frontend.wasm.gz --argument "(record { backend_canister_id = principal \"$II_CANISTER_ID\"; backend_origin = \"https://backend.id.ai\"; related_origins = opt vec { \"https://id.ai\"; \"https://identity.ic0.app\"; \"https://identity.internetcomputer.org\" }; fetch_root_key = opt true; dev_csp = opt true })"
-          dfx canister install test_app --wasm demos/test-app/test_app.wasm
+          # NOTE: icp canister install will run the sync steps from icp.yaml
+          icp canister install internet_identity --wasm internet_identity_backend.wasm.gz --args "(opt record { captcha_config = opt record { max_unsolved_captchas= 50:nat64; captcha_trigger = variant {Static = variant { CaptchaDisabled }}}; related_origins = opt vec { \"https://id.ai\"; \"https://identity.ic0.app\"; \"https://identity.internetcomputer.org\" }; new_flow_origins = opt vec { \"https://id.ai\" }; openid_configs = opt vec { ${{ steps.openid-configs.outputs.OPENID_CONFIGS }} } })"
+          II_CANISTER_ID=$(icp canister status internet_identity --id-only)
+          icp canister install internet_identity_frontend --wasm internet_identity_frontend.wasm.gz --args "(record { backend_canister_id = principal \"$II_CANISTER_ID\"; backend_origin = \"https://backend.id.ai\"; related_origins = opt vec { \"https://id.ai\"; \"https://identity.ic0.app\"; \"https://identity.internetcomputer.org\" }; fetch_root_key = opt true; dev_csp = opt true })"
+          icp canister install test_app --wasm demos/test-app/test_app.wasm
 
       - name: Run dev server
         id: dev-server-start
@@ -569,9 +573,9 @@ jobs:
         run: |
           npx playwright test --project ${{ matrix.device }} --workers 1 --shard=$(tr <<<'${{ matrix.shard }}' -s _ /) --reporter=line,html
 
-      - name: Stop dfx
+      - name: Stop icp-cli
         if: ${{ always() }}
-        run: dfx stop
+        run: icp network stop
 
       - name: Stop dev server
         if: ${{ always() }}
@@ -615,7 +619,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: dfinity/setup-dfx@e50c04f104ee4285ec010f10609483cf41e4d365
+      - name: Install icp-cli
+        run: npm install -g @icp-sdk/icp-cli@$(cat .icp-cli-version | tr -d '[:space:]')
 
       - name: "Download II wasm"
         uses: actions/download-artifact@v4
@@ -631,23 +636,23 @@ jobs:
 
       - name: "Install key"
         env:
-          DFX_DEPLOY_KEY: ${{ secrets.DFX_DEPLOY_KEY }}
+          ICP_DEPLOY_KEY: ${{ secrets.DFX_DEPLOY_KEY }}
         run: |
           key_pem=$(mktemp)
-          printenv "DFX_DEPLOY_KEY" > "$key_pem"
-          dfx identity import --disable-encryption --force default "$key_pem"
+          printenv "ICP_DEPLOY_KEY" > "$key_pem"
+          icp identity import --disable-encryption --force default "$key_pem"
           rm "$key_pem"
 
       - name: "Deploy II"
         run: |
           wallet="cvthj-wyaaa-aaaad-aaaaq-cai"
-          # Needed to surpass dfx error to use the insecure plaintext identity
-          export DFX_WARNING=-mainnet_plaintext_identity
+          # Needed to suppress icp-cli warning about insecure plaintext identity
+          export ICP_WARNING=-mainnet_plaintext_identity
           sha=$(shasum -a 256 ./archive.wasm.gz | cut -d ' ' -f1 | sed 's/../\\&/g')
-          dfx canister --network ic --wallet "$wallet" install --mode upgrade \
-            --argument "(opt record {archive_config = record { module_hash = blob \"$sha\"; entries_buffer_limit = 10000:nat64; entries_fetch_limit = 1000:nat16; polling_interval_ns = 60000000000:nat64}; canister_creation_cycles_cost = opt (1000000000000:nat64); })" \
-            --wasm internet_identity_backend.wasm.gz \
-            y2aaj-miaaa-aaaad-aacxq-cai
+          icp canister install y2aaj-miaaa-aaaad-aacxq-cai \
+            -e ic --proxy "$wallet" --mode upgrade \
+            --args "(opt record {archive_config = record { module_hash = blob \"$sha\"; entries_buffer_limit = 10000:nat64; entries_fetch_limit = 1000:nat16; polling_interval_ns = 60000000000:nat64}; canister_creation_cycles_cost = opt (1000000000000:nat64); })" \
+            --wasm internet_identity_backend.wasm.gz
 
       - name: "Download test app wasm"
         uses: actions/download-artifact@v4
@@ -658,11 +663,11 @@ jobs:
       - name: "Deploy test app"
         run: |
           wallet="cvthj-wyaaa-aaaad-aaaaq-cai"
-          # Needed to surpass dfx error to use the insecure plaintext identity
-          export DFX_WARNING=-mainnet_plaintext_identity
-          dfx canister --network ic --wallet "$wallet" install --mode upgrade \
-            --wasm ./test_app.wasm \
-            vt36r-2qaaa-aaaad-aad5a-cai
+          # Needed to suppress icp-cli warning about insecure plaintext identity
+          export ICP_WARNING=-mainnet_plaintext_identity
+          icp canister install vt36r-2qaaa-aaaad-aad5a-cai \
+            -e ic --proxy "$wallet" --mode upgrade \
+            --wasm ./test_app.wasm
 
       - name: "Download VC issuer wasm"
         uses: actions/download-artifact@v4
@@ -673,21 +678,21 @@ jobs:
       - name: "Deploy Issuer"
         run: |
           wallet="cvthj-wyaaa-aaaad-aaaaq-cai"
-          # Needed to surpass dfx error to use the insecure plaintext identity
-          export DFX_WARNING=-mainnet_plaintext_identity
-          dfx canister --network ic --wallet "$wallet" install --mode upgrade \
-            --wasm vc_demo_issuer.wasm.gz \
-            v2yvn-myaaa-aaaad-aad4q-cai
+          # Needed to suppress icp-cli warning about insecure plaintext identity
+          export ICP_WARNING=-mainnet_plaintext_identity
+          icp canister install v2yvn-myaaa-aaaad-aad4q-cai \
+            -e ic --proxy "$wallet" --mode upgrade \
+            --wasm vc_demo_issuer.wasm.gz
           ./demos/vc_issuer/provision \
             --ii-canister-id y2aaj-miaaa-aaaad-aacxq-cai \
-            --dfx-network ic \
+            --icp-network ic \
             --issuer-canister v2yvn-myaaa-aaaad-aad4q-cai \
-            --wallet "$wallet"
+            --proxy "$wallet"
 
       - name: "Deploy archive"
         run: |
-          # Needed to surpass dfx error to use the insecure plaintext identity
-          export DFX_WARNING=-mainnet_plaintext_identity
+          # Needed to suppress icp-cli warning about insecure plaintext identity
+          export ICP_WARNING=-mainnet_plaintext_identity
           scripts/deploy-archive --wasm archive.wasm.gz --canister-id y2aaj-miaaa-aaaad-aacxq-cai --network ic
 
   # This prepares all the files necessary for a release (all flavors of Wasm, release notes).
@@ -801,8 +806,8 @@ jobs:
           cp internet_identity_backend.wasm.gz internet_identity_production.wasm.gz
           cp internet_identity_backend.wasm.gz internet_identity_dev.wasm.gz
 
-      # Create a sha file for dfx pull, referenced by the metadata set in the build
-      - name: Create sha for dfx pull
+      # Create a sha file for icp-cli pull, referenced by the metadata set in the build
+      - name: Create sha for icp-cli pull
         run: |
           shasum -a 256 \
             ./internet_identity_backend.wasm.gz > \

.github/workflows/deploy-rc.yml

@@ -58,25 +58,26 @@ jobs:
       - name: "Print shasum of found build"
         run: shasum -a 256 ./internet_identity_backend.wasm.gz
 
-      - uses: dfinity/setup-dfx@e50c04f104ee4285ec010f10609483cf41e4d365
+      - name: Install icp-cli
+        run: npm install -g @icp-sdk/icp-cli@$(cat .icp-cli-version | tr -d '[:space:]')
 
       - name: "Install key"
         env:
-          DFX_DEPLOY_KEY: ${{ secrets.DFX_DEPLOY_KEY }}
+          ICP_DEPLOY_KEY: ${{ secrets.DFX_DEPLOY_KEY }}
         run: |
           key_pem=$(mktemp)
-          printenv "DFX_DEPLOY_KEY" > "$key_pem"
-          dfx identity import --disable-encryption --force default "$key_pem"
+          printenv "ICP_DEPLOY_KEY" > "$key_pem"
+          icp identity import --disable-encryption --force default "$key_pem"
           rm "$key_pem"
 
       - name: "Deploy Release Candidate"
         run: |
           wallet="${{ env.wallet_canister_id }}"
-          # Needed to surpass dfx error to use the insecure plaintext identity
-          export DFX_WARNING=-mainnet_plaintext_identity
-          dfx canister --network ic --wallet "$wallet" install --mode upgrade \
-            --wasm internet_identity_backend.wasm.gz \
-            ${{ env.ii_canister_id }}
+          # Needed to suppress icp-cli warning about insecure plaintext identity
+          export ICP_WARNING=-mainnet_plaintext_identity
+          icp canister install ${{ env.ii_canister_id }} \
+            -e ic --proxy "$wallet" --mode upgrade \
+            --wasm internet_identity_backend.wasm.gz
 
       - name: Send RC link to slack
         uses: ./.github/actions/slack

.github/workflows/update-dfx.yml

@@ -0,0 +1,60 @@
+# A GitHub Actions workflow that regularly checks for new icp-cli releases
+# and creates a PR on new versions.
+name: icp-cli Update
+
+on:
+  schedule:
+    # check for new icp-cli releases daily at 7:30
+    - cron: "30 7 * * *"
+  workflow_dispatch:
+
+jobs:
+  icp-cli-update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+        # First, check icp-cli releases for a new version.
+      - name: Check new icp-cli version
+        id: update
+        run: |
+          current_icp_cli_release=$(cat .icp-cli-version | tr -d '[:space:]')
+          echo "current icp-cli release '$current_icp_cli_release'"
+
+          latest_icp_cli_release=$(curl -sSL https://api.github.com/repos/dfinity/icp-cli/releases/latest | jq -r '.tag_name | sub("^v"; "")')
+          echo "latest icp-cli release '$latest_icp_cli_release'"
+
+          if [ "$current_icp_cli_release" != "$latest_icp_cli_release" ]
+          then
+            echo icp-cli needs an update
+            echo "$latest_icp_cli_release" > .icp-cli-version
+            echo "updated=1" >> "$GITHUB_OUTPUT"
+          else
+            echo "updated=0" >> "$GITHUB_OUTPUT"
+          fi
+
+          cat .icp-cli-version
+
+        # If the version was updated, create a PR.
+      - name: Create Pull Request
+        if: ${{ steps.update.outputs.updated == '1' }}
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GIX_BOT_PAT }}
+          base: main
+          add-paths: ./.icp-cli-version
+          commit-message: Update icp-cli release
+          committer: GitHub <noreply@github.com>
+          author: gix-bot <gix-bot@users.noreply.github.com>
+          branch: bot-icp-cli-update
+          delete-branch: true
+          title: "Update icp-cli"
+
+        # Since this is a scheduled job, a failure won't be shown on any
+        # PR status. To notify the team, we send a message to our Slack channel on failure.
+      - name: Notify Slack on failure
+        uses: ./.github/actions/slack
+        if: ${{ failure() }}
+        with:
+          WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+          MESSAGE: "icp-cli update failed: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"

.github/workflows/update-icp-cli.yml

@@ -8,8 +8,8 @@
 .DS_Store
 **/.DS_Store
 
-# dfx temporary files
-.dfx/
+# icp-cli temporary files
+.icp/
 
 # frontend code
 node_modules/

.gitignore

@@ -0,0 +1 @@
+0.2.0

.icp-cli-version

@@ -7,8 +7,8 @@
 .DS_Store
 **/.DS_Store
 
-# dfx temporary files
-.dfx/
+# icp-cli temporary files
+.icp/
 
 # frontend code
 node_modules/