dfinity/icskills

autoupgrade-icp-cli

One-time installer that keeps a project's Internet Computer CLI toolchain current.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/dfinity/icskills --skill autoupgrade-icp-cli

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Set up automatic icp CLI upgrades

A one-time installer: it adds a SessionStart hook that checks whether icp and ic-wasm are current and — if the user wants — upgrades them before work starts. Once these steps are done the user never needs this skill again.

ic-wasm is covered alongside icp because the official recipes (@dfinity/motoko, @dfinity/rust, @dfinity/static-site, @dfinity/asset-canister) invoke it on every build. An ic-wasm left behind while icp moves forward produces build failures that read as recipe bugs, so upgrading only one of the pair is the worse default.

icp has its own check (icp settings update-check) that is worth leaving on, but it only speaks once the user runs an icp command — by which point the agent has already chosen what to write. This hook runs before the session's first prompt, so the version reaches Claude's context up front, and it covers ic-wasm too.

Step 1 — Ask the user which mode they want

The installer cannot make this call for the user, so ask before writing anything:

"Two options for how the hook behaves when a newer version exists: notify — it prints the versions and the exact upgrade command, and nothing is installed until you run it. auto — it runs that upgrade itself at session start. Which do you want? You can switch later by editing one flag in the hook."

Default to notify if the user has no preference — it is the reversible choice.

Also tell them what adding a hook means, and do not attempt to bypass the approval:

"I'm adding a SessionStart hook that runs .claude/upgrade-icp-cli.sh. Claude Code will ask you to approve/trust it before it runs automatically."

Step 2 — Check prerequisites

bash
command -v curl   >/dev/null 2>&1 && echo "curl: ok" || echo "curl: MISSING"
icp --version     2>/dev/null     || echo "icp: not installed"
ic-wasm --version 2>/dev/null     || echo "ic-wasm: not installed"

If either tool is missing, mention the install command (npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm) but do not run it unprompted — installing a toolchain is a different decision from keeping one current.

Step 3 — Download the script

Fetch the published script verbatim rather than transcribing it, so the channel detection stays correct as it is updated upstream:

bash
mkdir -p .claude
curl -fsSL https://skills.internetcomputer.org/.well-known/skills/autoupgrade-icp-cli/scripts/upgrade-icp-cli.sh \
  -o .claude/upgrade-icp-cli.sh

Do not hand-write or paraphrase it.

Step 4 — Register the SessionStart hook (idempotently)

If .claude/settings.json does not exist, create it with the content below. If it does, merge: preserve every existing key, hook, and permission, add the SessionStart entry only if an equivalent bash .claude/upgrade-icp-cli.sh command is not already there, and write the parsed JSON back. Never overwrite the file.

Notify mode (the default):

json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "bash .claude/upgrade-icp-cli.sh --mode notify" }
        ]
      }
    ]
  }
}

Auto mode — same entry with --mode auto, plus a raised timeout, because installing a CLI binary can exceed the default 60 s and a timed-out install leaves the tool half-written:

json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "bash .claude/upgrade-icp-cli.sh --mode auto", "timeout": 300 }
        ]
      }
    ]
  }
}

Whenever you hand someone an auto-mode hook, say the thing that makes it a real choice: it upgrades the build toolchain while a project is open and blocks session start while it runs, so a session can begin against a different icp than the last one ended with — which can change build behaviour and output for a project that built fine yesterday. That is what some teams want and what others pin against.

Step 5 — Run it once, verify, report

bash
bash .claude/upgrade-icp-cli.sh --mode notify   # or --mode auto, matching the hook

Silence means both tools are current — that is the success case, not a failure. A hand-run always checks the network; the hook throttles (below), so this is also the command for whenever someone wants an answer now.

Then confirm the hook entry appears exactly once, report the versions found and whether anything was upgraded, and remind the user of the trust prompt. If the project commits .claude/, add .claude/.icp-upgrade-check to .gitignore — it is a per-machine timestamp, not shared configuration.

How the script decides what to run

It resolves each binary through its symlinks and reads the install channel off the path, because the upgrade command differs per channel and guessing wrong leaves two copies of the CLI on PATH shadowing each other:

