ICP CLI

# Homebrew (macOS/Linux)
brew install icp-cli
brew install ic-wasm

# Shell script (macOS/Linux/WSL)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.sh | sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/ic-wasm/releases/latest/download/ic-wasm-installer.sh | sh

Verify:

icp --version
ic-wasm --version

Linux note: On minimal installs, you may need system libraries: sudo apt-get install -y libdbus-1-3 libssl3 ca-certificates (Ubuntu/Debian) or sudo dnf install -y dbus-libs openssl ca-certificates (Fedora/RHEL).

Prerequisites

• For Rust canisters: rustup target add wasm32-unknown-unknown
• For Motoko canisters: npm i -g ic-mops and a mops.toml at the project root with the Motoko compiler version:

  [toolchain]
  moc = "1.3.0"
  

  The @dfinity/motoko recipe uses this to resolve the compiler. Without mops.toml, the recipe fails because moc is not found. Templates include mops.toml automatically; for manual projects, create it before running icp build.

Common Pitfalls

1. Using dfx instead of icp. The dfx tool is legacy. All commands have icp equivalents — see references/dfx-migration.md for the full command mapping. Never generate dfx commands or reference dfx documentation. Configuration uses icp.yaml, not dfx.json — and the structure differs: canisters are an array of objects, not a keyed object.

2. Using --network ic to deploy to mainnet. icp-cli uses environments, not direct network targeting. The correct flag is -e ic (short for --environment ic).

   # Wrong
   icp deploy --network ic
   # Correct
   icp deploy -e ic
   

   Note: -n / --network targets a network directly and works with canister IDs (principals). Use -e / --environment when referencing canisters by name. For token and cycles operations, use -n since they don't reference project canisters.

3. Using a recipe without a version pin. icp-cli rejects unpinned recipe references. Always include an explicit version. Official recipes are hosted at dfinity/icp-cli-recipes.

   # Wrong — rejected by icp-cli
   recipe:
     type: "@dfinity/rust"
   
   # Correct — pinned version
   recipe:
     type: "@dfinity/[email protected]"
   

4. Writing manual build steps when a recipe exists. Official recipes handle Rust, Motoko, and asset canister builds. Use them instead of writing shell commands:

   # Unnecessary — use a recipe instead
   build:
     steps:
       - type: script
         commands:
           - cargo build --target wasm32-unknown-unknown --release
           - cp target/.../backend.wasm "$ICP_WASM_OUTPUT_PATH"
   
   # Preferred
   recipe:
     type: "@dfinity/[email protected]"
     configuration:
       package: backend
   

5. Not committing .icp/data/ to version control. Mainnet canister IDs are stored in .icp/data/mappings/<environment>.ids.json. Losing this file means losing the mapping between canister names and on-chain IDs. Always commit .icp/data/ — never delete it. Add .icp/cache/ to .gitignore (it is ephemeral and rebuilt automatically).

6. Using icp identity use instead of icp identity default. The dfx command dfx identity use became icp identity default. Similarly, dfx identity get-principal became icp identity principal, and dfx identity remove became icp identity delete.

7. Confusing networks and environments. A network is a connection endpoint (URL). An environment combines a network + canisters + settings. You deploy to environments (-e), not networks. Multiple environments can target the same network with different settings (e.g., staging and production both on ic).

8. Forgetting that local networks are project-local. Unlike dfx which runs one shared global network, icp-cli runs a local network per project. You must run icp network start -d in your project directory before deploying locally. The local network auto-starts with system canisters and seeds accounts with ICP and cycles.

9. Not specifying build commands for asset canisters. dfx automatically runs npm run build for asset canisters. icp-cli requires explicit build commands in the recipe configuration:

   canisters:
     - name: frontend
       recipe:
         type: "@dfinity/[email protected]"
         configuration:
           dir: dist
           build:
             - npm install
             - npm run build
   

