DFINITY Retires dfx: Inside the Brand-New "icp-cli" Developer Revolution

For years, the dfx command-line utility has been the undisputed backbone of the developer workflow on the Internet Computer (ICP). But in a massive paradigm shift, the DFINITY Foundation is officially ushering in a new era. DFINITY has released icp-cli v0.3.0—the final milestone beta before the official v1.0 release—marking the transition of the legacy dfx tool into retirement.

icp-cli is not a simple rebrand. It is a ground-up architectural rebuild designed to fix long-standing developer pain points, enforce reproducible builds, and dramatically improve terminal-level Developer Experience (DX).

Goodbye JSON, Hello YAML and Build "Recipes"

The first major change developers will notice is the transition from JSON to YAML. Project configuration files now live in icp.yaml. More importantly, icp-cli decouples the CLI tool from specific language compilers or runtimes using a modular recipe system.

Historically, updating dfx was a fragile process because it contained tightly coupled, opinionated build environments. With icp-cli, building WebAssembly (WASM) binaries is delegated directly to underlying toolchains. Pinned, reusable recipes (such as @dfinity/rust or @dfinity/motoko) ensure that builds remain fully reproducible.

The v0.3.0 update pushes this decoupling further with sync plugins. Asset canisters—historically baked directly into the CLI binary—are now synced through a sandboxed WASM plugin. This ensures the CLI tool is never bottlenecked by outdated asset configurations.

Logical Environments vs. Project-Local Networks

Deploying code on the Internet Computer has also undergone a massive conceptual upgrade:

• Logical Environments: Instead of using --network ic, developers now use the -e or --environment flag (e.g., icp deploy -e ic). This abstracts away hardcoded network URLs from canister logic, allowing developers to target multiple distinct environments (such as staging and production) on the same underlying physical network.
• Project-Local Networks: Unlike dfx, which runs a shared global network in the background, icp-cli runs an isolated network per project using a lightweight PocketIC wrapper. Running icp network start -d fires up a project-local sandbox pre-seeded with system canisters, test ICP, and cycles.

Terminal-Native Internet Identity Login

Perhaps the most exciting breakthrough for day-to-day work is terminal-level login with Internet Identity (II). Developers can now programmatically link a web-based identity to their CLI session. Your terminal principal will perfectly match the principal generated on your web frontends, eliminating the hassle of manually creating and authorizing separate developer keys.

Additionally, icp-cli introduces Friendly Local Domains (no more copying and pasting long, cryptic canister principals in your browser) and Candid Assist, which provides interactive, auto-completed terminal guidance for crafting complex canister calls.

How to Upgrade

The new suite is available globally. You can install the core tools via npm:

npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm

Or on macOS and Linux using Homebrew:

brew install icp-cli

With the official 1.0 release right around the corner, DFINITY is encouraging all active developer teams to consult the migration guide and port their projects to icp.yaml to prepare for the future of on-chain computing.