### Full Multi-Environment Setup Example

Source: https://cli.internetcomputer.org/0.2/guides/managing-environments

A comprehensive `icp.yaml` example demonstrating configurations for 'staging' and 'production' environments, including build steps, sync settings, and environment-specific canister settings.

```yaml
canisters:
  - name: frontend
    build:
      steps:
        - type: script
          commands:
            - npm run build
    sync:
      steps:
        - type: assets
          dir: dist

  - name: backend
    build:
      steps:
        - type: script
          commands:
            - cargo build --target wasm32-unknown-unknown --release
            - cp target/wasm32-unknown-unknown/release/backend.wasm "$ICP_WASM_OUTPUT_PATH"

environments:
  - name: staging
    network: ic
    canisters: [frontend, backend]
    settings:
      frontend:
        memory_allocation: 2gib
      backend:
        compute_allocation: 5
        reserved_cycles_limit: 5t
        environment_variables:
          API_ENV: "staging"

  - name: production
    network: ic
    canisters: [frontend, backend]
    settings:
      frontend:
        memory_allocation: 4gib
        freezing_threshold: 90d
      backend:
        compute_allocation: 20
        reserved_cycles_limit: 50t
        freezing_threshold: 90d
        environment_variables:
          API_ENV: "production"
```

--------------------------------

### Create, Build, Deploy, and Test a New Project

Source: https://cli.internetcomputer.org/0.2/quickstart

Guides through the essential steps: creating a new project with specified backend and frontend types, starting a local network, building and deploying the project, and calling a backend canister to verify functionality. Remember to stop the local network when finished.

```bash
# 1. Create a new project with Motoko backend + React frontend
icp new my-project --subfolder hello-world \
  --define backend_type=motoko \
  --define frontend_type=react \
  --define network_type=Default && cd my-project

# 2. Start a local network (runs in background)
icp network start -d

# 3. Build and deploy
icp deploy

# 4. Call your backend canister
icp canister call backend greet '("World")'

# 5. Stop the local network when done
icp network stop
```

--------------------------------

### Local Development Server Setup

Source: https://cli.internetcomputer.org/0.2/guides/local-development

Deploys only the backend canister and starts a local development server for the frontend. This approach is suitable for fast iteration with hot reloading.

```bash
icp deploy backend  # Only deploy backend
npm run dev         # Start your dev server
```

--------------------------------

### Example Dockerfile for ICP Network

Source: https://cli.internetcomputer.org/0.2/guides/containerized-networks

This Dockerfile outlines the basic setup for an ICP network container. It includes installing necessary software, creating a status directory, setting the stop signal, and copying a startup script.

```dockerfile
FROM ubuntu:22.04

# Install your ICP network implementation
RUN apt-get update && apt-get install -y curl
# ... install network software ...

# Create status directory
RUN mkdir -p /app/status

# Set stop signal if needed
STOPSIGNAL SIGTERM

# Copy startup script
COPY start-network.sh /app/start-network.sh
RUN chmod +x /app/start-network.sh

ENTRYPOINT ["/app/start-network.sh"]
```

--------------------------------

### Rust Build Recipe Example

Source: https://cli.internetcomputer.org/0.2/guides/creating-recipes

A Handlebars recipe for building Rust canisters, including compilation and optimization with ic-wasm. It requires `ic-wasm` to be installed.

```handlebars
{{! file: ./recipes/rust-example.hbs }}
{{! A recipe for building a rust canister }}
{{! `package: string` The package to build }}
{{! `shrink: boolean` Optimizes the wasm with ic-wasm }}

build:
  steps:
    - type: script
      commands:
        - cargo build --package {{ package }} --target wasm32-unknown-unknown --release
        - mv target/wasm32-unknown-unknown/release/{{ replace "-" "_" package }}.wasm "$ICP_WASM_OUTPUT_PATH"

    - type: script
      commands:
        - command -v ic-wasm >/dev/null 2>&1 || { echo >&2 'ic-wasm not found. To install ic-wasm, see https://github.com/dfinity/ic-wasm 
'; exit 1; }
        - ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "${ICP_WASM_OUTPUT_PATH}" metadata "cargo:version" -d "$(cargo --version)" --keep-name-section
        - ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "${ICP_WASM_OUTPUT_PATH}" metadata "template:type" -d "rust" --keep-name-section
        {{#if shrink}}
        - ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "${ICP_WASM_OUTPUT_PATH}" shrink --keep-name-section
        {{/if}}
```

--------------------------------

### Start Multiple Containerized Networks

Source: https://cli.internetcomputer.org/0.2/guides/containerized-networks

Start each of the independently configured containerized networks defined in your `icp.yaml`.

```bash
icp network start docker-dev
icp network start docker-test
```

--------------------------------

### Examples of Transferring Cycles

Source: https://cli.internetcomputer.org/0.2/guides/tokens-and-cycles

Examples demonstrating how to transfer large amounts of cycles using human-readable suffixes.

```bash
# Transfer 1 trillion cycles
icp cycles transfer 1T aaaaa-aa -n ic
```

```bash
# Transfer 500 million cycles
icp cycles transfer 500m xxxxx-xxxxx-xxxxx-xxxxx-cai -n ic
```

--------------------------------

### Minimal icp.yaml Example

