Upgrading from icp-cli 0.2

The built-in assets sync step (type: assets) is removed in releases after 0.2.x — starting with the 0.3 release candidate and carried into 1.0.0. If you’re upgrading a project from icp-cli 0.2.x, this guide shows how to switch to the plugin-based replacement.

What changed

The assets sync step uploaded a directory to an asset canister from inside icp-cli core. That capability is retired: asset uploading now lives outside the CLI, in a recipe-provided sync plugin. The script and plugin sync steps are unaffected.

Do you need to migrate?

You’re affected if your icp.yaml (or a per-canister canister.yaml) either:

• contains a type: assets sync step, or
• uses the @dfinity/asset-canister recipe at a version below v2.2.1 (those versions emit a type: assets step internally).

After upgrading, any command that loads such a manifest (icp deploy, icp sync, …) fails to load it with a targeted error:

icp-cli no longer supports the `assets` sync step type. Switch to a `script` or
`plugin` sync step. If this step comes from a recipe, check whether a newer
version of the recipe uses a plugin-based solution.

Pick the path that matches how your project uploads assets:

• Recipe users — bump the @dfinity/asset-canister recipe version.
• Manual sync steps — switch a hand-written type: assets step to the certified-assets sync plugin.

Recipe users

If you reference the @dfinity/asset-canister recipe, upgrade it to v2.2.1. That version emits a plugin sync step instead of the retired assets step; nothing else in your configuration changes.

Before:

canisters:
  - name: frontend
    recipe:
      type: "@dfinity/asset-canister@v2.1.0"
      configuration:
        dir: www

After:

canisters:
  - name: frontend
    recipe:
      type: "@dfinity/asset-canister@v2.2.1"
      configuration:
        dir: www

The recipe’s configuration (including dir) is unchanged. See the asset-canister v2.2.1 release for details.

Manual sync steps

If your manifest declares type: assets directly, replace it with a plugin sync step that points at the certified-assets migration plugin.

Before:

sync:
  steps:
    - type: assets
      dirs:
        - www

After:

sync:
  steps:
    - type: plugin
      url: https://github.com/dfinity/certified-assets/releases/download/migration-v2.2.1-6b48585/sync_plugin.wasm
      sha256: ca7cb5666c30d2875f8d5e10535f8a53f97a86c79c263f7d5bdac2fdd1bbf83c
      dirs:
        - www

The plugin is published in the certified-assets migration-v2.2.1 release. It uploads the contents of a single directory to the asset canister being synced — the same job the old assets step did. dirs is the general sync-plugin field (a list, since a plugin may declare several directories), but this particular plugin reads exactly one — list a single entry. The url/sha256 pin the exact wasm: icp-cli downloads it once, verifies the checksum, and caches it.

Your build step is unchanged — keep building or providing the asset-canister wasm exactly as before. Only the sync step changes.

Convert dir: to dirs:

The assets step accepted either a single dir: or a list dirs:. The plugin step only takes the list form, and this plugin reads exactly one directory from it. If you used the singular dir:, wrap it in a single-element dirs: list:

Before:

- type: assets
  dir: dist

After:

- type: plugin
  url: https://github.com/dfinity/certified-assets/releases/download/migration-v2.2.1-6b48585/sync_plugin.wasm
  sha256: ca7cb5666c30d2875f8d5e10535f8a53f97a86c79c263f7d5bdac2fdd1bbf83c
  dirs:
    - dist

If your old assets step listed more than one directory, consolidate the files into a single directory before uploading — this plugin accepts only one.

Verify

After editing the manifest, redeploy:

icp deploy

The manifest now loads, the plugin downloads and its checksum is verified, and your assets upload exactly as they did with the built-in step.

See also

• Sync Plugins — how the plugin sandbox works
• Plugin Sync (Configuration Reference) — the plugin step manifest fields
• Using Recipes — referencing and pinning recipe versions

Browse all documentation →