Where the binary resolves toChannelUpgrade command (icp / ic-wasm)
…/node_modules/@icp-sdk/…npmnpm install -g @icp-sdk/icp-cli@latest / npm install -g @icp-sdk/ic-wasm@latest
…/Cellar/…Homebrewbrew upgrade icp-cli / brew upgrade ic-wasm
a cargo-dist receipt in ~/.config/<app>/shell installericp-cli-update / ic-wasm-update
anything elseunknown(none — reports the release URL instead)

That last row is deliberate: an unrecognised install is reported, never guessed at.

Two consequences worth passing on to users:

  • A shadowed install never moves. If an upgrade succeeds but PATH still resolves

to the old version, a second copy from another channel is winning — commonly an npm global under nvm alongside a shell-installer copy in ~/.cargo/bin. Upgrading one channel can never touch the other's copy; resolve the binary (command -v icp) to see which wins, then remove one or upgrade the one actually on PATH.

  • Auto mode never runs `sudo`. A non-writable npm prefix is reported as a sudo …

command instead, since a password prompt inside a hook has no terminal to answer it.

Throttling

A check that reached a release feed is stamped in .claude/.icp-upgrade-check and not repeated for 6 hours, so the hook costs ~10 ms on most session starts instead of ~1 s. Override with ICP_UPGRADE_CHECK_INTERVAL=<seconds> (0 disables it) or bypass once with --force; a run from a terminal always checks. A failed probe is not stamped, so an offline session retries at the next one.

What this does not upgrade

The hook manages the two CLI binaries only. Recipe versions in icp.yaml (@dfinity/motoko@v5.0.0 and friends) and the Motoko toolchain (moc, mops, the [toolchain] pin in mops.toml) are pinned per project and stay the user's call — load icp-cli and mops-cli respectively for those.

If a build starts failing right after an auto upgrade, check the icp-cli release notes before assuming the project broke.

Additional References

  • `icp-cli` — using the CLI itself: icp.yaml, recipes, environments, deployment.
  • `mops-cli` — the Motoko toolchain and its own version pinning.
  • `autosync-ic-skills` — the companion installer that keeps the IC skills in

.claude/skills/ current. The two are independent; installing both is common.

from this repository

More skills

All skills
dfinity
Community

buy-cycles

Buy cycles with a credit card for the CLI's own identity with icp cycles buy, through CyclePay's on-chain gateway, then continue deploying. Use when a mainnet deploy or canister creation fails for lack of cycles, the user has no ICP, no wallet or no exchange account, or asks to pay for cycles by card, Stripe, fiat or USD. Do NOT use for converting ICP you already hold (cycles-management: icp cycles mint), for topping up a canister from an existing balance, or for Internet Identity sign-in (agent

1h installs
1
GitHub stars
39
Updated
Nov 11
dfinity
Community

canhelp

Display a human-readable summary of a canister's interface given its mainnet canister ID or a human-readable name. Like --help but for canisters. Only for mainnet canisters — for local canisters, read the generated .did file in your project directly.

1h installs
1
GitHub stars
39
Updated
Nov 11
dfinity
Community

canister-security

IC-specific security patterns for canister development in Motoko and Rust. Covers access control, anonymous principal rejection, reentrancy prevention (CallerGuard pattern), async safety (saga pattern), callback trap handling, cycle drain protection, and safe upgrade patterns. Use when writing or modifying any canister that modifies state, handles tokens, makes inter-canister calls, or implements access control.

1h installs
1
GitHub stars
39
Updated
Nov 11
dfinity
Community

ckbtc

Accept, send, and manage ckBTC (chain-key Bitcoin). Covers BTC deposit flow via minter, ckBTC transfers, withdrawal to BTC, subaccount derivation, and UTXO management. Use when integrating Bitcoin, ckBTC, BTC deposits, or BTC withdrawals in a canister. Do NOT use for plain token transfers without BTC minting/withdrawal — use icrc-ledger instead.

1h installs
1
GitHub stars
39
Updated
Nov 11