Source: https://cli.internetcomputer.org/0.2/concepts/project-model

Defines canisters, their build steps, and output paths. This minimal example shows how to configure a canister build process.

```yaml
canisters:
  - name: hello
    build:
      steps:
        - type: script
          commands:
            - cargo build --target wasm32-unknown-unknown --release
            - cp target/wasm32-unknown-unknown/release/hello.wasm "$ICP_WASM_OUTPUT_PATH"
```

--------------------------------

### Networks vs Environments Example

Source: https://cli.internetcomputer.org/0.2/concepts/environments

Illustrates how multiple environments can target the same network with different configurations.

```text
Networks: local, ic
Environments: local, staging, production
                 ↓        ↓         ↓
              local      ic        ic
```

--------------------------------

### Containerized Network Configuration Example

Source: https://cli.internetcomputer.org/0.2/guides/containerized-networks

An example demonstrating various configuration options for setting up a managed containerized network, including port mapping, volumes, mounts, and environment variables.

```yaml
networks:
  - name: docker-local
    mode: managed
    image: ghcr.io/dfinity/icp-cli-network-launcher
    port-mapping:
      - "8000:4943"
    volumes:
      - icp-data:/data
    mounts:
      - "./config:/app/config:ro"  # Mount local config as read-only
    environment:
      - LOG_LEVEL=info
      - POCKET_IC_MUTE_SERVER=true
    rm-on-exit: false
    shm-size: 2147483648  # 2GB
```

--------------------------------

### Start the Containerized Network

Source: https://cli.internetcomputer.org/0.2/guides/containerized-networks

Use this command to start the ICP test network defined in your `icp.yaml`. This command pulls the Docker image if it's not already present and starts a container exposing the network on `http://localhost:8000`.

```bash
icp network start docker-local
```

--------------------------------

### Example Telemetry Record for `icp deploy`

Source: https://cli.internetcomputer.org/0.2/telemetry

This JSON structure represents the telemetry data recorded for the `icp deploy --mode install --environment production` command, detailing argument names, values (if constrained), and their source.

```json
[
  {"name": "mode", "value": "install", "source": "command-line"},
  {"name": "environment", "value": null, "source": "command-line"}
]
```

--------------------------------

### Verify Tool Installation

Source: https://cli.internetcomputer.org/0.2/tutorial

Confirms that the installed ICP CLI, ic-wasm, and mops are accessible and functioning.

```bash
icp --version
ic-wasm --version
mops --version
```

--------------------------------

### Start Local Network and Deploy Backend

Source: https://cli.internetcomputer.org/0.2/guides/local-development

Use these commands to start a local development network and deploy your backend canister. The dev server will automatically fetch new canister IDs on restart after `icp network stop`.

```bash
icp network start -d   # Start local network
icp deploy backend     # Deploy backend canister
npm run dev            # Start dev server (fetches IDs automatically)
```

--------------------------------

### Install Rust Toolchain and Target

Source: https://cli.internetcomputer.org/0.2/guides/installation

Installs the Rust compiler via rustup and adds the WebAssembly target for Internet Computer development.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-unknown-unknown
```

--------------------------------

### Build Phase: Asset Bundling Example

Source: https://cli.internetcomputer.org/0.2/concepts/build-deploy-sync

Use a script step to bundle static assets, typically for frontend applications, as part of the build process.

```yaml
build:
  steps:
    - type: script
      commands:
        - npm run build
```

--------------------------------

### Install ICP CLI and Motoko Toolchain

Source: https://cli.internetcomputer.org/0.2/quickstart

Installs the required ICP CLI and ic-wasm tools globally using npm. Also installs the Motoko package manager (ic-mops) for Motoko projects.

```bash
# icp-cli and ic-wasm (required)
npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm

# Motoko toolchain (for Motoko projects)
npm install -g ic-mops
```

--------------------------------

### Registry Recipe Source

Source: https://cli.internetcomputer.org/0.2/concepts/recipes

Example of using an official recipe from the DFINITY registry. The '@dfinity' prefix resolves to a specific GitHub repository.

```yaml
recipe:
  type: "@dfinity/rust@v3.0.0"
  configuration:
    package: my-crate
```

--------------------------------

### Build Phase: Pre-built WASM Example

Source: https://cli.internetcomputer.org/0.2/concepts/build-deploy-sync

Use a pre-built WASM file directly. An optional SHA256 hash can be provided for integrity checking.

```yaml
build:
  steps:
    - type: pre-built
      path: dist/canister.wasm
      sha256: abc123...  # Optional integrity check
```

--------------------------------

### Complete Configuration File with Conditionals

Source: https://cli.internetcomputer.org/0.2/guides/creating-templates

A comprehensive `cargo-generate.toml` example including exclusions and conditional file ignoring based on user choices.

```toml
[template]
name = "Full Stack ICP App"
description = "A complete ICP application with backend and frontend"
# Exclude files from the generated project
exclude = [
    ".git",
    "target",
    ".icp"
]

[placeholders]
backend_language = { type = "string", prompt = "Backend language?", choices = ["motoko", "rust"], default = "motoko" }
include_frontend = { type = "bool", prompt = "Include frontend?", default = true }
frontend_framework = { type = "string", prompt = "Frontend framework?", choices = ["vanilla", "react", "svelte"], default = "vanilla" }