10. Expecting output_env_file or .env with canister IDs. dfx writes canister IDs to a .env file (CANISTER_ID_BACKEND=...) via output_env_file. icp-cli does not generate .env files. Instead, it injects canister IDs as environment variables (PUBLIC_CANISTER_ID:<name>) directly into canisters during icp deploy. Frontends read these from the ic_env cookie set by the asset canister. Remove output_env_file from your config and any code that reads CANISTER_ID_* from .env — use the ic_env cookie instead (see Canister Environment Variables below).

11. Expecting dfx generate for TypeScript bindings. icp-cli does not have a dfx generate equivalent. Use @icp-sdk/bindgen (>= 0.3.0) with @icp-sdk/core (>= 5.0.0 — there is no 0.x or 1.x release) to generate TypeScript bindings from .did files at build time. Use outDir: "./src/bindings" so imports are clean (e.g., ./bindings/backend). The .did file must exist on disk — either commit it to the repo, or generate it with icp build first (recipes auto-generate it when candid is not specified). See references/binding-generation.md for the full Vite plugin setup.

12. Mixing canister-level fields across config styles. When using a recipe, the only valid canister-level fields are name, recipe, sync, settings, and init_args. Fields like candid, build, or wasm are not valid at canister level alongside a recipe — recipe-specific options go inside recipe.configuration. When using bare build (no recipe), valid canister-level fields are name, build, sync, settings, and init_args. The field init_arg_file does not exist — use init_args.path instead (e.g., init_args: { path: ./args.bin, format: bin }). For the authoritative field reference, consult the icp-cli configuration reference.

    # Wrong — candid is not a canister-level field when using a recipe
    canisters:
      - name: backend
        candid: backend/backend.did
        recipe:
          type: "@dfinity/[email protected]"
          configuration:
            package: backend
    
    # Correct — candid goes inside recipe.configuration
    canisters:
      - name: backend
        recipe:
          type: "@dfinity/[email protected]"
          configuration:
            package: backend
            candid: backend/backend.did
    

13. Misunderstanding Candid file generation with recipes. When using the Rust or Motoko recipe:

    • If candid is specified: the file must already exist (checked in or manually created). The recipe uses it as-is and does not generate one.
    • If candid is omitted: the recipe auto-generates the .did file from the compiled WASM (via candid-extractor for Rust, moc for Motoko). The generated file is placed in the build cache, not at a predictable project path.

    For projects that need a .did file on disk (e.g., for @icp-sdk/bindgen), the recommended pattern is: generate the .did file once, commit it, and specify candid in the recipe config. To generate it manually:

    Rust — build the WASM first, then extract the Candid interface:

    cargo install candid-extractor  # one-time setup
    icp build backend
    candid-extractor target/wasm32-unknown-unknown/release/backend.wasm > backend/backend.did
    

    Motoko — use moc directly with the --idl flag:

    $(mops toolchain bin moc) --idl $(mops sources) -o backend/backend.did backend/app.mo
    

How It Works

Project Creation

icp new scaffolds projects from templates. Without flags, an interactive prompt launches. For scripted or non-interactive use, pass --subfolder and --define flags directly. Available templates and options: dfinity/icp-cli-templates.

Build → Deploy → Sync

Source Code → [Build] → WASM → [Deploy] → Running Canister → [Sync] → Configured State

icp deploy runs all three phases in sequence:

1. Build — Compile canisters to WASM (via recipes or explicit build steps)
2. Deploy — Create canisters (if new), apply settings, install WASM
3. Sync — Post-deployment operations (e.g., upload assets to asset canisters)

Run phases separately for more control:

icp build                     # Build only
icp deploy                    # Full pipeline (build + deploy + sync)
icp sync my-canister          # Sync only (e.g., re-upload assets)

Environments and Networks

Two implicit environments are always available:

The ic network is protected and cannot be overridden.

Custom environments enable multiple deployment targets on the same network: