You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add new Canister Snapshots guide covering create, download, upload, restore, and delete workflows with pre-upgrade backup and state transfer examples
Add new Canister Migration guide with two approaches: snapshot-only transfer (new ID) and full migration via migrate-id (preserved ID), including troubleshooting and interruption handling
Enhance Tokens and Cycles guide with subaccount documentation (balance checks, transfers, receiver address formats, account identifiers)
Enhance Local Development guide with --query flag, proxy canister usage, and network status --json example output
Enhance Containerized Networks guide with launcher version pinning section
Improve Environments concept doc with api-url / http-gateway-url YAML example
Replace outdated "delete and redeploy" advice in Deploying to Specific Subnets with links to the new migration guides
Wire up new guides in sidebar navigation, index pages, and cross-links
Here also a summary of recommendations Claude came up with when creating the docs. I am not sure if a single high-level command makes sense is this involves quite a lot of different operations.
But a few of those recommendations certainly make sense.
CLI Improvement Recommendations: Snapshots and Migration
High Priority
Allow icp canister create without icp.yaml entry — The migration workflow requires a throwaway icp.yaml entry with a dummy build step just to create a target canister. A command like icp canister create --subnet <id> -n ic that returns a canister ID directly would make migration significantly simpler. It would also benefit any workflow where users need to create ad-hoc canisters.
Add icp canister migrate as a single high-level command — The full migration workflow (snapshot create, download, upload, restore, delete snapshot, copy settings, stop both, migrate-id, start, clean up) spans 8+ manual steps across two guides. A single icp canister migrate my-canister --to-subnet <id> that orchestrates all steps would dramatically improve the experience. It could preserve the current step-by-step approach as --dry-run output.
Medium Priority
Auto-remove NNS migration canister as controller — After a successful migrate-id, the NNS migration canister (sbzkb-zqaaa-aaaaa-aaaiq-cai) remains as a controller. The CLI could automatically remove it once migration completes, since there's no reason to keep it. This would eliminate the manual cleanup step.
Copy settings automatically during migration — migrate-id could read the source canister's settings and apply non-default values to the target before initiating the ID swap. This would eliminate the manual "Copy Settings" step and reduce the risk of forgetting to copy an important setting.
Warn about cycles and offer to drain before migration — The CLI already warns about high cycle balances on the source canister. It could go further by offering to transfer cycles from the source to the user's cycles balance before the destructive migration burns them.
Lower Priority
Add --snapshot flag to migrate-id — Allow migrate-id to handle the snapshot transfer inline: create snapshot on source, upload to target, restore, delete snapshot on target. This would collapse multiple steps into the existing command.
Auto-clean icp.yaml after migration — After a successful migration, the CLI could offer to remove the temporary migration-target entry from icp.yaml and the mappings file, since that canister ID no longer exists.
Add snapshot create --auto-stop — A convenience flag that stops the canister, takes the snapshot, and restarts it, minimizing the commands needed for the common backup workflow.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
migrate-id(preserved ID), including troubleshooting and interruption handling--queryflag, proxy canister usage, andnetwork status --jsonexample outputapi-url/http-gateway-urlYAML example