# Conditional files based on selections
# Ignore Rust files when Motoko is selected
[conditional.'backend_language == "motoko"']
ignore = ["Cargo.toml", "src/backend/lib.rs"]

# Ignore Motoko files when Rust is selected
[conditional.'backend_language == "rust"']
ignore = ["src/backend/main.mo"]
```

--------------------------------

### Install Core ICP CLI Tools via npm

Source: https://cli.internetcomputer.org/0.2/guides/installation

Installs the main command-line interface for building and deploying canisters, along with the WebAssembly optimizer.

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

--------------------------------

### Start the New Migrated Canister

Source: https://cli.internetcomputer.org/0.2/guides/canister-migration

Once all settings are copied, start the new canister on the target subnet. The old canister remains stopped on its original subnet and can be managed separately.

```bash
icp canister start <target-id> -n ic
```

--------------------------------

### Start Custom Network with icp-cli

Source: https://cli.internetcomputer.org/0.2/guides/containerized-networks

Command to start your custom containerized ICP network using the `icp-cli` tool after configuring it in `icp.yaml`.

```bash
icp network start custom-network
```

--------------------------------

### Expand Recipe Configuration

Source: https://cli.internetcomputer.org/0.2/concepts/recipes

Example of a recipe usage and its expanded build steps. Recipes take configuration parameters and expand into full canister configurations.

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

```yaml
canisters:
  - name: backend
    build:
      steps:
        - type: script
          commands:
            - cargo build --package my-backend --target wasm32-unknown-unknown --release
            - cp target/wasm32-unknown-unknown/release/my_backend.wasm "$ICP_WASM_OUTPUT_PATH"
```

--------------------------------

### Install Motoko Language Toolchain via npm

Source: https://cli.internetcomputer.org/0.2/guides/installation

Installs the Motoko package manager (mops) for compiling Motoko code.

```bash
npm install -g ic-mops
```

--------------------------------

### Install ic-wasm via Homebrew

Source: https://cli.internetcomputer.org/0.2/guides/installation

Installs the ic-wasm tool using the Homebrew package manager on macOS or Linux.

```bash
brew install ic-wasm
```

--------------------------------

### Install icp-cli via Homebrew

Source: https://cli.internetcomputer.org/0.2/guides/installation

Installs the icp-cli tool using the Homebrew package manager on macOS or Linux.

```bash
brew install icp-cli
```

--------------------------------

### Rust Build Recipe Usage

Source: https://cli.internetcomputer.org/0.2/guides/creating-recipes

Example of how to use the Rust build recipe in an `icp.yaml` file, specifying the recipe type and configuration.

```yaml
# file: icp.yaml
canisters:
  - name: backend
    recipe:
      type: ./recipes/rust-example.hbs
      configuration:
        package: my-backend-crate
        shrink: true
```

--------------------------------

### Verify Docker is Running

Source: https://cli.internetcomputer.org/0.2/guides/containerized-networks

Ensure Docker is installed and running on your system before proceeding with containerized networks.

```bash
docker ps
```

--------------------------------

### Stop, Create, and Start Canister

Source: https://cli.internetcomputer.org/0.2/guides/canister-snapshots

Before creating a snapshot, the canister must be stopped. After creation, it can be restarted.

```bash
icp canister stop my-canister -e ic
icp canister snapshot create my-canister -e ic
icp canister start my-canister -e ic
```

--------------------------------

### Install ic-wasm via Shell Script

Source: https://cli.internetcomputer.org/0.2/guides/installation

Installs the ic-wasm tool using a shell script, suitable for macOS and Linux.

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/ic-wasm/releases/latest/download/ic-wasm-installer.sh | sh
```

--------------------------------

### Recipe with Metadata Usage Example

Source: https://cli.internetcomputer.org/0.2/guides/creating-recipes

Shows how to configure a canister to use a recipe that injects metadata, providing an array of name-value pairs in the `icp.yaml` file.

```yaml
# file: icp.yaml
canisters:
  - name: backend
    recipe:
      type: ./recipes/rust-example-metadata.hbs
      configuration:
        package: my-backend-crate
        metadata:
          - name: "crate:version"
            value: "1.0.0"
          - name: "build:profile"
            value: "release"
```

--------------------------------

### Install Motoko Toolchain via Shell Script

Source: https://cli.internetcomputer.org/0.2/guides/installation

Installs the Motoko package manager (mops) using a shell script. Requires Node.js and a package manager.

```bash
curl -fsSL cli.mops.one/install.sh | sh
```

--------------------------------

### Deploy Canisters to Mainnet

Source: https://cli.internetcomputer.org/0.2/guides/deploying-to-mainnet

Deploys your project's canisters to the Internet Computer mainnet. This command builds, creates, installs, and syncs your canisters.

```bash
icp deploy --environment ic
```

--------------------------------

### Install ic-wasm via PowerShell Script (Windows)

Source: https://cli.internetcomputer.org/0.2/guides/installation

