Skills
skills/jorgenbuilder/icp-skills/icp-cli

icp-cli

SKILL.md

ICP CLI Usage

Hard rule: no dfx

  • Never suggest or use the legacy dfx command.
  • Any time the user mentions dfx, map the request to the equivalent icp command(s).
  • If a reference or example uses dfx, translate it to icp before responding.

Quick start workflow

Default to these steps unless the user asks for a specific command:

Standard workflow (template-based):

  1. Create a project: icp new my-project (interactive prompts for template selection)
  2. Enter project: cd my-project
  3. Start local network: icp network start -d
  4. Deploy (builds automatically): icp deploy
  5. Call a method: icp canister call <canister> <method> '(...)'
  6. Verify if needed: icp network status, icp canister status <canister>

Non-interactive project creation:

icp new my-project --subfolder hello-world \
  --define backend_type=rust \
  --define frontend_type=react \
  --define network_type=Default

Custom project with recipes:

  1. Create directory: mkdir my-project && cd my-project
  2. Create icp.yaml with recipe configuration (see recipe section)
  3. Create source code
  4. Start network: icp network start -d
  5. Deploy: icp deploy

Recipes (@dfinity/rust@v3.0.0, @dfinity/motoko@v4.0.0, @dfinity/asset-canister@v2.1.0, @dfinity/prebuilt@v2.0.0) provide best-practice configurations and reduce boilerplate. All recipes MUST include an explicit version.

Use -e/--environment when the user specifies a target (deploy uses environments; network start uses a network name or -e).

Preflight checks

Use these to confirm the environment quickly:

  • icp --version
  • icp network list
  • icp network status (or icp network ping --wait-healthy)

Command map (common tasks)

Project lifecycle:

  • icp new - Create project from template (uses cargo-generate)
  • icp build - Build canisters
  • icp deploy - Deploy canisters (builds automatically)
  • icp sync - Sync assets to asset canister
  • icp project show - View expanded configuration (useful for recipes)

Local network:

  • icp network start|status|ping|stop
  • Note: Windows requires Docker Desktop for local networks

Canister operations:

  • icp canister create|install|call|status|delete|list
  • icp canister start|stop - Control canister state
  • icp canister metadata <canister> <section> - Read metadata sections
  • icp canister settings show|update|sync - Manage settings
  • icp canister top-up --amount <amount> <canister> - Add cycles

