ICP Developer's Cookbook - DFX Command-Line Guide

A practical guide to using the DFX command-line tool for Internet Computer development, covering identity management, canister deployment, and token operations.

A comprehensive cookbook for developers working with the Internet Computer Protocol using the DFX command-line tool. This guide covers essential operations from identity management to deploying tokens on the ICP network.

Introduction to DFX

DFX is the primary command-line tool for creating, managing, and deploying dapps on the Internet Computer. Unlike other tools like ICP Ninja, DFX is the only tool that can manage application canisters, including adjusting settings, modifying controller lists, and topping up cycles balance.

Basic Usage

		dfx [subcommand] [flags]

Essential Subcommands

dfx new - Create new projects
dfx start/stop - Control local development environment
dfx deploy - Deploy canisters
dfx canister - Manage deployed canisters
dfx identity - Manage identities
dfx ledger - Interact with ledger canisters
dfx cycles - Manage cycles balance

Flags and Options

-h, --help - Display usage information
-v, --verbose - Enable verbose output
-q, --quiet - Suppress informational messages
--identity <identity> - Specify identity to use

Installation and Setup

Installing DFX

		# Install using the official installer
sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
 
# Verify installation
dfx --version
 
# Upgrade if needed
dfx upgrade

Environment Setup

		# Add to PATH if not automatically added
export PATH="$HOME/bin:$PATH"
 
# For local development, ensure Node.js 16+ is installed
node --version

Project Initialization

		# Create a new project with Motoko backend and React frontend
dfx new my_project --type=motoko --frontend=react
cd my_project
 
# Create project with Rust backend
dfx new my_project --type=rust --no-frontend
 
# Initialize npm dependencies
npm install

Identity Management

Creating Identities

		# Create a new identity
dfx identity new my_identity
 
# List all identities
dfx identity list
 
# Switch to an identity
dfx identity use my_identity
 
# Get current identity principal
dfx identity get-principal
 
# Rename an identity
dfx identity rename old_name new_name
 
# Remove an identity
dfx identity remove unwanted_identity

Identity Files Location

		# Default identity location
~/.config/dfx/identity/default/identity.pem
 
# Export identity for backup
dfx identity export my_identity > my_identity.pem
 
# Import identity
dfx identity import my_identity my_identity.pem

Local Development Workflow

Starting Local Environment

		# Start local replica with clean state
dfx start --clean --background
 
# Start with specific port configuration
dfx start --host 127.0.0.1:8000
 
# Check if replica is running
dfx ping
 
# Stop local environment
dfx stop

Project Structure

After running dfx new, your project structure looks like:

		my_project/
├── dfx.json          # Project configuration
├── src/
│   ├── my_project_backend/
│   │   └── main.mo   # Backend canister code
│   └── my_project_frontend/
│       ├── src/
│       └── package.json
├── package.json
└── README.md

Configuration File (dfx.json)

		{
  "canisters": {
    "my_project_backend": {
      "main": "src/my_project_backend/main.mo",
      "type": "motoko"
    },
    "my_project_frontend": {
      "dependencies": ["my_project_backend"],
      "frontend": {
        "entrypoint": "src/my_project_frontend/src/index.html"
      },
      "source": ["src/my_project_frontend/dist"],
      "type": "assets"
    }
  },
  "defaults": {
    "build": {
      "args": "",
      "packtool": ""
    }
  },
  "version": 1
}

Canister Deployment

Deploying to Local Network

		# Deploy all canisters
dfx deploy
 
# Deploy specific canister
dfx deploy my_project_backend
 
# Deploy with custom arguments
dfx deploy my_project_backend --argument '(variant { Init = record { greeting = "Hello ICP!" } })'
 
# Deploy to specific network
dfx deploy --network local

Manual Deployment Steps

		# Step 1: Create canister
dfx canister create my_project_backend
 
# Step 2: Build canister
dfx build my_project_backend
 
# Step 3: Install canister
dfx canister install my_project_backend
 
# Combined: Deploy (does all three steps)
dfx deploy my_project_backend

Canister Management

		# List deployed canisters
dfx canister list
 
# Get canister ID
dfx canister id my_project_backend
 
# Check canister status
dfx canister status my_project_backend
 
# Update canister settings
dfx canister update-settings my_project_backend --controller <principal>
 
# Stop a canister
dfx canister stop my_project_backend
 
# Start a canister
dfx canister start my_project_backend
 
# Delete a canister
dfx canister delete my_project_backend

Interacting with Canisters

Calling Canister Methods

		# Call query method (read-only)
dfx canister call my_project_backend get_greeting
 
# Call update method (state-changing)
dfx canister call my_project_backend set_greeting '("Hello World!")'
 
# Call with complex arguments
dfx canister call my_project_backend transfer '(record {
  to = record { owner = principal "abcde-fghij..." };
  amount = 1000000 : nat
})'
 