Installs the ic-wasm tool using a PowerShell script for Windows environments.

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/ic-wasm/releases/latest/download/ic-wasm-installer.ps1 | iex"
```

--------------------------------

### Start Local Network

Source: https://cli.internetcomputer.org/0.2/guides/local-development

Starts the local Internet Computer network in detached mode. Use `icp network ping` to verify it is running.

```bash
icp network start -d
```

```bash
icp network ping
```

--------------------------------

### Find and View Container Logs

Source: https://cli.internetcomputer.org/0.2/guides/containerized-networks

When a container fails to start, use these bash commands to find the container ID and view its logs for troubleshooting.

```bash
# Find container ID
docker ps -a | grep icp-cli-network-launcher

# View logs
docker logs <container-id>
```

--------------------------------

### Post-Generation Hook Script Example

Source: https://cli.internetcomputer.org/0.2/guides/creating-templates

An example Rhai script in `post-generate.rhai` to perform actions after project generation, such as renaming directories based on user selections.

```rhai
// Rename a directory based on user selection
let backend = variable::get("backend_type");
if backend == "rust" {
    file::rename("rust-backend", "backend");
} else {
    file::rename("motoko-backend", "backend");
}
```

--------------------------------

### Local Managed Network Status Example

Source: https://cli.internetcomputer.org/0.2/guides/local-development

Example JSON output for a local managed network, detailing API endpoints and canister principals.

```json
{
  "managed": true,
  "api_url": "http://localhost:8000",
  "gateway_url": "http://localhost:8000",
  "candid_ui_principal": "be2us-64aaa-aaaaa-qaabq-cai",
  "proxy_canister_principal": "bd3sg-teaaa-aaaaa-qaaba-cai",
  "root_key": "308182..."
}
```

--------------------------------

### Configure Custom Network in icp.yaml

Source: https://cli.internetcomputer.org/0.2/guides/containerized-networks

Example configuration for `icp.yaml` to define and use your custom containerized ICP network.

```yaml
networks:
  - name: custom-network
    mode: managed
    image: my-icp-network
    port-mapping:
      - "8000:4943"
```

--------------------------------

### Start Docker Daemon on Linux

Source: https://cli.internetcomputer.org/0.2/guides/containerized-networks

If encountering a 'Cannot connect to Docker daemon' error, ensure the Docker daemon is running. Use this command on Linux systems.

```bash
sudo systemctl start docker  # Linux
```

--------------------------------

### Local File Recipe Source

Source: https://cli.internetcomputer.org/0.2/concepts/recipes

Example of using a project-specific recipe defined in a local file. This allows for custom build configurations within your project.

```yaml
recipe:
  type: ./recipes/my-template.hb.yaml
  configuration:
    param: value
```

--------------------------------

### Using Local and Git Templates

Source: https://cli.internetcomputer.org/0.2/guides/creating-templates

Demonstrates how to use custom templates from a local directory or a Git repository.

```bash
# From local directory
icp new my-project --path /path/to/my-template

# From Git repository
icp new my-project --git https://github.com/user/my-template
```

--------------------------------

### Typical Deployment Workflow

Source: https://cli.internetcomputer.org/0.2/guides/managing-environments

Illustrates a common development and deployment workflow, moving from local development to staging and then to production.

```bash
# 1. Develop locally
icp network start -d
icp build && icp deploy
# ... test changes ...

# 2. Deploy to staging
icp deploy --environment staging
# ... verify on staging ...

# 3. Deploy to production
icp deploy --environment production
```

--------------------------------

### Local Development Workflow with icp-cli

Source: https://cli.internetcomputer.org/0.2/migration/from-dfx

Steps to test your project locally after migrating to icp-cli. This includes starting the network, building, deploying, and calling a canister method.

```bash
icp network start -d
icp build
icp deploy
icp canister call my-canister test_method '()'
```

--------------------------------

### Get Status of Containerized Network with Dynamic Port

Source: https://cli.internetcomputer.org/0.2/guides/containerized-networks

After starting a network with dynamic port allocation, use this command to find out which host port Docker assigned to the container.

```bash
icp network status docker-local
# Shows: Port: 54321 (example)
```

--------------------------------

### Build Phase: Script Step Example

Source: https://cli.internetcomputer.org/0.2/concepts/build-deploy-sync

Use a script step to run shell commands for compilation and WASM output. The `ICP_WASM_OUTPUT_PATH` environment variable specifies where to place the final WASM file.

```yaml
build:
  steps:
    - type: script
      commands:
        - cargo build --target wasm32-unknown-unknown --release
        - cp target/wasm32-unknown-unknown/release/my_canister.wasm "$ICP_WASM_OUTPUT_PATH"
```

--------------------------------

### Provide Init Args from a File

Source: https://cli.internetcomputer.org/0.2/reference/configuration

Reference initialization arguments from a binary file using the `path` and `format` properties.

```yaml
init_args:
  path: ./args.bin
  format: bin
```

--------------------------------

### icp canister install

Source: https://cli.internetcomputer.org/0.2/reference/cli

Installs a WebAssembly (WASM) module to a canister. Supports various installation modes and argument formats.

```APIDOC
## `icp canister install`

Install a built WASM to a canister on a network

**Usage:** `icp canister install [OPTIONS] <CANISTER>`

###### **Arguments:**

* `<CANISTER>` — Name or principal of canister to target. When using a name an environment must be specified

###### **Options:**

* `-m`, `--mode <MODE>` — Specifies the mode of canister installation

  Default value: `auto`

  Possible values: `auto`, `install`, `reinstall`, `upgrade`

