dfxmon CLI

Command-line interface for dfxmon - the universal file watcher and auto-deployment tool for Internet Computer (ICP) projects.

Overview

The dfxmon CLI is a client tool that communicates with the dfxmon canister deployed on the Internet Computer. It provides a seamless interface for managing file watching and automatic deployment of your ICP projects.

Installation

From crates.io

cargo install dfxmon-cli

From GitHub Releases

Download the latest binary for your platform from the GitHub Releases page.

Real-World Usage

Working with an Existing ICP Project

Assuming you have a typical ICP project structure:

my-dapp/
├── dfx.json
├── src/
│   ├── backend/
│   │   ├── main.mo          # Motoko backend
│   │   └── types.mo
│   ├── frontend/
│   │   ├── src/
│   │   │   ├── App.tsx      # React frontend
│   │   │   └── index.ts
│   │   └── package.json
│   └── shared/
│       └── types.did
└── canister_ids.json

Step 1: Register your project with dfxmon

cd my-dapp
dfxmon create my-dapp --dfx-json ./dfx.json --auto-deploy

Step 2: Start development with auto-deployment

dfxmon watch my-dapp

Now when you edit files, dfxmon automatically handles deployments:

• Edit src/backend/main.mo → Backend canister redeploys
• Edit src/frontend/src/App.tsx → Frontend assets redeploy
• Edit src/shared/types.did → Both canisters redeploy

Commands

dfxmon create

Create a new project in the dfxmon canister.

dfxmon create <PROJECT_NAME> [OPTIONS]

Options:
  --dfx-json <PATH>     Path to dfx.json file
  --auto-deploy         Enable automatic deployment
  --debounce-ms <MS>    Debounce delay in milliseconds [default: 1000]

dfxmon watch

Start watching a project for file changes.

dfxmon watch <PROJECT_NAME> [OPTIONS]

Options:
  --filter <FILTER>     Filter files to watch (e.g., "*.rs,*.mo")

dfxmon deploy

Manually trigger deployment of a project or specific canister.

dfxmon deploy <PROJECT_NAME> [OPTIONS]

Options:
  --canister <NAME>     Deploy specific canister only
  --force               Force deployment even if no changes detected

dfxmon status

Get the status of a project.

dfxmon status <PROJECT_NAME>

dfxmon list

List all projects managed by the dfxmon canister.

dfxmon list

dfxmon history

View deployment history for a project.

dfxmon history <PROJECT_NAME> [OPTIONS]

Options:
  --limit <N>           Number of deployments to show [default: 10]

dfxmon settings

View or update global settings.

dfxmon settings [OPTIONS]

Options:
  --get                 Show current settings
  --max-deployments <N> Set max concurrent deployments
  --debounce <MS>       Set default debounce delay
  --notifications       Enable/disable notifications
  --log-level <LEVEL>   Set log level (debug, info, warn, error)

Configuration

Canister ID

The CLI comes with embedded canister IDs for both local and mainnet networks:

• Local: uxrrr-q7777-77774-qaaaq-cai (automatically used with --network local)
• Mainnet: yvfam-kiaaa-aaaag-aucfa-cai (automatically used with --network mainnet)

No configuration required! The CLI automatically selects the correct canister based on your network.

You can override the embedded IDs if needed:

1. Command line flag:

   dfxmon --canister-id your-custom-canister-id create my-project
   

2. Environment variable:

   export DFXMON_CANISTER_ID=your-custom-canister-id
   dfxmon create my-project
   

3. Configuration file (.dfxmon.toml in current directory or home):

   canister_id = "your-custom-canister-id"
   network = "local"
   

Network Configuration

The CLI supports convenient network shortcuts:

• --network local → http://localhost:4943 (default)
• --network mainnet or --network ic → https://ic0.app
• Custom URLs: --network https://your-custom-replica.com

Examples:

# Local development (default)
dfxmon create my-project

# Mainnet
dfxmon --network mainnet create my-project

# Custom network
dfxmon --network https://testnet.dfinity.network create my-project

Or set the network in configuration:

network = "mainnet"  # or "local", "ic", or custom URL

File Watching

When you run dfxmon watch, the CLI starts a local file watcher that monitors your project directory for changes. When changes are detected, it notifies the dfxmon canister, which then triggers the appropriate deployment.

Supported File Types

• Motoko: .mo files
• Rust: .rs files
• Frontend: .js, .ts, .jsx, .tsx, .html, .css, .scss
• Configuration: .json, .toml, .did
• Documentation: .md

Ignored Patterns

The following files and directories are automatically ignored:

• .dfx/ - DFX build artifacts
• target/ - Rust build artifacts
• node_modules/ - Node.js dependencies
• .git/ - Git repository files
• dist/, build/ - Build output directories
• Temporary files (*.tmp, *.swp, *~)

Examples

Multi-Canister Rust Project

Working on a DeFi project with multiple Rust canisters:

# Project structure:
# defi-dapp/
# ├── src/
# │   ├── token/src/lib.rs      # Token canister
# │   ├── exchange/src/lib.rs   # Exchange canister  
# │   ├── governance/src/lib.rs # Governance canister
# │   └── frontend/src/App.tsx  # React frontend
# └── dfx.json

cd defi-dapp
dfxmon create defi-dapp --dfx-json ./dfx.json --auto-deploy
dfxmon watch defi-dapp

# Now edit src/token/src/lib.rs
# → Only the token canister rebuilds and redeploys
# → Other canisters remain untouched

Frontend-Heavy Development

Working on a social media dapp with frequent UI changes:

# Focus only on frontend changes
dfxmon watch social-dapp --filter "*.tsx,*.css,*.js"

# Edit src/frontend/components/Feed.tsx
# → Frontend assets rebuild and redeploy instantly
# → Backend canisters stay running without interruption

Motoko Backend with TypeScript Frontend

Typical full-stack development workflow:

# Project: chat-app
dfxmon create chat-app --dfx-json ./dfx.json --auto-deploy
dfxmon watch chat-app

# Terminal 1: dfxmon watching
# Terminal 2: Your editor

# Edit src/backend/main.mo (add new message type)
# → Backend redeploys, Candid interface updates
# → dfxmon detects interface change, triggers frontend rebuild

# Edit src/frontend/src/types.ts (update types)  
# → Frontend rebuilds with new types
# → Hot reload in browser shows changes immediately

Production Deployment Monitoring

Using dfxmon to track deployments on mainnet:

# Connect to mainnet dfxmon canister
export DFXMON_CANISTER_ID="rdmx6-jaaaa-aaaaa-aaadq-cai"
dfxmon --network ic list

# Check production deployment history
dfxmon --network ic history my-production-app --limit 20

# Monitor deployment status
dfxmon --network ic status my-production-app

Troubleshooting

Common Issues

1. "Canister ID not provided"

   • Set the canister ID via --canister-id, environment variable, or config file

2. "Failed to connect to replica"

   • Ensure your local replica is running (dfx start)
   • Check network configuration

3. "Permission denied"

   • Ensure you have the necessary permissions to interact with the canister
   • For local development, make sure you're using the correct identity

4. "File watching not working"

   • Check that you're in the correct project directory
   • Verify the project exists in the dfxmon canister (dfxmon list)

Debug Mode

Enable verbose logging for troubleshooting:

RUST_LOG=debug dfxmon watch my-project

Contributing

Contributions are welcome! Please see the main repository for contribution guidelines.

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Author

Created by Dedan Okware (softengdedan@gmail.com)

Links

• Main Repository
• Documentation
• Crates.io
• Issues