# Using specific identity
dfx canister call my_project_backend privileged_method --identity admin

Candid Interface

Every canister automatically provides a Candid web interface:

		# Get Candid interface URL
dfx canister info my_project_backend
 
# Example output:
# Candid: http://127.0.0.1:4943/?canisterId=abcde-fghij...&id=abcde-fghij...

Frontend Integration

		# Start frontend development server
npm start
 
# Frontend will be available at:
# http://localhost:8080/?canisterId=<frontend-canister-id>

Cycles Management

Checking Cycles Balance

		# Check cycles balance for current identity
dfx cycles balance
 
# Check balance for specific canister
dfx cycles balance --canister my_project_backend

Topping Up Cycles

		# Convert ICP to cycles (requires ICP in wallet)
dfx cycles convert 1.0  # Convert 1 ICP to cycles
 
# Redeem cycles coupon (if you have one)
dfx cycles redeem-faucet-coupon <coupon-code>
 
# Top up canister
dfx cycles top-up my_project_backend 1000000000000  # 1T cycles

Cycles Wallet

		# Create cycles wallet
dfx cycles wallet-create
 
# Get wallet ID
dfx cycles wallet-id
 
# Send cycles to another wallet
dfx cycles wallet-send <destination-wallet-id> 1000000000000

Ledger and Token Operations

Interacting with ICP Ledger

		# Check ICP balance
dfx ledger balance
 
# Transfer ICP
dfx ledger transfer <destination-account> --amount 1.0
 
# Get account identifier
dfx ledger account-id

Token Ledger Deployment

		# Download ICRC-1 ledger Wasm
export IC_VERSION=$(curl -s https://dashboard.internetcomputer.org/releases | grep -o '"ic_version_id":"[^"]*"' | cut -d'"' -f4)
curl -o icrc1-ledger.wasm.gz "https://download.dfinity.systems/ic/$IC_VERSION/canisters/ic-icrc1-ledger.wasm.gz"
gunzip icrc1-ledger.wasm.gz
 
# Download Candid interface
curl -o icrc1-ledger.did "https://raw.githubusercontent.com/dfinity/ic/$IC_VERSION/rs/rosetta-api/icrc1/ledger/ledger.did"
 
# Configure dfx.json for token ledger
{
  "canisters": {
    "token_ledger": {
      "type": "custom",
      "wasm": "icrc1-ledger.wasm",
      "candid": "icrc1-ledger.did"
    }
  }
}
 
# Deploy token ledger
dfx deploy token_ledger --argument "(variant {
  Init = record {
    token_symbol = "MYT";
    token_name = "My Token";
    minting_account = record { owner = principal "$(dfx identity get-principal)" };
    transfer_fee = 10000;
    metadata = vec {};
    initial_balances = vec {
      record {
        record { owner = principal "$(dfx identity get-principal)" };
        1000000000000 : nat
      }
    };
  }
})"

Troubleshooting Common Issues

Clock Synchronization Issues

		# Fix WSL clock sync issues
sudo hwclock -s
 
# Restart dfx
dfx stop
dfx start --clean

Port Conflicts

		# Check if ports are in use
lsof -i :8000
lsof -i :4943
 
# Specify custom ports
dfx start --host 127.0.0.1:8001

Canister Deployment Failures

		# Clear dfx state
rm -rf .dfx
 
# Reinstall canisters
dfx canister install --mode reinstall my_canister

Identity Issues

		# Reset to default identity
dfx identity use default
 
# Check identity file permissions
ls -la ~/.config/dfx/identity/default/

Advanced Workflows

Multi-Canister Projects

		# Deploy interdependent canisters
dfx deploy  # Deploys in dependency order
 
# Manual deployment order
dfx deploy dependency_canister
dfx deploy main_canister

Cross-Canister Calls

		# Call canister from another canister
dfx canister call main_canister call_other_canister

Logging and Debugging

		# Enable verbose logging
dfx deploy --verbose
 
# View canister logs
dfx canister logs my_canister
 
# Debug with trace logging
dfx build --trace

Mainnet Deployment

Prerequisites

Cycles wallet with sufficient balance
Production-ready canister code
Proper controller identities

Mainnet Commands

		# Switch to mainnet
export NETWORK=ic
 
# Deploy to mainnet
dfx deploy --network ic
 
# Check mainnet canister status
dfx canister --network ic status my_canister

Production Best Practices

		# Use production identities
dfx identity use production-admin
 
# Set proper controllers
dfx canister update-settings --network ic my_canister --controller <production-controller>
 
# Enable proper monitoring
# Set up logging and alerting

Resources and Further Reading

This cookbook is continuously updated with new DFX features and best practices. Check back regularly for the latest commands and workflows.