* `--wasm <WASM>` — Path to the WASM file to install. Uses the build output if not explicitly provided
* `--args <ARGS>` — Inline arguments, interpreted per `--args-format` (Candid by default)
* `--args-file <ARGS_FILE>` — Path to a file containing arguments
* `--args-format <ARGS_FORMAT>` — Format of the arguments

  Default value: `candid`

  Possible values:
  - `hex`:
    Hex-encoded bytes
  - `candid`:
    Candid text format
  - `bin`:
    Raw binary (only valid for file references)

* `-y`, `--yes` — Skip confirmation prompts, including the Candid interface compatibility check
* `-n`, `--network <NETWORK>` — Name or URL of the network to target, conflicts with environment argument
* `-k`, `--root-key <ROOT_KEY>` — The root key to use if connecting to a network by URL. Required when using `--network <URL>`
* `-e`, `--environment <ENVIRONMENT>` — Override the environment to connect to. By default, the local environment is used
* `--identity <IDENTITY>` — The user identity to run this command as
* `--proxy <PROXY>` — Principal of a proxy canister to route the management canister call through.
```

--------------------------------

### Sync Phase: Asset Upload Example

Source: https://cli.internetcomputer.org/0.2/concepts/build-deploy-sync

Configure asset synchronization to upload static files from a specified directory after the canister is deployed. This is common for frontend assets.

```yaml
sync:
  steps:
    - type: assets
      dir: dist
```

--------------------------------

### Equivalent Individual Commands for ICP Deploy

Source: https://cli.internetcomputer.org/0.2/concepts/build-deploy-sync

Understand the sequence of commands that `icp deploy` executes internally. This includes building, creating canisters, setting environment variables, syncing settings, installing WASM, and final sync operations.

```bash
icp build                         # 1. Build
icp canister create               # 2. Create (if needed)
# (canister env vars updated)     # 3. Set environment variables
# (canister settings updated)     # 4. Sync settings
icp canister install --mode auto  # 5. Install
icp sync                          # 6. Sync (if configured)
```

--------------------------------

### Status File JSON Example

Source: https://cli.internetcomputer.org/0.2/guides/containerized-networks

This JSON structure represents the required format for the status file that your container must write when the network is ready. It includes version, gateway port, and root key, with optional fields for PocketIC-based networks.

```json
{
  "v": "1",
  "gateway_port": 4943,
  "root_key": "308182301d060d2b0601040182dc7c0503010201060c2b0601040182dc7c05030201036100814c0e6ec71fab583b08bd81373c255c3c371b2e84863c98a4f1e08b74235d14fb5d9c0cd546d9685f913a0c0b2cc5341583bf4b4392e467db96d65b9bb4cb717112f8472e0d5a4d14505ffd7484b01291091c5f87b98883463f98091a0baaae",
  "instance_id": null,
  "config_port": null,
  "default_effective_canister_id": null
}
```

--------------------------------

### Using Subfolders for Multiple Templates

Source: https://cli.internetcomputer.org/0.2/guides/creating-templates

Illustrates how to organize multiple templates within a single repository and select a specific subfolder template using the `--subfolder` flag.

```bash
icp new my-project --git https://github.com/org/icp-templates --subfolder motoko-basic
```

--------------------------------

### Install Linux Dependencies for icp-cli

Source: https://cli.internetcomputer.org/0.2/guides/installation

Installs necessary system libraries for icp-cli on Ubuntu/Debian and Fedora/RHEL systems.

```bash
# Ubuntu/Debian
sudo apt-get install -y libdbus-1-3 libssl3 ca-certificates
# Fedora/RHEL
sudo dnf install -y dbus-libs openssl ca-certificates
```

--------------------------------

### Deploy a canister with raw binary arguments

Source: https://cli.internetcomputer.org/0.2/reference/cli

When deploying with raw binary arguments, use `--args-file` to specify the file and `--args-format bin` to indicate the format.

```bash
icp deploy my_canister --args-file ./args.bin --args-format bin
```

--------------------------------

### Start Migrated Canister

Source: https://cli.internetcomputer.org/0.2/guides/canister-migration

Start the canister after a successful ID migration to resume operation on the new subnet.

```bash
icp canister start my-canister -e ic
```

--------------------------------

### ICP Deploy Install Modes

Source: https://cli.internetcomputer.org/0.2/concepts/build-deploy-sync

Control how WASM code is installed on canisters using the `--mode` flag. Use 'auto' for default behavior, 'install' for new canisters only, 'upgrade' to preserve state, and 'reinstall' to clear all state.

```bash
icp deploy

icp deploy --mode install

icp deploy --mode upgrade

icp deploy --mode reinstall
```

--------------------------------

### Pre-built WASM Deployment Configuration

Source: https://cli.internetcomputer.org/0.2/guides/using-recipes

Use the `@dfinity/prebuilt` recipe for deploying a pre-built WebAssembly (WASM) module. Provide the path to the WASM file and its SHA256 hash.

```yaml
canisters:
  - name: my-canister
    recipe:
      type: "@dfinity/prebuilt@v2.0.0"
      configuration:
        path: ./my-canister.wasm
        sha256: d7c1aba0de1d7152897aeca49bd5fe89a174b076a0ee1cc3b9e45fcf6bde71a6