Identities:

  • icp identity new|list|default|principal|import|export|rename|delete
  • icp identity account-id - Get ledger AccountIdentifier
  • icp identity link hsm - Link HSM identity (PKCS#11)
  • Storage modes: keyring (default), password-protected, plaintext

Cycles:

  • icp cycles balance|mint - Check and mint cycles
  • icp cycles transfer <amount> <receiver> - Transfer cycles
  • icp cycles mint --icp <amount> or --cycles <amount> - Convert ICP to cycles
  • Human-friendly amounts: 1k, 1.5m, 2T

Tokens:

  • icp token balance - ICP token balance
  • icp token transfer <amount> <receiver> - ICP token transfer
  • icp token <LEDGER_ID> balance|transfer - ICRC-1 token operations
  • Accepts AccountIdentifier hex strings

Environments:

  • icp environment list - List environments
  • Use -e <env> for environment-specific commands
  • Use -e ic for mainnet (not --mainnet)

Arguments:

  • Positional argument can be Candid text, hex, or file path
  • icp canister call <canister> <method> <arg> where arg can be a file path
  • icp canister install <canister> --args <arg> where arg can be a file path

Decision points

Recipe selection:

  • Use official @dfinity/ recipes for standard canister types
  • @dfinity/rust@v3.0.0 - Rust canisters (config: package = Cargo package name)
  • @dfinity/motoko@v4.0.0 - Motoko canisters (config: main = main .mo file, args required - see note below)
  • @dfinity/asset-canister@v2.1.0 - Frontend assets (config: dir = asset directory)
  • @dfinity/prebuilt@v2.0.0 - Pre-built WASM (config: path + sha256)
  • All recipes MUST specify a version: @dfinity/rust@v3.0.0 (unversioned is not supported)
  • Motoko v4.0.0 note: args in recipe configuration is currently required (moc compiler flags). Use args: "" if no extra flags needed. Will become optional in a future Motoko recipe release.
  • Use local recipes for custom workflows: file://recipes/custom.hbs
  • Remote recipes require sha256 for integrity

Environment strategy:

  • Default to local if unspecified
  • Use -e ic for IC mainnet (not --mainnet or --ic, removed since beta.5)
  • Custom environments defined in icp.yaml: -e staging, -e production
  • Multi-stage workflow: local → staging → ic
  • Each environment has separate canister IDs in .icp/<env>/canister_ids.json

Network vs environment flags (-n vs -e):

  • -n (network): Use for token and cycles operations (icp token balance -n ic, icp cycles mint -n ic)
  • -e (environment): Use for canister operations that reference canister names (icp deploy -e ic, icp canister status my-canister -e ic)
  • Canister IDs (not names) can use either flag
  • Quick rule: icp token * and icp cycles * → use -n; icp deploy, icp canister *, icp build → use -e

Network type:

  • Managed networks (default): Native PocketIC, simpler for local dev
  • Docker networks: Docker-based, isolated, ideal for CI/CD
  • Windows: Docker Desktop required for all local networks

Platform-specific:

  • Windows: Native support for Rust canisters; Motoko requires WSL; Docker Desktop required for local networks
  • macOS/Linux: Full native support for all canister types; Docker optional (only for Docker-based networks)
  • Large WASM: Automatic chunking for >2MB (no manual action needed)

Identity storage:

  • Production: Always keyring (OS keychain)
  • Development: Keyring or password-protected
  • CI/CD: Password-protected with secrets management
  • HSM: Hardware security modules via PKCS#11 (icp identity link hsm)
  • Never: Plaintext for production (insecure)

Local development identity:

  • Local networks use an anonymous identity that is pre-funded with cycles
  • No need to create/fund an identity for local development
  • Just icp network start -d && icp deploy works out of the box

Deploy output:

  • icp deploy prints canister URLs after successful deployment
  • Frontend URLs follow the pattern: http://<canister-id>.localhost:8000

Deployment mode:

  • Use --mode install|reinstall|upgrade only when user requests it
  • Default: auto-detects based on canister state

Resource allocation:

  • Set compute_allocation (0-100%) for performance guarantees
  • Set memory_allocation for predictable billing
  • Configure freezing_threshold (default 30 days, recommend 90 days for production)
  • Budget 1-2T cycles minimum for production canisters

Canister settings:

  • log_visibility: controllers (default), public, or allowed_viewers with specific principals
  • environment_variables: Runtime key-value pairs for canister configuration
  • wasm_memory_limit, wasm_memory_threshold: Memory controls

Amount format:

  • Use human-friendly: 2T, 500m, 1.5b, 100k (trillion, million, billion, thousand)
  • Or underscores: 2_000_000_000_000
  • Avoid raw numbers (hard to read)

Controller safety:

  • CLI warns before removing self from controllers
  • Use --force to skip confirmation (scripts only, dangerous)
  • Always maintain multiple controllers for critical canisters

Legacy compatibility:

  • Local vs ic: Use -e ic (not --mainnet or --ic, removed since beta.5)
  • Cycles transfer: Use icp cycles transfer (not icp token cycles transfer, removed since beta.5)
  • Identity switch: Use icp identity default (not icp identity use)
  • Map all dfx commands to icp equivalents

Common mistakes to avoid

These are frequent errors. Never produce these patterns:

  • Wrong: dfx deploy → Correct: icp deploy (never use dfx)
  • Wrong: icp deploy --mainnet → Correct: icp deploy -e ic
  • Wrong: icp identity use dev → Correct: icp identity default dev
  • Wrong: icp token cycles transfer --to X --amount 2T → Correct: icp cycles transfer 2T X -n ic
  • Wrong: icp token transfer --to X --amount 10 → Correct: icp token transfer 10 X -n ic
  • Wrong: icp cycles mint --amount 5 → Correct: icp cycles mint --icp 5 -n ic or --cycles 5T
  • Wrong: icp identity new prod --storage-mode keyring → Correct: icp identity new prod --storage keyring
  • Wrong: @dfinity/rust (no version) → Correct: @dfinity/rust@v3.0.0 (version required)
  • Wrong: icp new --recipe @dfinity/rust → Correct: icp new my-project (recipes go in icp.yaml, not in icp new)
  • Wrong: Using -e for token/cycles ops → Correct: Use -n ic for icp token and icp cycles commands
  • Wrong: Motoko recipe without args → Correct: Include args: "" in motoko v4.0.0 recipe configuration
  • Wrong: icp canister top-up for sending cycles to another user → Correct: icp canister top-up adds cycles to a canister you manage; icp cycles transfer sends cycles to any canister/principal

Usage guidance

  • All recipes MUST include a version: e.g., @dfinity/rust@v3.0.0 (unversioned recipes are not supported)
  • Use environments for multi-stage deployments: -e local, -e staging, -e ic
  • Default to keyring for identity storage: Most secure option
  • Budget cycles proactively: 1-2T minimum for production, use human-readable amounts (2T, 500m)
  • Default to local network workflows unless a target is specified
  • Use -e/--environment or -n/--network when a target is named, but never both
  • Suggest --identity when multiple identities might exist
  • Provide the minimal command set plus a short verify step
  • If call arguments are unknown, omit args to trigger the interactive prompt

Troubleshooting

Local network:

  • Port 8000 already in use: local PocketIC binds to localhost:8000. If icp network start fails, check and stop the other process with lsof -i :8000 and kill <PID>.
  • Shutdown: icp network stop (use when finished with local testing).
  • Verify network: icp network status or icp network ping --wait-healthy

Recipe errors:

  • URL fetch failure: Check network connection, verify recipe URL is accessible
  • SHA-256 mismatch: Recipe content changed, update sha256 hash or use a different version-pinned recipe
  • Template expansion errors: Run icp project show to see expanded config and identify issues

Environment issues:

  • Wrong network: Verify -e <env> matches intended environment with icp environment list
  • Canister not found: Check .icp/<env>/canister_ids.json exists and has correct IDs
  • Settings mismatch: Use icp canister settings sync to apply icp.yaml settings to deployed canisters

Docker network problems:

  • Container won't start: Verify Docker is running (docker ps)
  • Windows: Ensure Docker Desktop is installed and running (required for all local networks)
  • Port conflicts: Change port in icp.yaml network configuration

Cycles depletion:

  • Canister frozen: Top-up with icp canister top-up --amount 2T <canister>
  • Low cycles warning: Monitor with icp canister status regularly
  • Prevent freezing: Increase freezing_threshold to 90 days (7776000 seconds)

Windows-specific:

  • Motoko build fails: Motoko requires WSL on Windows, install icp-cli inside WSL
  • Local network fails: Docker Desktop must be running
  • Rust works, Motoko doesn't: Expected behavior, use WSL for Motoko development

Controller lockout:

  • Warning system: CLI warns before removing self from controllers
  • Confirmation prompt: Review carefully, type 'y' only if intentional
  • Skip prompt: Use --force flag (dangerous, scripts only)
  • Already locked out: Contact other controllers to restore access

Large WASM:

  • Automatic chunking: Files >2MB upload automatically in chunks
  • No action needed: CLI handles chunking transparently
  • Optimize anyway: Use ic-wasm to reduce deployment cost

Network naming:

  • --mainnet removed: Use -e ic or -n ic instead
  • --ic removed: Use -e ic instead
  • Environment "mainnet" renamed: Update icp.yaml to use "ic"

Navigation

This skill provides quick-start guidance. For detailed information:

  • Recipe system, environment configuration, network configuration, YAML configuration, advanced canister settings, argument handling: See reference.md
  • Practical workflow examples (recipe-based projects, multi-environment deployment, Docker networks, identity management, cycles management): See examples.md
  • Security patterns, resource budgeting, platform-specific guidance, migration from dfx: See best-practices.md

Tool calls

Use tool calls to validate the latest CLI help and documentation.

CLI help (preferred when available locally):

{ "tool": "Shell", "command": "icp --help" }

{ "tool": "Shell", "command": "icp canister --help" }

{ "tool": "Shell", "command": "icp network --help" }

Docs pages (when the CLI isn't available or for citations):

Core documentation:

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/quickstart/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/tutorial/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/reference/cli/" }

Feature-specific guides:

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/guides/using-recipes/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/guides/creating-recipes/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/guides/managing-environments/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/guides/deploying-to-mainnet/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/guides/deploying-to-specific-subnets/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/guides/containerized-networks/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/guides/managing-identities/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/guides/tokens-and-cycles/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/guides/local-development/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/guides/installation/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/guides/creating-templates/" }

Concept documentation:

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/concepts/project-model/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/concepts/build-deploy-sync/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/concepts/environments/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/concepts/recipes/" }

Reference documentation:

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/reference/configuration/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/reference/canister-settings/" }

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/reference/environment-variables/" }

Migration:

{ "tool": "WebFetch", "url": "https://dfinity.github.io/icp-cli/0.1/migration/from-dfx/" }

Repo and releases:

{ "tool": "WebFetch", "url": "https://github.com/dfinity/icp-cli" }

{ "tool": "WebFetch", "url": "https://github.com/dfinity/icp-cli/releases" }

{ "tool": "WebFetch", "url": "https://github.com/dfinity/icp-cli-recipes" }

{ "tool": "WebFetch", "url": "https://forum.dfinity.org/t/icp-cli-announcements-and-feedback-discussion/60410" }

Responses

When replying to users:

  • Provide the smallest set of commands to accomplish the task.
  • Include flags only when necessary to meet the user's environment or identity needs.
  • Offer a short "verify" step (e.g., icp network status, icp canister status).
  • Cite official docs or the CLI help when explaining flags or behavior.
  • Ask for missing details only when required: environment/network, canister name, method, and args.
  • All recipe references MUST include a version (e.g., @dfinity/rust@v3.0.0).

Self-test prompts

Use these to sanity-check outputs:

  • "Start a local network and deploy" → quick start workflow + verify step
  • "Create project with Rust recipe" → icp new my-project + icp.yaml with @dfinity/rust@v3.0.0
  • "Call a canister method but I don't know args" → omit args to trigger prompt
  • "Deploy to staging" → use -e staging, avoid -n
  • "Deploy to IC mainnet" → use -e ic (NOT --mainnet)
  • "Check cycles and top up" → icp cycles balance -n ic + icp canister top-up --amount 2T <canister> -e ic
  • "Set up Docker-based network" → Docker workflow in icp.yaml
  • "Top up canister with 2 trillion cycles" → icp canister top-up --amount 2T <canister>
  • "Get my ledger account ID" → icp identity account-id
  • "View expanded project config" → icp project show
  • "Transfer cycles to a canister" → icp cycles transfer 2T <canister-id> -n ic
  • "Export my identity" → icp identity export my-identity > backup.pem
  • "Link HSM identity" → icp identity link hsm my-hsm --pkcs11-module <path> --key-id 01
  • "Switch default identity" → icp identity default my-identity (NOT icp identity use)

Examples

Create project with template and deploy locally

Commands:

# Create with template (interactive)
icp new my-project
cd my-project

# Or non-interactive with specific options
icp new my-project --subfolder hello-world \
  --define backend_type=rust \
  --define frontend_type=react \
  --define network_type=Default && cd my-project

# Start local network
icp network start -d
icp network status

# Deploy (builds automatically)
icp deploy

# Test
icp canister call backend greet '("World")'

# View expanded config (see what recipes generated)
icp project show

For Motoko: use --define backend_type=motoko (requires WSL on Windows).

Custom project with recipe-based icp.yaml

# icp.yaml
canisters:
  - name: backend
    recipe:
      type: "@dfinity/rust@v3.0.0"
      configuration:
        package: backend

icp network start -d
icp deploy
icp canister call backend greet '("World")'

Multi-environment deployment (local → staging → IC mainnet)

Commands:

# 1. Develop and test locally
icp network start -d
icp deploy
icp canister status backend

# 2. Deploy to staging environment
icp deploy -e staging
icp canister status backend -e staging

# 3. Promote to IC mainnet
# IMPORTANT: Use -e ic (not --mainnet)
icp deploy -e ic
icp canister status backend -e ic

Environment-specific settings configured in icp.yaml:

canisters:
  - name: backend
    recipe:
      type: "@dfinity/rust@v3.0.0"
      configuration:
        package: backend

environments:
  - name: staging
    network: ic
    canisters: [backend]
    settings:
      backend:
        compute_allocation: 20

  - name: production
    network: ic
    canisters: [backend]
    settings:
      backend:
        compute_allocation: 50
        memory_allocation: 4294967296

Check cycles and top up (with human-readable amounts)

Commands:

# Check cycles balance
icp cycles balance -n ic

# Top up with human-readable amounts
icp canister top-up --amount 2T backend -e ic     # 2 trillion
icp canister top-up --amount 500m backend -e ic   # 500 million

# Transfer cycles (positional args: amount, receiver)
icp cycles transfer 1.5T rrkah-fqaaa-aaaaa-aaaaq-cai -n ic

# Check canister cycles
icp canister status backend -e ic

Supported formats: 1k, 1.5m, 2b, 4T, 1_000_000.

Get account ID and transfer tokens

Commands:

# Get your ledger AccountIdentifier
icp identity account-id
# Output: d4685b31b51450508aff0331584df7692a84467b680326f5c5f7d30ae711682f

# Transfer ICP tokens (positional args: amount, receiver)
icp token transfer 10.5 d4685b31b51450508aff0331584df7692a84467b680326f5c5f7d30ae711682f -n ic

# Check token balance
icp token balance -n ic

# ICRC-1 token (e.g., ckBTC)
icp token mxzaz-hqaaa-aaaar-qaada-cai balance -n ic

Sources

Core documentation:

Feature-specific guides:

Concept documentation:

Migration:

Repositories and releases:

Weekly Installs
16
Repository
jorgenbuilder/icp-skills
GitHub Stars
9
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn
Installed on
opencode11
codex10
gemini-cli10
claude-code9
antigravity8
github-copilot8