```

--------------------------------

### Create a New Project

Source: https://cli.internetcomputer.org/0.2/tutorial

Initializes a new project for a full-stack application using the ICP CLI. This command will prompt for template, backend language, and network type.

```bash
icp new my-project
```

--------------------------------

### Verify ICP CLI and ic-wasm Installation

Source: https://cli.internetcomputer.org/0.2/guides/installation

Checks if the icp-cli and ic-wasm tools are installed and accessible by printing their versions.

```bash
icp --version
ic-wasm --version
```

--------------------------------

### Install icp-cli via PowerShell Script (Windows)

Source: https://cli.internetcomputer.org/0.2/guides/installation

Installs the icp-cli tool using a PowerShell script for Windows environments.

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.ps1 | iex"
```

--------------------------------

### Provide Init Args as Inline Candid

Source: https://cli.internetcomputer.org/0.2/reference/configuration

Specify initialization arguments directly as a plain string in Candid format.

```yaml
init_args: "(record { owner = principal \"aaaaa-aa\" })"
```

--------------------------------

### Install icp-cli via Shell Script

Source: https://cli.internetcomputer.org/0.2/guides/installation

Installs the icp-cli tool using a shell script, suitable for macOS, Linux, and WSL.

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.sh | sh
```

--------------------------------

### Connect to Existing Network as Local

Source: https://cli.internetcomputer.org/0.2/concepts/environments

Configure the 'local' environment to connect to an existing network instead of managing one. Provide the URL and root key.

```yaml
networks:
  - name: local
    mode: connected
    url: http://192.168.1.100:8000
    root-key: <hex-encoded-root-key>
```

--------------------------------

### Deploy a canister with arguments from a file

Source: https://cli.internetcomputer.org/0.2/reference/cli

Use the `--args-file` option to specify a file containing Candid arguments for canister deployment.

```bash
icp deploy my_canister --args-file ./args.did
```

--------------------------------

### Download and Upload Snapshot

Source: https://cli.internetcomputer.org/0.2/guides/canister-migration

Download the created snapshot locally and then upload it to the target canister. This prepares the target canister to receive the state.

```bash
# Download the snapshot locally
icp canister snapshot download my-canister <snapshot-id> -o ./migration-snapshot -e ic

# Upload the snapshot to the target canister
icp canister snapshot upload <target-id> -i ./migration-snapshot -n ic
```

--------------------------------

### icp canister start

Source: https://cli.internetcomputer.org/0.2/reference/cli

Starts a canister on the specified network. This command targets a canister by its name or principal and can be configured with network and identity options.

```APIDOC
## `icp canister start`

Start a canister on a network

**Usage:** `icp canister start [OPTIONS] <CANISTER>`

###### **Arguments:**

* `<CANISTER>` — Name or principal of canister to target. When using a name an environment must be specified

###### **Options:**

* `-n`, `--network <NETWORK>` — Name or URL of the network to target, conflicts with environment argument
* `-k`, `--root-key <ROOT_KEY>` — The root key to use if connecting to a network by URL. Required when using `--network <URL>`
* `-e`, `--environment <ENVIRONMENT>` — Override the environment to connect to. By default, the local environment is used
* `--identity <IDENTITY>` — The user identity to run this command as
* `--proxy <PROXY>` — Principal of a proxy canister to route the management canister call through
```

--------------------------------

### List and Show Project State

Source: https://cli.internetcomputer.org/0.2/guides/local-development

Lists all configured canisters in the current environment. Shows the effective project configuration.

```bash
icp canister list
```

```bash
icp project show
```

--------------------------------

### Deploy to Staging Environment

Source: https://cli.internetcomputer.org/0.2/concepts/environments

Command to deploy using the 'staging' environment. Use the '-e' or '--environment' flag.

```bash
icp deploy -e staging
```

--------------------------------

### Set Environment-Specific Init Args

Source: https://cli.internetcomputer.org/0.2/guides/managing-environments

Provide different initialization arguments for canisters based on the deployment environment.

```yaml
canisters:
  - name: backend
    build:
      # ... build steps
    init_args: "(record { mode = \"production\" })"

environments:
  - name: staging
    network: ic
    canisters: [backend]
    init_args:
      backend: "(record { mode = \"staging\" })"
```

--------------------------------

### Motoko Canister Build Configuration

Source: https://cli.internetcomputer.org/0.2/guides/using-recipes

Use the `@dfinity/motoko` recipe for building Motoko canisters. Specify the main Motoko file in the configuration.

```yaml
canisters:
  - name: backend
    recipe:
      type: "@dfinity/motoko@v4.0.0"
      configuration:
        main: src/main.mo
```

--------------------------------

### Create Project with Define Flags

Source: https://cli.internetcomputer.org/0.2/tutorial

An alternative method to create a new project, bypassing interactive prompts by specifying template, backend, frontend, and network types using `--define` flags.

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

--------------------------------

### View Environment Configuration

Source: https://cli.internetcomputer.org/0.2/guides/managing-environments

List all configured environments using `icp environment list` or view the effective project configuration with `icp project show`.

```bash
# See all configured environments
icp environment list

# View the effective project configuration
icp project show
```

--------------------------------

### Pre-Upgrade Backup Workflow

Source: https://cli.internetcomputer.org/0.2/guides/canister-snapshots

A common workflow to create a snapshot before an upgrade for rollback purposes. Includes steps for creating, deploying, testing, and optionally cleaning up or restoring the snapshot.

```bash
# 1. Stop the canister and create a snapshot before upgrading
icp canister stop my-canister -e ic
icp canister snapshot create my-canister -e ic
# Note the snapshot ID from the output

# 2. Deploy the upgrade
icp deploy my-canister -e ic

# 3. Test the upgrade
icp canister call my-canister health_check -e ic

# 4a. If everything works, optionally clean up the snapshot
icp canister snapshot delete my-canister <snapshot-id> -e ic

# 4b. If something is wrong, stop the canister and restore the snapshot
icp canister stop my-canister -e ic
icp canister snapshot restore my-canister <snapshot-id> -e ic
icp canister start my-canister -e ic
```

--------------------------------

### Rust Canister Build Configuration

Source: https://cli.internetcomputer.org/0.2/guides/using-recipes

Use the `@dfinity/rust` recipe for building Rust canisters. Specify the package name in the configuration.

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

--------------------------------

### Deploy All Canisters

Source: https://cli.internetcomputer.org/0.2/concepts/canister-discovery

Run this command to deploy all canisters defined in your project. This is the recommended way to ensure canister environment variables are set correctly.

```bash
icp deploy
```

--------------------------------

### Get Account Identifier (ICRC-1 Format)

Source: https://cli.internetcomputer.org/0.2/guides/managing-identities

Displays the account identifier for the current identity using the ICRC-1 format.

```bash
icp identity account-id --format icrc1
```

--------------------------------

### Get Account Identifier for a Specific Identity

Source: https://cli.internetcomputer.org/0.2/guides/managing-identities

Retrieves the account identifier for a specified identity. Useful when managing multiple identities.

```bash
icp identity account-id --identity other-identity
```

--------------------------------

### Script Sync Step

Source: https://cli.internetcomputer.org/0.2/reference/configuration

Configures a sync step to execute shell commands after canister deployment, useful for post-deployment setup or configuration.

```yaml
sync:
  steps:
    - type: script
      commands:
        - echo "Post-deployment setup"
        - ./scripts/configure-canister.sh
```

--------------------------------

### Deploy and Access Frontend

Source: https://cli.internetcomputer.org/0.2/guides/local-development

Deploys all canisters and provides the URL to access the frontend served by the asset canister. The canister ID is shown in the deploy output.

```bash
icp network start -d
icp deploy
```

--------------------------------

### External Network Files

Source: https://cli.internetcomputer.org/0.2/concepts/project-model

References network configurations defined in separate YAML files. This helps organize complex network setups.

```yaml
networks:
  - networks/testnet1.yaml
  - networks/testnet2.yaml
```

--------------------------------

### Define Basic Environments in icp.yaml

Source: https://cli.internetcomputer.org/0.2/guides/managing-environments

Configure 'staging' and 'production' environments, specifying the network and canisters for each.

```yaml
canisters:
  - name: frontend
    build:
      # ... build steps
  - name: backend
    build:
      # ... build steps

environments:
  - name: staging
    network: ic
    canisters: [frontend, backend]

  - name: production
    network: ic
    canisters: [frontend, backend]
```

--------------------------------

### Check Network Status File

Source: https://cli.internetcomputer.org/0.2/guides/containerized-networks

If the network is unreachable after starting, verify that the network status file has been written by executing a command inside the container.

```bash
# The container should write status to the status directory
docker exec <container-id> cat /app/status/status.json
```

--------------------------------

### Configure Canister Build and Settings

Source: https://cli.internetcomputer.org/0.2/reference/canister-settings

Define canister build steps and default settings. Use this to specify compilation commands and resource allocations like compute, memory, and freezing thresholds.

```yaml
canisters:
  - name: backend
    build:
      steps:
        - type: script
          commands:
            - cargo build --target wasm32-unknown-unknown --release
            - cp target/wasm32-unknown-unknown/release/backend.wasm "$ICP_WASM_OUTPUT_PATH"
    settings:
      compute_allocation: 5
      memory_allocation: 2gib
      freezing_threshold: 30d
      reserved_cycles_limit: 5t
      wasm_memory_limit: 1gib
      wasm_memory_threshold: 512mib
      log_visibility: controllers
      log_memory_limit: 2mib
      environment_variables:
        ENV: "production"
        API_BASE_URL: "https://api.example.com"
```

--------------------------------

### Get Account Identifiers for Subaccounts

Source: https://cli.internetcomputer.org/0.2/guides/tokens-and-cycles

Obtain account identifiers for a specified subaccount. You can choose the output format as either `ledger` (default) or `icrc1`.

```bash
# Show account identifiers for a subaccount
icp identity account-id --of-subaccount 1

# Show the icrc1 format
icp identity account-id --of-subaccount 1 --format icrc1
```

--------------------------------

### Verify Build and Network Health Before Deployment

Source: https://cli.internetcomputer.org/0.2/guides/local-development

Before deploying, ensure your project builds successfully and the network is healthy.

```bash
# Verify the build succeeded
icp build
# Check network health
icp network ping
```

--------------------------------

### Reset Local Network State

Source: https://cli.internetcomputer.org/0.2/guides/local-development

Stop the current local network and start a new one to discard previous state. Redeploy your canisters afterward.

```bash
# Stop the current network
icp network stop

# Start a new network (previous state is discarded)
icp network start -d

then redeploy your canisters:
icp deploy
```

--------------------------------

### Configure Multiple Environments

Source: https://cli.internetcomputer.org/0.2/guides/deploying-to-mainnet

Sets up multiple deployment environments (e.g., staging, production) in the `icp.yaml` configuration file.

```yaml
environments:
  - name: staging
    network: ic
  - name: prod
    network: ic
```

--------------------------------

### Configure Managed Docker Network

Source: https://cli.internetcomputer.org/0.2/reference/configuration

Use the `image` field to run a managed network inside a Docker container. This example shows basic configuration.

```yaml
networks:
  - name: docker-local
    mode: managed
    image: ghcr.io/dfinity/icp-cli-network-launcher
    port-mapping:
      - "0:4943"
```

--------------------------------

### View Expanded Configuration

Source: https://cli.internetcomputer.org/0.2/concepts/recipes

Command to display the effective configuration after all recipes have been rendered. This helps in verifying the expanded build and sync steps.

```bash
icp project show
```

--------------------------------

### Mainnet Deployment Workflow

Source: https://cli.internetcomputer.org/0.2/guides/deploying-to-mainnet

A comprehensive bash script outlining the steps for deploying to the mainnet, including identity management, cycle conversion, and canister status checks.

```bash
# 1. Create a dedicated mainnet identity
icp identity new mainnet-deployer
icp identity default mainnet-deployer

# 2. Get your principal (your unique identifier) to receive ICP tokens
icp identity principal
# Output example: xxxxx-xxxxx-xxxxx-xxxxx-xxx
# Share this principal with the sender (exchange or another user)
# Note: If your exchange requires an account identifier instead, use: icp identity account-id

# 3. Verify ICP arrived
icp token balance -n ic
# Output: 10 ICP

# 4. Convert ICP to cycles
icp cycles mint --icp 5 -n ic

# 5. Verify your cycles balance
icp cycles balance -n ic
# Output: ~5T cycles

# 6. Deploy your project to mainnet
icp deploy -e ic

# 7. Monitor your canister's cycles
icp canister status my-canister -e ic

# 8. Top up if needed
icp canister top-up my-canister --amount 2T -e ic
```

--------------------------------

### Deploy to Specific Environment

Source: https://cli.internetcomputer.org/0.2/guides/deploying-to-mainnet

Deploys your project to a specified environment (e.g., staging or production).

```bash
icp deploy -e staging
```

```bash
icp deploy -e prod
```

--------------------------------

### List project environments

Source: https://cli.internetcomputer.org/0.2/reference/cli

Use the `icp environment list` command to display all environments defined within the current project.

```bash
icp environment list
```

--------------------------------

### Remote URL Recipe Source

Source: https://cli.internetcomputer.org/0.2/concepts/recipes

Example of using a recipe hosted at a remote URL. Always include the 'sha256' hash for security and integrity verification.

```yaml
recipe:
  type: https://example.com/recipes/custom.hb.yaml
  sha256: 17a05e36278cd04c7ae6d3d3226c136267b9df7525a0657521405e22ec96be7a
  configuration:
    param: value
```

--------------------------------

### Asset Canister Deployment Configuration

Source: https://cli.internetcomputer.org/0.2/guides/using-recipes

Use the `@dfinity/asset-canister` recipe for deploying frontend assets. Specify the directory containing the assets.

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

--------------------------------

### Sync Canister Settings from Configuration using CLI

Source: https://cli.internetcomputer.org/0.2/reference/canister-settings

Synchronize canister settings with the configuration defined in `icp.yaml` using the ICP CLI.

```bash
icp canister settings sync my-canister
```

--------------------------------

### Specify custom network launcher path

Source: https://cli.internetcomputer.org/0.2/reference/environment-variables

Sets the path to a custom network launcher binary. Useful for air-gapped environments or testing custom launcher versions.

```bash
export ICP_CLI_NETWORK_LAUNCHER_PATH=/path/to/icp-cli-network-launcher
```

--------------------------------

### icp.yaml with Build Commands for Asset Canister

Source: https://cli.internetcomputer.org/0.2/migration/from-dfx

Specifies build commands for an asset canister, including 'npm install' and 'npm run build', when using icp-cli.

```yaml
canisters:
  - name: frontend
    recipe:
      type: "@dfinity/asset-canister@v2.1.0"
      configuration:
        dir: dist
        build:
          - npm install
          - npm run build
```

--------------------------------

### Publish Template to GitHub

Source: https://cli.internetcomputer.org/0.2/guides/creating-templates

After pushing your template to a GitHub repository, users can reference it directly using this command to create new projects.

```bash
icp new my-project --git https://github.com/username/my-template
```

--------------------------------

### Get Canister IDs using dfx

Source: https://cli.internetcomputer.org/0.2/migration/from-dfx

Retrieve canister IDs from your dfx project for persistent and ephemeral networks. Use the 'ic' network flag for mainnet IDs.

```bash
# dfx stores IDs in different locations depending on network type:
# - Persistent networks: canister_ids.json (project root)
# - Ephemeral networks: .dfx/<network>/canister_ids.json

# For mainnet/ic network:
dfx canister id frontend --network ic
dfx canister id backend --network ic
```